Skip to main content

MariaDB

@sqb/mariadb is the SQB adapter for MariaDB. It's built on top of mariadb, the official MariaDB Node.js connector.

Install​

npm install @sqb/mariadb mariadb

@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/mariadb registers it as a side effect — there's nothing else to wire up:

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

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

Under the hood, @sqb/mariadb's entry point imports @sqb/mariadb-dialect (which teaches @sqb/builder MariaDB's SQL syntax) and registers a MariadbAdapter instance with AdapterRegistry. MariadbAdapter reports driver: 'mariadb' and dialect: 'mariadb'.

Configuration​

host, port, user, password, and database from ClientConfiguration map directly onto the mariadb driver's own ConnectionConfig. Anything set in driverOptions is spread onto that same options object first, so it can carry any option the driver supports that isn't already covered by the standard fields:

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

namedPlaceholders, decimalAsNumber, bigIntAsNumber, and insertIdAsNumber are always forced to true by the adapter after driverOptions is applied (to keep numeric/id columns as plain JS numbers, matching @sqb/mysql's behavior), so they can't be overridden through driverOptions.

Feature notes​

  • Cursors: supported (features.cursor: true), backed by the driver's queryStream() — see Cursors & Streaming.
  • Schemas: not supported — MariaDB has no separate schema concept beyond the database itself.
  • RETURNING: MariaDB supports INSERT ... RETURNING and DELETE ... RETURNING natively, but has no UPDATE ... RETURNING. For updates, the dialect strips RETURNING and the adapter emulates it with a follow-up SELECT reusing the original WHERE clause.

Migrator support​

Supported since v6.0.8 — see Running migrations. MariaDB commits implicitly on DDL, so its migration adapter refuses transaction: 'run'/'migration' and dryRun (see Transactional runs). MariadbMigrationAdapter auto-creates the infoSchema database (CREATE DATABASE IF NOT EXISTS), runs a whole multi-statement script in one call, and serializes concurrent runs with GET_LOCK()/RELEASE_LOCK(). Unlike MySQL, MariaDB rejects a negative GET_LOCK timeout, so the adapter waits with a very large positive timeout instead.

See also​