{"id":43826,"library":"shadow-mysql","title":"shadow-mysql","description":"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.","status":"active","version":"2.0.9","language":"javascript","source_language":"en","source_url":"https://github.com/shadow88sky/shadow-mysql","tags":["javascript","shadow-mysql"],"install":[{"cmd":"npm install shadow-mysql","lang":"bash","label":"npm"},{"cmd":"yarn add shadow-mysql","lang":"bash","label":"yarn"},{"cmd":"pnpm add shadow-mysql","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime dependency: shadow-mysql wraps the mysql package for database connectivity. Not optional unless you provide a custom driver.","package":"mysql","optional":false}],"imports":[{"note":"CommonJS only; the package does not support ES modules. Pool is the only exported class.","wrong":"const shadowMysql = require('shadow-mysql'); const pool = new shadowMysql.Pool();","symbol":"Pool","correct":"const { Pool } = require('shadow-mysql');"},{"note":"Exported as a named function; use destructuring or `require('shadow-mysql').makeSQL`.","wrong":"","symbol":"makeSQL","correct":"const { makeSQL } = require('shadow-mysql')"},{"note":"Exposed as a named export for SQL injection prevention.","wrong":"const mysql = require('shadow-mysql'); mysql.escape(param); // works but not destructured","symbol":"escape","correct":"const { escape } = require('shadow-mysql')"}],"quickstart":{"code":"const { Pool, makeSQLSelect, escape } = require('shadow-mysql');\n\nconst pool = new Pool({\n  host: process.env.DB_HOST ?? 'localhost',\n  user: process.env.DB_USER ?? 'root',\n  password: process.env.DB_PASS ?? '',\n  database: process.env.DB_NAME ?? 'test',\n  multipleStatements: 'true'\n});\n\nasync function run() {\n  try {\n    const rows = await new Promise((resolve, reject) => {\n      pool.query('SELECT 1 AS result', (err, rows) => {\n        if (err) reject(err);\n        else resolve(rows);\n      });\n    });\n    console.log('Query result:', rows);\n\n    const sql = makeSQLSelect('users', ['id', 'name'], { active: 1 });\n    console.log('Generated SQL:', sql);\n\n    const safeParam = escape(\"O'Brien\");\n    console.log('Escaped:', safeParam);\n  } finally {\n    pool.end();\n  }\n}\nrun().catch(console.error);","lang":"javascript","description":"Demonstrates basic usage: creating a pool, performing a query via callback wrapped in Promise, generating a SELECT SQL with makeSQLSelect, and escaping user input."},"warnings":[{"fix":"Call `pool.end()` after all queries finish, or use a process handler like `process.on('exit', () => pool.end())`.","message":"Pool.end() is not documented but necessary to close connections gracefully. Failing to call it may leave dangling connections.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Wrap pool.query in a Promise manually (see quickstart). There is no built-in queryAsync.","message":"Promise-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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use `escape()` for dynamic values or switch to the mysql package's built-in placeholder `?` style with query()","message":"The `makeSQL` function uses placeholder syntax `@param@` which is non-standard; consider using `escape()` directly or switching to parameterized queries for better security.","severity":"deprecated","affected_versions":"*"},{"fix":"Always call `conn.release()` after commit or rollback, and ensure rollback on error.","message":"Transactions require manual beginTransaction/commit/rollback with callbacks; the package does not provide a higher-level abstraction. Missing release() after transaction will trigger warning log.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"search_vec":"'2.0.9':35 'ad':44 'altern':72 'async':17 'automat':48 'base':16 'basic':82 'build':26 'callback':66 'common':40 'compar':70 'connect':12,49 'detect':55 'e.g':19 'featur':89 'focus':80 'function':24 'generat':86 'getconnectionasync':21 'helper':23 'javascript':90 'knex':76 'lightweight':5 'like':73 'makesql':29 'makesqldelet':33 'makesqlinsert':31 'makesqlselect':30 'makesqlupd':32 'method':18 'misus':54 'mysql':3,6,41,60,79,93 'mysql2':74 'node.js':9,37 'npm':61 'offer':64 'oper':42 'orm':88 'packag':62 'pool':13,83 'promis':15,68 'promise-bas':14 'provid':11 'queri':28 'queryasync':20 'releas':50 'reli':57 'safeguard':45 'shadow':2,78,92 'shadow-mysql':1,77,91 'simplifi':39 'sql':27,85 'style':69 'target':36 'transact':53 'version':34 'warn':51 'without':87 'wrapper':7","created_at":"2026-06-05T17:01:40.093427+00:00","updated_at":"2026-06-05T17:01:40.093427+00:00","problems":[{"fix":"Use `const { Pool } = require('shadow-mysql');` instead.","cause":"Using ES module import (`import { Pool } from 'shadow-mysql'`) which is not supported; the package only provides CommonJS exports.","error":"TypeError: Pool is not a constructor"},{"fix":"Run `npm install shadow-mysql` in your project root.","cause":"Package not installed or running in a different directory.","error":"Cannot find module 'shadow-mysql'"},{"fix":"Add `return` before `connection.rollback(...)` to stop execution after error.","cause":"Attempting to send multiple HTTP responses within a single transaction callback because of missing return statements in error handling.","error":"Error: Can't set headers after they are sent."},{"fix":"Verify DB_HOST, DB_USER, DB_PASS, and DB_NAME environment variables or options passed to Pool constructor.","cause":"Incorrect database credentials or host not allowed.","error":"ER_ACCESS_DENIED_ERROR: Access denied for user '...'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/shadow88sky/shadow-mysql#readme","github":"https://github.com/shadow88sky/shadow-mysql","docs":null,"changelog":null,"pypi":null,"npm":"shadow-mysql","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}