{"id":43320,"library":"mysql-plus","title":"mysql-plus","description":"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.","status":"active","version":"0.16.2","language":"javascript","source_language":"en","source_url":"https://github.com/nwoltman/node-mysql-plus","tags":["javascript","mysql","plus","database","auto","automatic","migration","schema","table"],"install":[{"cmd":"npm install mysql-plus","lang":"bash","label":"npm"},{"cmd":"yarn add mysql-plus","lang":"bash","label":"yarn"},{"cmd":"pnpm add mysql-plus","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"mysql-plus extends the mysql module, which must be present as its core dependency for connection pooling and query execution.","package":"mysql","optional":false}],"imports":[{"note":"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.","wrong":"const mysql = require('mysql');","symbol":"mysql","correct":"const mysql = require('mysql-plus');"},{"note":"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.","wrong":"","symbol":"PoolPlus","correct":"const pool = mysql.createPool({...});"},{"note":"defineTable is a method on a pool instance, not on the mysql module itself. It returns a MySQLTable instance used for CRUD operations.","wrong":"const table = mysql.defineTable('name', {...});","symbol":"defineTable","correct":"const table = pool.defineTable('name', { columns: {...} });"}],"quickstart":{"code":"const mysql = require('mysql-plus');\nconst db = mysql.createPool({\n  host: 'localhost',\n  user: process.env.DB_USER,\n  password: process.env.DB_PASS,\n  database: 'my_db'\n});\n\nconst userTable = db.defineTable('user', {\n  columns: {\n    id: db.ColTypes.bigint().unsigned().notNull().primaryKey().autoIncrement(),\n    email: db.ColTypes.varchar(255).notNull().unique(),\n    name: db.ColTypes.varchar(63).notNull()\n  }\n});\n\ndb.sync((err) => {\n  if (err) throw err;\n  userTable.insert({ email: 'test@example.com', name: 'Test' })\n    .then(result => console.log('Inserted ID:', result.insertId))\n    .catch(err => console.error(err));\n});\n","lang":"javascript","description":"Creates a pool, defines a user table with auto-migrating columns, syncs schema, and inserts a row."},"warnings":[{"fix":"Call db.sync() before using the table, typically in app startup.","message":"defineTable does not immediately create or alter the table; call db.sync() to apply schema changes.","severity":"gotcha","affected_versions":"all"},{"fix":"Use await pool.query(...) or pool.query(...).then() instead of pool.query(..., callback).","message":"mysql-plus v0.12.0 removed support for callback-style queries on pool; use promises or async/await.","severity":"deprecated","affected_versions":">=0.12.0"},{"fix":"Update column definitions to use chainable syntax: { columns: { id: db.ColTypes.bigint().unsigned().notNull() } }","message":"mysql-plus v0.10.0 changed the column definition API from object-based to chainable methods (e.g., db.ColTypes.integer().notNull()).","severity":"breaking","affected_versions":">=0.10.0"},{"fix":"npm install mysql","message":"The mysql module must be installed separately because mysql-plus lists it as a peer dependency.","severity":"gotcha","affected_versions":"all"},{"fix":"Use migration strategies like ALTER or DROP, or manually adjust schema.","message":"When using defineTable with an existing table, the schema must match exactly; otherwise sync will attempt to migrate, which may fail if incompatible changes exist.","severity":"gotcha","affected_versions":"all"},{"fix":"Use standard mysql connection options (host, user, password, database).","message":"mysql-plus v0.8.0 renamed `createConnection` options to match mysql's; old option names no longer work.","severity":"deprecated","affected_versions":">=0.8.0 <0.10.0"}],"env_vars":null,"search_vec":"'0.16.2':24 '6':71 'auto':40,82 'auto-migr':39 'automat':14,83 'chainabl':31 'client':5 'column':32 'compar':52 'current':20 'databas':81 'db.coltypes.bigint':36 'definit':17,34,65 'depend':73 'differenti':30 'e.g':35 'extend':8 'focus':62 'javascript':78 'key':29 'knex':54 'lighter':58 'migrat':19,41,67,84 'modul':12 'mysql':2,4,11,76,79 'mysql-plus':1 'node':70 'node.js':7 'notnul':38 'npm':28 'opinion':61 'packag':77 'plus':3,80 'popular':10 'promis':46 'queri':49 'regular':26 'releas':25 'requir':69 'schema':16,44,64,85 'sequel':56 'simplic':68 'stabl':21 'support':47 'tabl':15,43,86 'transact':51 'type':33 'unsign':37 'version':22","created_at":"2026-06-05T16:59:14.376656+00:00","updated_at":"2026-06-05T16:59:14.376656+00:00","problems":[{"fix":"Ensure the pool is created correctly: const db = mysql.createPool({...}); db.sync();","cause":"db.sync() was called before pool was fully initialized or the pool variable is undefined.","error":"TypeError: Cannot read property 'query' of undefined"},{"fix":"Call db.sync() first and check for errors: db.sync(err => { if(err) throw err; ... });","cause":"Attempting to use a defined table before calling db.sync() or the table was not created due to an earlier error.","error":"Error: ER_BAD_TABLE_NAME: Table 'my_table' doesn't exist"},{"fix":"Verify columns use correct ColTypes methods (e.g., db.ColTypes.varchar(255)) and include notNull when needed.","cause":"Using invalid column type or missing required properties in defineTable.","error":"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"},{"fix":"Use const mysql = require('mysql-plus'); and ensure version >=0.12.0 for promise support.","cause":"Importing 'mysql' instead of 'mysql-plus' or using an older version without promise support.","error":"TypeError: pool.query is not a function"},{"fix":"Check for duplicate column names in the columns object; remove duplicates.","cause":"Defining a column with the same name as an existing column during migration or duplicate definition in columns object.","error":"Error: ER_DUP_FIELDNAME: Duplicate column name 'id'"}],"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/nwoltman/node-mysql-plus#readme","github":"https://github.com/nwoltman/node-mysql-plus","docs":null,"changelog":null,"pypi":null,"npm":"mysql-plus","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}}