Skip to main content

MySQL

@sqb/mysql is the SQB adapter for MySQL. It's built on top of mysql2, a pure-JavaScript MySQL driver.

Install​

npm install @sqb/mysql mysql2

@sqb/connect and @sqb/builder are peer dependencies pulled in transitively if you already depend on them directly; otherwise install them alongside.

Registering the adapter​

Importing @sqb/mysql registers it as a side effect — there's nothing else to wire up:

import '@sqb/mysql';
import { SqbClient } from '@sqb/connect';

const client = new SqbClient({
  dialect: 'mysql', // or driver: 'mysql2'
  host: 'localhost',
  database: 'mydb',
  user: 'myuser',
  password: 'mypassword',
});

Under the hood, @sqb/mysql's entry point imports @sqb/mysql-dialect (which teaches @sqb/builder MySQL's SQL syntax) and registers a MysqlAdapter instance with AdapterRegistry. MysqlAdapter reports driver: 'mysql2' and dialect: 'mysql' — either can be used to select it via ClientConfiguration.driver/.dialect.

Configuration​

host, port, user, password, and database from ClientConfiguration map directly onto mysql2's own ConnectionOptions. Anything set in driverOptions is spread onto that same options object first, so it can carry any option mysql2 supports (e.g. ssl, charset) that isn't already covered by the standard fields:

new SqbClient({
  dialect: 'mysql',
  host: 'localhost',
  database: 'mydb',
  driverOptions: {
    charset: 'utf8mb4',
  },
});
note

namedPlaceholders and decimalNumbers are always forced to true by the adapter after driverOptions is applied, so they can't be overridden through driverOptions.

Feature notes​

  • Cursors: supported (features.cursor: true), backed by mysql2's row streaming — see Cursors & Streaming.
  • Schemas: not supported — MySQL has no separate schema concept beyond the database itself.
  • RETURNING: MySQL has no INSERT ... RETURNING/UPDATE ... RETURNING. The adapter emulates it with a follow-up SELECT — for inserts, by looking up the table's AUTO_INCREMENT column and matching on LAST_INSERT_ID(); for updates, by re-running the original WHERE clause.

Migrator support​

Supported since v6.0.8 — see Running migrations. MySQL commits implicitly on DDL, so its migration adapter refuses transaction: 'run'/'migration' and dryRun (see Transactional runs). MysqlMigrationAdapter auto-creates the infoSchema database (CREATE DATABASE IF NOT EXISTS), runs a whole multi-statement script in one call (multipleStatements is enabled on the migration connection), and serializes concurrent runs with GET_LOCK()/RELEASE_LOCK().

See also​