Registry / database / mysql-plus

mysql-plus

JSON →
library0.16.2jsnpmunverified

MySQL client for Node.js extending the popular mysql module with automatic table schema definition and migration. Current stable version is 0.16.2, released regularly on npm. Key differentiators: chainable column type definitions (e.g., db.ColTypes.bigint().unsigned().notNull()), auto-migration of table schemas, and promise support for queries and transactions. Comparable to knex or sequelize but lighter and more opinionated, focusing on schema definition and migration simplicity. Requires Node >=6 and depends on the mysql package.

database
npm install mysql-plus
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · MYSQL-PLUS
M
mysql-plus
databasejavascriptv0.16.2
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.

mysql
✓ const mysql = require('mysql-plus');
✗ const mysql = require('mysql');
mysql-plus extends the mysql module, so you must require 'mysql-plus' to get automatic migration and schema features. The returned object is compatible with mysql's API.
PoolPlus
✓ const pool = mysql.createPool({...});
The pool created by mysql-plus is a PoolPlus instance that extends mysql's Pool. It supports promisified queries and transactions out of the box.
defineTable
✓ const table = pool.defineTable('name', { columns: {...} });
✗ const table = mysql.defineTable('name', {...});
defineTable is a method on a pool instance, not on the mysql module itself. It returns a MySQLTable instance used for CRUD operations.

Creates a pool, defines a user table with auto-migrating columns, syncs schema, and inserts a row.

const mysql = require('mysql-plus'); const db = mysql.createPool({ host: 'localhost', user: process.env.DB_USER, password: process.env.DB_PASS, database: 'my_db' }); const userTable = db.defineTable('user', { columns: { id: db.ColTypes.bigint().unsigned().notNull().primaryKey().autoIncrement(), email: db.ColTypes.varchar(255).notNull().unique(), name: db.ColTypes.varchar(63).notNull() } }); db.sync((err) => { if (err) throw err; userTable.insert({ email: 'test@example.com', name: 'Test' }) .then(result => console.log('Inserted ID:', result.insertId)) .catch(err => console.error(err)); });
Debug
Known issues
gotchadefineTable does not immediately create or alter the table; call db.sync() to apply schema changes.
fix
Call db.sync() before using the table, typically in app startup.
affects: all
deprecatedmysql-plus v0.12.0 removed support for callback-style queries on pool; use promises or async/await.
fix
Use await pool.query(...) or pool.query(...).then() instead of pool.query(..., callback).
affects: >=0.12.0
breakingmysql-plus v0.10.0 changed the column definition API from object-based to chainable methods (e.g., db.ColTypes.integer().notNull()).
fix
Update column definitions to use chainable syntax: { columns: { id: db.ColTypes.bigint().unsigned().notNull() } }
affects: >=0.10.0
gotchaThe mysql module must be installed separately because mysql-plus lists it as a peer dependency.
fix
npm install mysql
affects: all
gotchaWhen using defineTable with an existing table, the schema must match exactly; otherwise sync will attempt to migrate, which may fail if incompatible changes exist.
fix
Use migration strategies like ALTER or DROP, or manually adjust schema.
affects: all
deprecatedmysql-plus v0.8.0 renamed `createConnection` options to match mysql's; old option names no longer work.
fix
Use standard mysql connection options (host, user, password, database).
affects: >=0.8.0 <0.10.0
Errors
Common errors & fixes
TypeError: Cannot read property 'query' of undefined
db.sync() was called before pool was fully initialized or the pool variable is undefined.
fix
Ensure the pool is created correctly: const db = mysql.createPool({...}); db.sync();
Error: ER_BAD_TABLE_NAME: Table 'my_table' doesn't exist
Attempting to use a defined table before calling db.sync() or the table was not created due to an earlier error.
fix
Call db.sync() first and check for errors: db.sync(err => { if(err) throw err; ... });
Error: ER_PARSE_ERROR: You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near
Using invalid column type or missing required properties in defineTable.
fix
Verify columns use correct ColTypes methods (e.g., db.ColTypes.varchar(255)) and include notNull when needed.
TypeError: pool.query is not a function
Importing 'mysql' instead of 'mysql-plus' or using an older version without promise support.
fix
Use const mysql = require('mysql-plus'); and ensure version >=0.12.0 for promise support.
Error: ER_DUP_FIELDNAME: Duplicate column name 'id'
Defining a column with the same name as an existing column during migration or duplicate definition in columns object.
fix
Check for duplicate column names in the columns object; remove duplicates.
Upgrade
Version history
0.16.2latest on npm
Audit
Dependencies
mysqlrequiredmysql-plus extends the mysql module, which must be present as its core dependency for connection pooling and query execution.
Agent activity
6 hits · last 30 days
node
6
Resources
githubhttps://github.com/nwoltman/node-mysql-plus ↗
packagemysql-plus ↗
homepagehttps://github.com/nwoltman/node-mysql-plus#readme ↗