MySQL Adapter

$pnpm add @datrix/adapter-mysql

Requires mysql2 as a peer dependency.

Requirements

• MySQL 8.0.14+ or MariaDB 10.5+ — the adapter relies on LATERAL joins and JSON_ARRAYAGG / JSON_OBJECT for relation population.
• Native foreign key constraints are fully supported and automatically managed by migrations.

Configuration

import { MySQLAdapter } from "@datrix/adapter-mysql"

new MySQLAdapter({
  host:     "localhost",  // database server hostname (default: "localhost")
  port:     3306,         // database server port (default: 3306)
  database: "mydb",       // database name
  user:     "root",       // login user
  password: "secret",     // login password

  // Alternative: provide a full connection string instead of individual fields
  // connectionString: "mysql://root:secret@localhost:3306/mydb"

  // SSL
  ssl: {
    rejectUnauthorized: true,
    ca:   "...",  // CA certificate (PEM)
    cert: "...",  // client certificate (PEM)
    key:  "...",  // client private key (PEM)
  },

  // Connection pool
  connectionLimit:    10,   // maximum number of connections (default: 10)
  queueLimit:         0,    // max queued requests when pool is full — 0 = unlimited
  waitForConnections: true, // wait when pool is exhausted instead of erroring

  // Timeouts (milliseconds)
  connectTimeout: 10000,  // time to wait when establishing a connection

  charset:  "utf8mb4",  // character set for the connection (default: "utf8mb4")
  timezone: "local",    // timezone for date/time columns (default: "local")
})

Populate strategies

Two strategies are selected automatically based on query depth and complexity:

• JSON Aggregation — default for single-level relations. Uses JSON_ARRAYAGG and JSON_OBJECT in subqueries — offloads mapping to the database.
• Batched IN Queries — used for deep nesting (depth > 1), high cardinality, or populate options like limit, offset, where, orderBy. Collects parent IDs and issues targeted WHERE id IN (...) queries, stitching results in Node.js memory.

limit/offset on a hasMany/manyToMany populate apply per parent record, not globally across the batch.

Migration

Migration operations map to native SQL DDL (CREATE TABLE, ALTER TABLE, CREATE INDEX, etc.).

DDL rollback warning: DDL statements trigger implicit commits in both MySQL and MariaDB. If a migration contains DDL operations and fails partway, the structural changes already executed cannot be rolled back. This is a MySQL/MariaDB limitation, not a Datrix limitation.

Known limitations

• DDL operations in migrations cannot be rolled back on failure (see above).
• It is strongly recommended to run the server with strict mode enabled (STRICT_ALL_TABLES or STRICT_TRANS_TABLES). Without it, MySQL/MariaDB silently truncates data or coerces types instead of raising errors.

Field type mapping