Registry / database / tangbao-he-db-helper

tangbao-he-db-helper

library1.0.24jsnpmunverified

MyBatis-style database helper for Node-RED that provides CRUD nodes, SQL mapper with template engine (dynamic parameters, conditionals, foreach loops), and multi-database support for MySQL (auto-installed mysql2) and SQLite (requires manual better-sqlite3 install). Current version 1.0.24 targets Node-RED 4.0+, Node.js 18+. Key differentiators: snake_case to camelCase mapping, runtime dynamic parameters via msg, and transaction support. Released under an unspecified license with no release cadence given; appears actively maintained for its niche but not widely used.

database

npm install tangbao-he-db-helper

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TANGBAO-HE-DB-HELP

tangbao-he-db-helper

databasejavascriptv1.0.24

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

tangbao-db-config

✓ Node-RED node type: tangbao-db-config (configure via Node-RED UI, not imported in JS modules)

✗ const config = require('tangbao-he-db-helper').config;

This is a Node-RED custom node, not a library for direct require/import. All nodes are registered via Node-RED's runtime and used through the editor UI.

tangbao-db-query

✓ Node-RED node type: tangbao-db-query (add node in flow editor)

✗ import { QueryNode } from 'tangbao-he-db-helper';

Nodes are used exclusively via Node-RED's visual programming interface; there are no JavaScript importable symbols.

tangbao-sql-mapper

✓ Node-RED config node type: tangbao-sql-mapper (configure in editor)

✗ const sqlMapper = require('tangbao-he-db-helper').SQLMapper;

SQL templates are managed as config nodes, not as code objects.

Shows how to install and use the tangbao-db-query node with dynamic SQL via msg.payload.

// No JavaScript API to import. Install as Node-RED node: // cd ~/.node-red && npm install tangbao-he-db-helper // Then in a Node-RED flow, drag 'tangbao-db-query' node, configure a database config node. // Sent msg with: msg.payload = { sql: 'SELECT * FROM users WHERE status = #{status}', params: { status: 1 } }; // Output is in msg.payload as array.

Debug

Known issues

gotchaSQLite support requires manual installation of 'better-sqlite3' package; it is not included as a dependency. If you use SQLite without installing better-sqlite3, the node will fail silently or error.

fix

Install better-sqlite3: npm install better-sqlite3

affects: >=1.0.0

gotchaThe package uses '${param}' for direct string replacement in SQL templates, which is a SQL injection risk if user input is used. This is only 'safe' when the parameter is a table name or column name that you control.

fix

Use '#{param}' for user-supplied values to use prepared statements; avoid '${param}' unless absolutely necessary and the value is sanitized.

affects: >=1.0.0

gotchaNode-RED 4.0+ required. Running on older Node-RED versions will cause node registration failures.

fix

Upgrade Node-RED to 4.0.0 or later: npm install node-red@latest

affects: >=1.0.0

gotchaThe node 'tangbao-db-query' expects msg.payload as fallback for parameters; if msg.payload contains non-object data (e.g., string), it may cause unexpected behavior.

fix

Ensure msg.payload is an object or undefined when using msg.params or msg.sql explicitly.

affects: >=1.0.0

gotchaDatabase connection credentials are stored in Node-RED credentials file (encrypted at rest), but the encryption key is stored in settings.js. Ensure both are secured.

fix

Use Node-RED's credentialSecret setting to encrypt sensitive data.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'better-sqlite3'

SQLite driver not installed manually.

fix

Run: cd ~/.node-red && npm install better-sqlite3

TypeError: Cannot read properties of undefined (reading 'config')

Attempted to use a database node without configuring a tangbao-db-config node first.

fix

Add a tangbao-db-config node to the flow and configure it with database credentials, then connect it to the tangbao-db-query or tangbao-db-crud node.

Error: SQLITE_ERROR: no such table: ...

SQLite database file does not contain the expected table, or the path is wrong.

fix

Verify the SQLite database file path in the config node and ensure the table exists. If the file is created automatically, it will be empty; run CREATE TABLE statements first.

Error: ER_ACCESS_DENIED_ERROR: Access denied for user '...'

MySQL credentials are incorrect or user lacks permissions.

fix

Check username, password, and host in the tangbao-db-config node; ensure the MySQL user has access to the specified database from the Node-RED host.

Upgrade

Version history

1.0.24latest on npm

Audit

Dependencies

mysql2requiredMySQL driver for MySQL support (auto-installed with this package)

better-sqlite3optionalSQLite driver - must be installed manually for SQLite support (not auto-installed)

Agent activity

18 hits · last 30 days

node