MySQL2
MySQL driver using mysql2 with connection pooling
Installation
pnpm add mysql2
Configuration
import { createClient } from "viborm/mysql2";
const client = createClient({
databaseUrl: "mysql://user:password@localhost:3306/database",
schema,
});
Options
| Option | Type | Description |
|---|---|---|
pool |
Pool |
Existing mysql2 pool instance |
options |
PoolOptions |
mysql2 pool configuration |
databaseUrl |
string |
MySQL connection URL |
namespace |
string |
MySQL database for VibORM-owned objects |
migrationNamespaceAttestation |
"non-redirecting" |
Caller assertion required for effectful migrations |
createClient refuses any other key with a ClientInitializationError that
names it.
URL and options together
databaseUrl fills only the keys it carries, and a key you set in options
wins over the same key in the URL. An option set to undefined counts as
absent, so an unset environment variable never erases a URL key. A URL without
a port leaves mysql2’s default (3306) unless options.port sets one. This lets
each tenant have its own URL while the password comes from a secret:
const client = createClient({
databaseUrl: `mysql://app@db.internal/${tenant}`,
options: { password: process.env.DB_PASSWORD },
schema,
});
URL credentials and the database path are percent-decoded, and URL query
options are preserved. sslmode=require, verify-ca, and verify-full enable
verified TLS. Weaker or unrecognized TLS URL settings (sslmode=prefer,
ssl-mode, sslaccept, …) are refused with a ClientInitializationError
that says which setting VibORM cannot honour. Use options.ssl for
certificate settings. A URL the parser cannot read is refused as
Driver "mysql2" could not parse its databaseUrl., with its details redacted
because they can contain the password. Typed commands use MySQL text protocol
with per-command date and exact-integer decoding, including supplied pools;
VibORM does not fill mysql2’s server prepared-statement cache.
Using Pool Options
import { createClient } from "viborm/mysql2";
const client = createClient({
options: {
host: "localhost",
port: 3306,
user: "root",
password: "password",
database: "mydb",
connectionLimit: 10,
},
schema,
});
Using Existing Pool
import { createPool } from "mysql2/promise";
import { createClient } from "viborm/mysql2";
const pool = createPool({
host: "localhost",
user: "root",
database: "mydb",
});
const client = createClient({
pool,
schema,
});
Namespace
namespace selects the MySQL database holding this driver’s tables, junctions,
indexes, and migration tracking table.
import { createClient } from "viborm/mysql2";
const db = createClient({
databaseUrl: "mysql://user:password@localhost:3306/app_dev",
namespace: "billing",
schema,
});
SELECT `user`.`id` FROM `billing`.`user` AS `user`
The target is resolved once, in this order:
- an explicit
namespace; - for a driver-created pool,
options.database; - for a driver-created pool, a non-empty database path in
databaseUrl; - otherwise unbound — SQL stays unqualified and is byte-for-byte what it was before this option existed.
options.database wins over the URL path like every other option, and an empty
URL path contributes neither a namespace nor a pool-database override. Whichever
source resolves the target, the driver-created pool’s default database is set
to that same value on a copy of your options — the object you passed in is
never mutated, and the databaseUrl is parsed once at construction and never
re-read, so the pool cannot be pointed somewhere the resolved target never saw.
Effectful migrations need an attestation
A resolved database says which qualifier VibORM emits. It does not prove that a
qualified database.table reference reaches that database — mysql2 is also an
ordinary Vitess/PlanetScale client, and a proxy can rewrite qualifiers while
emulating host, handshake, vendor, and server-version evidence.
VibORM performs no backend detection. It asks you instead:
const db = createClient({
databaseUrl: process.env.DATABASE_URL,
namespace: "billing",
migrationNamespaceAttestation: "non-redirecting",
schema,
});
| Work | Needs namespace |
Needs the attestation |
|---|---|---|
| Runtime queries | No (unbound is valid) | No |
| Offline generation | No | No |
| Admitted read-only live migration commands | Yes | No |
| Effectful or concurrency-stable live migration work | Yes | Yes |
Omission fails closed, and the value is never inferred from the driver class, URL, host, server version, handshake, or the resolved namespace. It is immutable across transactions, nested transaction views, and the pinned migration session.
reset no longer does nothing
MySQL reset previously emitted only foreign-key-check toggles, so the CLI reset
dropped nothing. That silent no-op is fixed: reset is now real, the CLI
confirmation names the target namespace, and effectful reset additionally
requires the attestation. An unattested driver now refuses loudly where it
used to succeed while doing nothing.
Portable migration artifacts
Generated MySQL artifacts stay database-relative, so one estate deploys to
app_dev, app_test, and app_prod unchanged. Execution establishes the
selected database on one private pinned migration session; live push/reset SQL
and tracking SQL stay explicitly qualified.
Unqualified raw SQL remains caller-owned and follows the connection’s default database — see Namespaces.
GeoPoint
MySQL2 is the reference full-tier MySQL provider for s.point(). It stores
POINT SRID 4326, binds longitude before latitude with an explicit axis-order
option, supports inclusive polygons and fixed-radius meter distance, and emits
one-field non-null SPATIAL INDEX declarations. The live contract covers
round trips, antimeridian polygons and holes, distance, index plans, and
migration convergence. MySQL draws polygon edges on the ellipsoid rather than
the sphere VibORM reads them on; see How each database reads a
polygon.
Transactions
MySQL2 supports full transactions with savepoints for nested transactions — see Transactions.
Limitations
- No
RETURNINGclause - VibORM refetches created rows (using the driver-reported insert id for auto-increment keys) - JSON columns return as strings and are parsed automatically
- Boolean values stored as
TINYINT(1) updateMany/deleteManywith a self-relation filter (e.g. filtering users by their ownmanager/reportsrelation) fails with MySQL error 1093: MySQL cannot reference the table being updated/deleted in a filter subquery. Workaround: select the matching ids first, then mutate withwhere: { id: { in: ids } }.