Registry / database / serverless-mysql

serverless-mysql

JSON →
library2.1.0jsnpmunverified

A wrapper for mysql2 that manages MySQL connections in serverless environments like AWS Lambda, Google Cloud Functions, and Azure Functions. Current stable version is 2.1.0, released regularly. It prevents connection exhaustion by monitoring and limiting concurrent connections, cleaning up zombie connections, and retrying with exponential backoff. Differentiators include built-in async/await support, simplified transactions, and optional SQL query logging for debugging. Ships TypeScript types and works with any standards-based MySQL server including RDS, Aurora, and Aurora Serverless.

databasedevops
npm install serverless-mysql
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · SERVERLESS-MYSQL
S
serverless-mysql
databasejavascriptv2.1.0
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.

default
✓ const mysql = require('serverless-mysql')({ config: {...} })
✗ import mysql from 'serverless-mysql'
The package exports a factory function that must be called with options. ESM import works but requires default import from the factory.
mysql
✓ import mysql from 'serverless-mysql'
✗ import { mysql } from 'serverless-mysql'
The default export is the factory function; named export 'mysql' does not exist. In TypeScript, use `import serverlessMysql from 'serverless-mysql'`.
ServerlessMySQL
✓ import type { ServerlessMySQL } from 'serverless-mysql'
✗ import { ServerlessMySQL } from 'serverless-mysql' (if used as value)
The type is exported for TypeScript usage only. The main export is a factory function, not a class.

Initializes the connection manager with environment variables, runs a parameterized query, and cleans up resources.

const mysql = require('serverless-mysql')({ config: { host : process.env.DB_HOST ?? 'localhost', database : process.env.DB_NAME ?? 'test', user : process.env.DB_USER ?? 'root', password : process.env.DB_PASS ?? '' } }); async function query() { let results = await mysql.query('SELECT * FROM users WHERE id = ?', [1]); console.log(results); await mysql.end(); return results; } query().catch(err => console.error(err));
Debug
Known issues
gotchaThe module must be initialized outside the handler function (global scope) to reuse connections across invocations. Initializing inside the handler will create new connections per request and cause connection leaks.
fix
Initialize `const mysql = require('serverless-mysql')({...})` at module scope, not inside the handler.
affects: >=1.0.0
gotchaCalling `mysql.end()` after each query is required to release the connection back to the pool. Forgetting to call `end()` will exhaust connections quickly.
fix
Always call `await mysql.end()` after finishing all queries in a handler invocation.
affects: >=1.0.0
breakingVersion 2.0.0 dropped Node.js 8 support and changed internal connection management. Existing code using `mysql.quit()` instead of `mysql.end()` will break.
fix
Use `mysql.end()` instead of deprecated `mysql.quit()`. Update to Node 10+.
affects: >=2.0.0 <3.0.0
deprecatedThe `mysql.quit()` method was deprecated in v2.0.0 and removed in v2.1.0. Using it will throw an error.
fix
Replace `mysql.quit()` with `mysql.end()`.
affects: >=2.1.0
gotchaIf `returnFinalSqlQuery` is enabled, the results object and error objects will have an extra `sql` property, which may conflict with existing code that iterates over result keys.
fix
Check for `sql` property in results if you iterate over keys, or disable the option if not needed.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Can't add new command when connection is in closed state
Query attempted on a connection that was already ended by a previous invocation's `mysql.end()` call.
fix
Ensure each handler invocation initializes the module once at global scope and only calls `mysql.end()` once per invocation.
TypeError: mysql.query is not a function
The factory function was not called, so the returned object is the factory itself, not the configured instance.
fix
Use `const mysql = require('serverless-mysql')({...})` with parentheses, not just `require('serverless-mysql')`.
TimeoutError: Connection lost: The server closed the connection.
Idle connection timed out due to default MySQL wait_timeout or too many zombie connections.
fix
Increase idle timeout or use `mysql.end()` to release connections promptly. Adjust `maxRetries` and `backoff` options.
Error: ER_CON_COUNT_ERROR: Too many connections
Serverless function instances exceeded the MySQL max_connections limit because connections were not released or managed properly.
fix
Call `mysql.end()` after each request, reduce `maxConcurrentQueries` option, or increase MySQL max_connections. Ensure initialization is outside the handler.
Upgrade
Version history
2.1.0latest on npm
Audit
Dependencies
mysql2requiredCore MySQL client library that serverless-mysql wraps for connection pooling and query execution.
Agent activity
22 hits · last 30 days
node
22
Resources
githubhttps://github.com/jeremydaly/serverless-mysql ↗
packageserverless-mysql ↗
homepagehttps://github.com/jeremydaly/serverless-mysql#readme ↗
serverless-mysql — npm install serverless-mysql · libregistry