@zmdb/mysql 1.0.0-beta.1

package/src/__fixtures__/mysql-8.4.11.json

@@ -0,0 +1,261 @@
+{
+  "provenance": {
+    "capturedOn": "2026-09-04",
+    "captureFormat": "filtered deterministic subset of mysql --batch --raw capture; every retained non-NULL catalog cell is text",
+    "image": "docker.io/library/mysql:8.4",
+    "imageCreated": "2026-07-27T22:08:26.634911873Z",
+    "imageDigest": "sha256:1d6b6a8fcee8ff758ff151d017f5203cd06792a0e698f0a593c9dfcb14609cf0",
+    "imageId": "bced325a4ab7aec848f4688371c7433351dcb5dba26fbcc29c67727d898ae5cb",
+    "schema": "zmdb430",
+    "server": {
+      "version": "8.4.11",
+      "versionComment": "MySQL Community Server - GPL",
+      "versionCompileMachine": "x86_64",
+      "versionCompileOs": "Linux"
+    }
+  },
+  "rows": {
+    "tables": [
+      {
+        "TABLE_SCHEMA": "zmdb430",
+        "TABLE_NAME": "accounts",
+        "TABLE_TYPE": "BASE TABLE",
+        "ENGINE": "InnoDB"
+      },
+      {
+        "TABLE_SCHEMA": "zmdb430",
+        "TABLE_NAME": "memberships",
+        "TABLE_TYPE": "BASE TABLE",
+        "ENGINE": "InnoDB"
+      },
+      {
+        "TABLE_SCHEMA": "zmdb430",
+        "TABLE_NAME": "posts",
+        "TABLE_TYPE": "BASE TABLE",
+        "ENGINE": "InnoDB"
+      }
+    ],
+    "columns": [
+      {
+        "TABLE_NAME": "accounts",
+        "ORDINAL_POSITION": "1",
+        "COLUMN_NAME": "id",
+        "IS_NULLABLE": "NO",
+        "DATA_TYPE": "bigint",
+        "COLUMN_TYPE": "bigint",
+        "CHARACTER_MAXIMUM_LENGTH": null,
+        "NUMERIC_PRECISION": "19",
+        "NUMERIC_SCALE": "0",
+        "COLUMN_DEFAULT": null,
+        "EXTRA": "auto_increment",
+        "GENERATION_EXPRESSION": ""
+      },
+      {
+        "TABLE_NAME": "accounts",
+        "ORDINAL_POSITION": "2",
+        "COLUMN_NAME": "email",
+        "IS_NULLABLE": "NO",
+        "DATA_TYPE": "varchar",
+        "COLUMN_TYPE": "varchar(255)",
+        "CHARACTER_MAXIMUM_LENGTH": "255",
+        "NUMERIC_PRECISION": null,
+        "NUMERIC_SCALE": null,
+        "COLUMN_DEFAULT": null,
+        "EXTRA": "",
+        "GENERATION_EXPRESSION": ""
+      },
+      {
+        "TABLE_NAME": "memberships",
+        "ORDINAL_POSITION": "1",
+        "COLUMN_NAME": "tenant_id",
+        "IS_NULLABLE": "NO",
+        "DATA_TYPE": "int",
+        "COLUMN_TYPE": "int",
+        "CHARACTER_MAXIMUM_LENGTH": null,
+        "NUMERIC_PRECISION": "10",
+        "NUMERIC_SCALE": "0",
+        "COLUMN_DEFAULT": null,
+        "EXTRA": "",
+        "GENERATION_EXPRESSION": ""
+      },
+      {
+        "TABLE_NAME": "memberships",
+        "ORDINAL_POSITION": "2",
+        "COLUMN_NAME": "user_id",
+        "IS_NULLABLE": "NO",
+        "DATA_TYPE": "int",
+        "COLUMN_TYPE": "int",
+        "CHARACTER_MAXIMUM_LENGTH": null,
+        "NUMERIC_PRECISION": "10",
+        "NUMERIC_SCALE": "0",
+        "COLUMN_DEFAULT": null,
+        "EXTRA": "",
+        "GENERATION_EXPRESSION": ""
+      },
+      {
+        "TABLE_NAME": "posts",
+        "ORDINAL_POSITION": "1",
+        "COLUMN_NAME": "id",
+        "IS_NULLABLE": "NO",
+        "DATA_TYPE": "int",
+        "COLUMN_TYPE": "int",
+        "CHARACTER_MAXIMUM_LENGTH": null,
+        "NUMERIC_PRECISION": "10",
+        "NUMERIC_SCALE": "0",
+        "COLUMN_DEFAULT": null,
+        "EXTRA": "auto_increment",
+        "GENERATION_EXPRESSION": ""
+      },
+      {
+        "TABLE_NAME": "posts",
+        "ORDINAL_POSITION": "2",
+        "COLUMN_NAME": "account_id",
+        "IS_NULLABLE": "NO",
+        "DATA_TYPE": "bigint",
+        "COLUMN_TYPE": "bigint",
+        "CHARACTER_MAXIMUM_LENGTH": null,
+        "NUMERIC_PRECISION": "19",
+        "NUMERIC_SCALE": "0",
+        "COLUMN_DEFAULT": null,
+        "EXTRA": "",
+        "GENERATION_EXPRESSION": ""
+      },
+      {
+        "TABLE_NAME": "posts",
+        "ORDINAL_POSITION": "3",
+        "COLUMN_NAME": "slug",
+        "IS_NULLABLE": "NO",
+        "DATA_TYPE": "varchar",
+        "COLUMN_TYPE": "varchar(120)",
+        "CHARACTER_MAXIMUM_LENGTH": "120",
+        "NUMERIC_PRECISION": null,
+        "NUMERIC_SCALE": null,
+        "COLUMN_DEFAULT": null,
+        "EXTRA": "",
+        "GENERATION_EXPRESSION": ""
+      }
+    ],
+    "statistics": [
+      {
+        "TABLE_NAME": "accounts",
+        "INDEX_NAME": "accounts_email_uq",
+        "NON_UNIQUE": "0",
+        "SEQ_IN_INDEX": "1",
+        "COLUMN_NAME": "email",
+        "EXPRESSION": null,
+        "INDEX_TYPE": "BTREE"
+      },
+      {
+        "TABLE_NAME": "accounts",
+        "INDEX_NAME": "PRIMARY",
+        "NON_UNIQUE": "0",
+        "SEQ_IN_INDEX": "1",
+        "COLUMN_NAME": "id",
+        "EXPRESSION": null,
+        "INDEX_TYPE": "BTREE"
+      },
+      {
+        "TABLE_NAME": "memberships",
+        "INDEX_NAME": "PRIMARY",
+        "NON_UNIQUE": "0",
+        "SEQ_IN_INDEX": "1",
+        "COLUMN_NAME": "user_id",
+        "EXPRESSION": null,
+        "INDEX_TYPE": "BTREE"
+      },
+      {
+        "TABLE_NAME": "memberships",
+        "INDEX_NAME": "PRIMARY",
+        "NON_UNIQUE": "0",
+        "SEQ_IN_INDEX": "2",
+        "COLUMN_NAME": "tenant_id",
+        "EXPRESSION": null,
+        "INDEX_TYPE": "BTREE"
+      },
+      {
+        "TABLE_NAME": "posts",
+        "INDEX_NAME": "posts_account_idx",
+        "NON_UNIQUE": "1",
+        "SEQ_IN_INDEX": "1",
+        "COLUMN_NAME": "account_id",
+        "EXPRESSION": null,
+        "INDEX_TYPE": "BTREE"
+      },
+      {
+        "TABLE_NAME": "posts",
+        "INDEX_NAME": "PRIMARY",
+        "NON_UNIQUE": "0",
+        "SEQ_IN_INDEX": "1",
+        "COLUMN_NAME": "id",
+        "EXPRESSION": null,
+        "INDEX_TYPE": "BTREE"
+      }
+    ],
+    "keyColumnUsage": [
+      {
+        "TABLE_NAME": "accounts",
+        "CONSTRAINT_NAME": "accounts_email_uq",
+        "ORDINAL_POSITION": "1",
+        "POSITION_IN_UNIQUE_CONSTRAINT": null,
+        "COLUMN_NAME": "email",
+        "REFERENCED_TABLE_NAME": null,
+        "REFERENCED_COLUMN_NAME": null
+      },
+      {
+        "TABLE_NAME": "accounts",
+        "CONSTRAINT_NAME": "PRIMARY",
+        "ORDINAL_POSITION": "1",
+        "POSITION_IN_UNIQUE_CONSTRAINT": null,
+        "COLUMN_NAME": "id",
+        "REFERENCED_TABLE_NAME": null,
+        "REFERENCED_COLUMN_NAME": null
+      },
+      {
+        "TABLE_NAME": "memberships",
+        "CONSTRAINT_NAME": "PRIMARY",
+        "ORDINAL_POSITION": "1",
+        "POSITION_IN_UNIQUE_CONSTRAINT": null,
+        "COLUMN_NAME": "user_id",
+        "REFERENCED_TABLE_NAME": null,
+        "REFERENCED_COLUMN_NAME": null
+      },
+      {
+        "TABLE_NAME": "memberships",
+        "CONSTRAINT_NAME": "PRIMARY",
+        "ORDINAL_POSITION": "2",
+        "POSITION_IN_UNIQUE_CONSTRAINT": null,
+        "COLUMN_NAME": "tenant_id",
+        "REFERENCED_TABLE_NAME": null,
+        "REFERENCED_COLUMN_NAME": null
+      },
+      {
+        "TABLE_NAME": "posts",
+        "CONSTRAINT_NAME": "posts_account_fkey",
+        "ORDINAL_POSITION": "1",
+        "POSITION_IN_UNIQUE_CONSTRAINT": "1",
+        "COLUMN_NAME": "account_id",
+        "REFERENCED_TABLE_NAME": "accounts",
+        "REFERENCED_COLUMN_NAME": "id"
+      },
+      {
+        "TABLE_NAME": "posts",
+        "CONSTRAINT_NAME": "PRIMARY",
+        "ORDINAL_POSITION": "1",
+        "POSITION_IN_UNIQUE_CONSTRAINT": null,
+        "COLUMN_NAME": "id",
+        "REFERENCED_TABLE_NAME": null,
+        "REFERENCED_COLUMN_NAME": null
+      }
+    ],
+    "referentialConstraints": [
+      {
+        "TABLE_NAME": "posts",
+        "CONSTRAINT_NAME": "posts_account_fkey",
+        "UNIQUE_CONSTRAINT_NAME": "PRIMARY",
+        "MATCH_OPTION": "NONE",
+        "UPDATE_RULE": "RESTRICT",
+        "DELETE_RULE": "CASCADE"
+      }
+    ]
+  }
+}

package/src/dialect.ts

@@ -0,0 +1,99 @@
+import {
+  defineSqlDialect,
+  type DatabaseCapabilities,
+  type PaginationTail,
+  type ResolvedDialectTraits,
+} from '@zmdb/sql';
+
+import { mysqlIntrospector } from './introspect.js';
+import { createMysqlMigrations } from './migrations.js';
+
+const OPERATOR_TOKEN = /^(?!.*--)[A-Za-z@<>=!~*&|?-]{1,4}$/;
+
+function acceptsOperator(operator: string): boolean {
+  if (operator === '#>' || operator === '#>>') return false;
+  return OPERATOR_TOKEN.test(operator) && !operator.includes('?');
+}
+
+function paginate({ limit, offset }: PaginationTail): string {
+  if (limit === undefined && offset !== undefined) {
+    return ` LIMIT 18446744073709551615 OFFSET ${String(offset)}`;
+  }
+  let text = '';
+  if (limit !== undefined) text += ` LIMIT ${String(limit)}`;
+  if (offset !== undefined) text += ` OFFSET ${String(offset)}`;
+  return text;
+}
+
+const traits: ResolvedDialectTraits = {
+  placeholder: 'positional',
+  quote: Object.freeze(['`', '`']),
+  paginate,
+  paginationRequiresOrder: false,
+  rowValueIn: true,
+  returning: Object.freeze({
+    insert: 'none',
+    upsert: 'none',
+    update: 'none',
+    delete: 'none',
+  }),
+  upsert: 'onDuplicateKey',
+  fts: 'match',
+  concat: 'function',
+  booleanNot: 'not',
+  types: Object.freeze({
+    serial: 'INT AUTO_INCREMENT',
+    integer: 'INT',
+    bigint: 'BIGINT',
+    numeric: 'DECIMAL',
+    text: 'TEXT',
+    varchar: 'VARCHAR',
+    boolean: 'TINYINT(1)',
+    timestamp: 'DATETIME(3)',
+    json: 'JSON',
+    jsonEnum: 'TEXT',
+  }),
+  paramLimit: 60000,
+  retryableCodes: Object.freeze([]),
+  acceptsOperator,
+  functions: true,
+  procedures: true,
+  tableFunctions: false,
+  vectorDistance: false,
+  spatialPredicates: false,
+};
+
+const capabilities: DatabaseCapabilities = {
+  returning: Object.freeze({
+    insert: false,
+    upsert: false,
+    update: false,
+    delete: false,
+  }),
+  transactionalDdl: false,
+  schemas: true,
+  sequences: false,
+  generatedColumns: true,
+  partialIndexes: false,
+  foreignKeys: true,
+  rowLevelSecurity: false,
+  streaming: false,
+  cancellation: false,
+};
+
+export const mysql = defineSqlDialect({
+  name: 'mysql',
+  family: 'mysql',
+  telemetrySystem: 'mysql',
+  traits,
+  capabilities,
+  migrations: createMysqlMigrations('mysql'),
+  introspector: mysqlIntrospector,
+  outbox: Object.freeze({
+    createTable: 'CREATE TABLE',
+    pendingIndex: 'full',
+    epochLiteral: "'1970-01-01 00:00:00.000'",
+    createdAtDefault: 'CURRENT_TIMESTAMP(3)',
+    boundedTextType: (length: number) => `VARCHAR(${String(length)})`,
+  }),
+});

package/src/driver.ts

@@ -0,0 +1,219 @@
+import { type ExecuteOptions, type SelectedDriver, type TransactionalDriver } from '@zmdb/orm';
+import { type CompiledQuery, type SqlDialect } from '@zmdb/sql';
+
+export interface MysqlResultHeader {
+  readonly affectedRows: number;
+  readonly insertId: number | string | bigint;
+  readonly warningStatus?: number;
+}
+
+export type MysqlQueryResult = readonly Readonly<Record<string, unknown>>[] | MysqlResultHeader;
+
+export type MysqlParameter =
+  | string
+  | number
+  | bigint
+  | boolean
+  | Date
+  | null
+  | Uint8Array
+  | MysqlParameter[]
+  | { readonly [key: string]: MysqlParameter };
+
+/**
+ * The mysql2/promise surface used by the adapter. It is deliberately structural:
+ * importing @zmdb/mysql does not resolve or load mysql2.
+ */
+export interface MysqlQueryable {
+  execute(sql: string, values?: MysqlParameter[]): Promise<readonly [unknown, readonly unknown[]]>;
+  /** Optional mysql2 text protocol for metadata statements that the prepared protocol rejects. */
+  query?(sql: string, values?: MysqlParameter[]): Promise<readonly [unknown, readonly unknown[]]>;
+}
+
+export interface MysqlConnection extends MysqlQueryable {
+  beginTransaction(): Promise<unknown>;
+  commit(): Promise<unknown>;
+  rollback(): Promise<unknown>;
+  release?(): void;
+}
+
+export interface MysqlPool extends MysqlQueryable {
+  getConnection(): Promise<MysqlConnection>;
+}
+
+export interface MysqlOptions {
+  /** Optional application-to-wire conversion applied before mysql2 receives a value. */
+  readonly mapParameter?: (value: unknown, index: number) => MysqlParameter;
+}
+
+export type MysqlExecutionResult =
+  | {
+      readonly kind: 'rows';
+      readonly rows: readonly Readonly<Record<string, unknown>>[];
+    }
+  | {
+      readonly kind: 'command';
+      readonly affectedRows: number;
+      readonly insertId: number | string | bigint;
+      readonly warningStatus?: number;
+    };
+
+export interface MysqlDriver<Name extends string = 'mysql'> extends TransactionalDriver<Name> {
+  readonly dialect: SqlDialect<Name>;
+  executeResult(query: CompiledQuery, options?: ExecuteOptions): Promise<MysqlExecutionResult>;
+}
+
+function isPool(client: MysqlQueryable): client is MysqlPool {
+  return typeof Reflect.get(client, 'getConnection') === 'function';
+}
+
+function isConnection(client: MysqlQueryable): client is MysqlConnection {
+  return (
+    typeof Reflect.get(client, 'beginTransaction') === 'function' &&
+    typeof Reflect.get(client, 'commit') === 'function' &&
+    typeof Reflect.get(client, 'rollback') === 'function'
+  );
+}
+
+function resultHeader(value: unknown): MysqlResultHeader {
+  if (value === null || typeof value !== 'object') {
+    throw new TypeError('mysql2 returned neither rows nor a result header');
+  }
+  const affectedRows = Reflect.get(value, 'affectedRows');
+  const insertId = Reflect.get(value, 'insertId');
+  const warningStatus = Reflect.get(value, 'warningStatus');
+  if (typeof affectedRows !== 'number' || !Number.isSafeInteger(affectedRows) || affectedRows < 0) {
+    throw new TypeError('mysql2 result header affectedRows must be a non-negative safe integer');
+  }
+  if (
+    (typeof insertId !== 'number' || !Number.isSafeInteger(insertId)) &&
+    typeof insertId !== 'string' &&
+    typeof insertId !== 'bigint'
+  ) {
+    throw new TypeError('mysql2 result header insertId must be a safe integer, string, or bigint');
+  }
+  if (
+    warningStatus !== undefined &&
+    (typeof warningStatus !== 'number' || !Number.isSafeInteger(warningStatus) || warningStatus < 0)
+  ) {
+    throw new TypeError('mysql2 result header warningStatus must be a non-negative safe integer');
+  }
+  return {
+    affectedRows,
+    insertId,
+    ...(warningStatus === undefined ? {} : { warningStatus }),
+  };
+}
+
+function isPlainRecord(value: object): value is Readonly<Record<string, unknown>> {
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function mysqlParameter(value: unknown, label: string): MysqlParameter {
+  if (
+    value === null ||
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'bigint' ||
+    typeof value === 'boolean' ||
+    value instanceof Date ||
+    value instanceof Uint8Array
+  ) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry, index) => mysqlParameter(entry, `${label}[${String(index)}]`));
+  }
+  if (typeof value === 'object' && isPlainRecord(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [key, mysqlParameter(entry, `${label}.${key}`)]),
+    );
+  }
+  throw new TypeError(`${label} is not a mysql2 execute parameter`);
+}
+
+function mapParameters(query: CompiledQuery, options: MysqlOptions | undefined): MysqlParameter[] {
+  const map = options?.mapParameter;
+  return query.parameters.map((value, index) =>
+    map === undefined ? mysqlParameter(value, `query parameter ${String(index + 1)}`) : map(value, index),
+  );
+}
+
+async function runTransaction<Name extends string, Result>(
+  dialect: SqlDialect<Name>,
+  connection: MysqlConnection,
+  options: MysqlOptions | undefined,
+  run: (driver: SelectedDriver<Name>) => Promise<Result>,
+): Promise<Result> {
+  await connection.beginTransaction();
+  const transactionDriver = createMysqlDriver(dialect, connection, options, true);
+  try {
+    const result = await run(transactionDriver);
+    await connection.commit();
+    return result;
+  } catch (error) {
+    await connection.rollback();
+    throw error;
+  }
+}
+
+function createMysqlDriver<Name extends string>(
+  dialect: SqlDialect<Name>,
+  client: MysqlQueryable,
+  options: MysqlOptions | undefined,
+  pinned: boolean,
+): MysqlDriver<Name> {
+  const driver: MysqlDriver<Name> = {
+    dialect,
+    async executeResult(query, executeOptions) {
+      const signal = executeOptions?.signal;
+      signal?.throwIfAborted();
+      const parameters = mapParameters(query, options);
+      const textQuery = /^\s*(?:SHOW|DESCRIBE)\b/iu.test(query.text) ? client.query : undefined;
+      const [result] =
+        textQuery === undefined
+          ? await client.execute(query.text, parameters)
+          : await textQuery.call(client, query.text, parameters);
+      signal?.throwIfAborted();
+      if (Array.isArray(result)) {
+        if (result.some(row => row === null || typeof row !== 'object' || Array.isArray(row))) {
+          throw new TypeError('mysql2 row results must contain objects');
+        }
+        return { kind: 'rows', rows: result };
+      }
+      return { kind: 'command', ...resultHeader(result) };
+    },
+    async execute(query, executeOptions) {
+      const result = await driver.executeResult(query, executeOptions);
+      return result.kind === 'rows' ? result.rows : [];
+    },
+    async transaction<Result>(run: (transactionDriver: SelectedDriver<Name>) => Promise<Result>): Promise<Result> {
+      if (pinned) {
+        if (!isConnection(client)) throw new TypeError('a pinned mysql transaction lost its connection');
+        return runTransaction(dialect, client, options, run);
+      }
+      if (isPool(client)) {
+        const connection = await client.getConnection();
+        try {
+          return await runTransaction(dialect, connection, options, run);
+        } finally {
+          connection.release?.();
+        }
+      }
+      if (!isConnection(client)) {
+        throw new TypeError('mysqlDriver.transaction requires a mysql2 pool or connection');
+      }
+      return runTransaction(dialect, client, options, run);
+    },
+  };
+  return driver;
+}
+
+export function mysqlFamilyDriver<Name extends string>(
+  dialect: SqlDialect<Name>,
+  client: MysqlQueryable,
+  options?: MysqlOptions,
+): MysqlDriver<Name> {
+  return createMysqlDriver(dialect, client, options, false);
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+import { type DatabaseVertical } from '@zmdb/orm';
+
+import { mysql } from './dialect.js';
+import { mysqlFamilyDriver, type MysqlDriver, type MysqlOptions, type MysqlQueryable } from './driver.js';
+
+export { mysql } from './dialect.js';
+export {
+  mysqlFamilyDriver,
+  type MysqlConnection,
+  type MysqlDriver,
+  type MysqlExecutionResult,
+  type MysqlOptions,
+  type MysqlParameter,
+  type MysqlPool,
+  type MysqlQueryable,
+  type MysqlQueryResult,
+  type MysqlResultHeader,
+} from './driver.js';
+export { mysqlFamilyIntrospector, mysqlIntrospector, mysqlSnapshot, type MysqlCatalogOverrides } from './introspect.js';
+export {
+  createMysqlMigrations,
+  mysqlFamilyMigrations,
+  type MysqlMigrationOverrides,
+  type MysqlTableDdlExtension,
+  type MysqlTableDdlHelpers,
+} from './migrations.js';
+
+export function mysqlDriver(client: MysqlQueryable, options?: MysqlOptions): MysqlDriver<'mysql'> {
+  return mysqlFamilyDriver(mysql, client, options);
+}
+
+export const mysqlVertical: DatabaseVertical<'mysql', MysqlQueryable, MysqlOptions> = Object.freeze({
+  dialect: mysql,
+  driver: mysqlDriver,
+});