shadow-mysql

library2.0.9jsnpmunverified

A lightweight MySQL wrapper for Node.js that provides connection pooling, promise-based async methods (e.g., queryAsync, getConnectionAsync), and helper functions for building SQL queries (makeSQL, makeSQLSelect, makeSQLInsert, makeSQLUpdate, makeSQLDelete). Version 2.0.9 targets Node.js and simplifies common MySQL operations while adding safeguards such as automatic connection release warnings and transaction misuse detection. It relies on the mysql npm package and offers both callback and promise styles. Compared to alternatives like mysql2 or knex, shadow-mysql focuses on basic pooling and SQL generation without ORM features.

database

npm install shadow-mysql

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SHADOW-MYSQL

shadow-mysql

databasejavascriptv2.0.9

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.

Pool

✓ const { Pool } = require('shadow-mysql');

✗ const shadowMysql = require('shadow-mysql'); const pool = new shadowMysql.Pool();

CommonJS only; the package does not support ES modules. Pool is the only exported class.

makeSQL

✓ const { makeSQL } = require('shadow-mysql')

Exported as a named function; use destructuring or `require('shadow-mysql').makeSQL`.

escape

✓ const { escape } = require('shadow-mysql')

✗ const mysql = require('shadow-mysql'); mysql.escape(param); // works but not destructured

Exposed as a named export for SQL injection prevention.

Demonstrates basic usage: creating a pool, performing a query via callback wrapped in Promise, generating a SELECT SQL with makeSQLSelect, and escaping user input.

const { Pool, makeSQLSelect, escape } = require('shadow-mysql'); const pool = new Pool({ host: process.env.DB_HOST ?? 'localhost', user: process.env.DB_USER ?? 'root', password: process.env.DB_PASS ?? '', database: process.env.DB_NAME ?? 'test', multipleStatements: 'true' }); async function run() { try { const rows = await new Promise((resolve, reject) => { pool.query('SELECT 1 AS result', (err, rows) => { if (err) reject(err); else resolve(rows); }); }); console.log('Query result:', rows); const sql = makeSQLSelect('users', ['id', 'name'], { active: 1 }); console.log('Generated SQL:', sql); const safeParam = escape("O'Brien"); console.log('Escaped:', safeParam); } finally { pool.end(); } } run().catch(console.error);

Debug

Known issues

gotchaPool.end() is not documented but necessary to close connections gracefully. Failing to call it may leave dangling connections.

fix

Call `pool.end()` after all queries finish, or use a process handler like `process.on('exit', () => pool.end())`.

affects: >=2.0.0

breakingPromise-based methods (e.g., queryAsync) are only available if you use the callback-style pool methods with a wrapper. Versions before 2.0 may have had different async behavior.

fix

Wrap pool.query in a Promise manually (see quickstart). There is no built-in queryAsync.

affects: >=2.0.0

deprecatedThe `makeSQL` function uses placeholder syntax `@param@` which is non-standard; consider using `escape()` directly or switching to parameterized queries for better security.

fix

Use `escape()` for dynamic values or switch to the mysql package's built-in placeholder `?` style with query()

affects: *

gotchaTransactions require manual beginTransaction/commit/rollback with callbacks; the package does not provide a higher-level abstraction. Missing release() after transaction will trigger warning log.

fix

Always call `conn.release()` after commit or rollback, and ensure rollback on error.

affects: *

Errors

Common errors & fixes

TypeError: Pool is not a constructor

Using ES module import (`import { Pool } from 'shadow-mysql'`) which is not supported; the package only provides CommonJS exports.

fix

Use `const { Pool } = require('shadow-mysql');` instead.

Cannot find module 'shadow-mysql'

Package not installed or running in a different directory.

fix

Run `npm install shadow-mysql` in your project root.

Error: Can't set headers after they are sent.

Attempting to send multiple HTTP responses within a single transaction callback because of missing return statements in error handling.

fix

Add `return` before `connection.rollback(...)` to stop execution after error.

ER_ACCESS_DENIED_ERROR: Access denied for user '...'

Incorrect database credentials or host not allowed.

fix

Verify DB_HOST, DB_USER, DB_PASS, and DB_NAME environment variables or options passed to Pool constructor.

Upgrade

Version history

2.0.9latest on npm

Audit

Dependencies

mysqlrequiredRuntime dependency: shadow-mysql wraps the mysql package for database connectivity. Not optional unless you provide a custom driver.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/shadow88sky/shadow-mysql ↗

packageshadow-mysql ↗

homepagehttps://github.com/shadow88sky/shadow-mysql#readme ↗