@rdlabo/workers-mysql 0.1.0-beta.pr48.sha371f5792ce8a

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rdlabo-dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# @rdlabo/workers-mysql
+
+MySQL and Hyperdrive infrastructure for Cloudflare Workers without a Hono dependency. Compose
+invocation-scoped primary/replica access, deadlock retries, optional Drizzle helpers, and Node.js
+migration/testing tools while the application keeps its schemas and credentials.
+
+The Worker must enable Node.js compatibility because `mysql2` uses Node.js networking APIs:
+
+```toml
+# wrangler.toml
+compatibility_flags = ["nodejs_compat"]
+```
+
+## Choose an entry point
+
+| Import                             | Responsibility                                                                  |
+| ---------------------------------- | ------------------------------------------------------------------------------- |
+| `@rdlabo/workers-mysql`            | Workers MySQL and Hyperdrive runtime, retry, write-result, and JST wire helpers |
+| `@rdlabo/workers-mysql/drizzle`    | Drizzle configuration and JST column helpers                                    |
+| `@rdlabo/workers-mysql/migrations` | Node.js migration and brownfield baseline helpers                               |
+| `@rdlabo/workers-mysql/testing`    | Local MySQL/Drizzle test database and fakes                                     |
+
+## Install
+
+```bash
+npm install @rdlabo/workers-mysql
+```
+
+`mysql2` is included as a direct dependency. Add `drizzle-orm` when using `/drizzle` or `/testing`:
+
+```bash
+npm install drizzle-orm
+```
+
+Keeping Drizzle as a peer gives the application and its schemas one type identity.
+
+The public connection types use Node.js declarations. `@types/node@>=20.19.43` is a required peer
+(also when deploying to Workers). TypeScript applications should add it directly so its global
+declarations are visible with strict package layouts, including pnpm:
+
+```sh
+npm install -D @types/node@20
+# pnpm users:
+pnpm add -D @types/node@20
+```
+
+Use the matching supported major for your tooling. Automatic peer installation alone may not expose
+these global declarations to the application's TypeScript compiler under pnpm.
+
+## Quick start
+
+Create the database inside each Worker invocation. In this fragment, `env` contains the application's
+Hyperdrive bindings and `schema` is its own Drizzle schema:
+
+```ts
+import { createHyperdriveDatabase } from '@rdlabo/workers-mysql';
+import { DRIZZLE_ORM_OPTIONS } from '@rdlabo/workers-mysql/drizzle';
+import { drizzle } from 'drizzle-orm/mysql2';
+
+const db = createHyperdriveDatabase({
+  primaryHyperdrive: env.PRIMARY,
+  replicaHyperdrive: env.REPLICA,
+  createOrm: (connection) => drizzle(connection, { schema, ...DRIZZLE_ORM_OPTIONS }),
+});
+```
+
+With `nodejs_compat` enabled, the package root is Workers-runtime-safe and does not load Drizzle or
+Node-only migration code.
+
+Fixed `+09:00` storage helpers are a MySQL wire contract. They do not follow IANA display timezones
+from [`@rdlabo/workers-timezone`](https://docs.rdlabo.dev/projects/workers-timezone/docs/readme).
+
+## Hono integration
+
+Hono middleware remains an adapter in `@rdlabo/workers-hono-kit/mysql`; the database package itself
+does not depend on Hono.
+
+```ts
+import { createContainerRuntime } from '@rdlabo/workers-hono-kit/mysql';
+```
+
+This adapter is available from Hono kit `0.12.0`. Install both packages:
+
+```sh
+npm install @rdlabo/workers-mysql @rdlabo/workers-hono-kit
+```
+
+## Documentation
+
+- [Runtime](https://docs.rdlabo.dev/projects/workers-mysql/docs/runtime) — request lifetime, primary/replica reads, and retry safety.
+- [Drizzle and dates](https://docs.rdlabo.dev/projects/workers-mysql/docs/drizzle) — schema ownership, optional peer, and fixed-JST storage.
+- [Migrations and testing](https://docs.rdlabo.dev/projects/workers-mysql/docs/tooling) — Node.js tooling and destructive test helpers.
+- [API](https://docs.rdlabo.dev/projects/workers-mysql/docs/api) — public exports by entry point.
+- [Migration](https://docs.rdlabo.dev/projects/workers-mysql/docs/migration) — kit compatibility imports.
+
+These guides describe this source revision. Use the matching release tag for an installed version.
+
+## Migrating from workers-hono-kit
+
+Kit `0.12.0` changes the import boundaries. Its old `/db` and DB-related `/testing` exports remain
+available as maintained compatibility paths with `@deprecated` notices; there is no planned removal.
+See [Migration](https://docs.rdlabo.dev/projects/workers-mysql/docs/migration) for the import map.

package/bin/db-baseline.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runBaselineCli } from '../dist/baseline-cli.js';
+
+await runBaselineCli();

package/dist/baseline-cli.d.ts

@@ -0,0 +1,2 @@
+/** Run the brownfield migration-baseline command. */
+export declare function runBaselineCli(): Promise<void>;

package/dist/baseline-cli.js

@@ -0,0 +1,47 @@
+import { createConnection } from 'mysql2/promise';
+import { baselineMigrations } from './migrate.js';
+import { resolveDbSecret } from './orm-config.js';
+function arg(name) {
+    const index = process.argv.indexOf(`--${name}`);
+    return index >= 0 ? process.argv[index + 1] : undefined;
+}
+/** Run the brownfield migration-baseline command. */
+export async function runBaselineCli() {
+    const migrationsFolder = arg('migrations') ?? process.env.MIGRATIONS_DIR ?? './drizzle';
+    const secret = resolveDbSecret();
+    const connectionOptions = secret
+        ? {
+            host: secret.host,
+            port: secret.port,
+            user: secret.username,
+            password: secret.password,
+            database: secret.dbname,
+        }
+        : {
+            host: process.env.DB_HOST ?? '127.0.0.1',
+            port: Number(process.env.DB_PORT ?? '3306'),
+            user: process.env.DB_USER ?? 'root',
+            password: process.env.DB_PASSWORD ?? 'root',
+            database: process.env.DB_NAME,
+        };
+    if (!connectionOptions.database) {
+        console.error('[db:baseline] DB_NAME (or DB_SECRET) is required.');
+        process.exitCode = 1;
+        return;
+    }
+    console.log('[db:baseline] database target configured.');
+    const db = await createConnection(connectionOptions);
+    await baselineMigrations({ db, migrationsFolder })
+        .then((result) => {
+        if (result.status === 'already-baselined') {
+            console.log(`[db:baseline] already baselined (${result.tag}, created_at=${result.when}). no-op.`);
+            return;
+        }
+        console.log(`[db:baseline] inserted baseline marker for ${result.tag} (created_at=${result.when}). ` +
+            '0000 is now recorded as applied; future migrations will run.');
+    }, (error) => {
+        console.error('[db:baseline] failed:', error instanceof Error ? error.message : error);
+        process.exitCode = 1;
+    })
+        .finally(() => db.end());
+}

package/dist/columns.d.ts

@@ -0,0 +1,38 @@
+/**
+ * SQL expression for `ON UPDATE CURRENT_TIMESTAMP` (the MySQL session clock).
+ * customType columns have no `.onUpdateNow()`, so pair this with `.$onUpdateFn(() => jstOnUpdateNow(fsp))`.
+ *
+ * @param fsp - optional fractional-seconds precision; when provided, emits `CURRENT_TIMESTAMP(fsp)`.
+ */
+export declare const jstOnUpdateNow: (fsp?: number) => import("drizzle-orm").SQL<unknown>;
+/** MySQL `timestamp` — pass-through. A `Date` is formatted as JST by mysql2 via the connection `timezone:'+09:00'`. */
+export declare const jstTimestamp: (name: string, opts?: {
+    fsp?: number;
+}) => import("drizzle-orm/mysql-core").MySqlCustomColumnBuilder<{
+    name: string;
+    dataType: "custom";
+    columnType: "MySqlCustomColumn";
+    data: string | Date;
+    driverParam: string | Date;
+    enumValues: undefined;
+}>;
+/** MySQL `datetime` — same pass-through policy as {@link jstTimestamp}. */
+export declare const jstDatetime: (name: string, opts?: {
+    fsp?: number;
+}) => import("drizzle-orm/mysql-core").MySqlCustomColumnBuilder<{
+    name: string;
+    dataType: "custom";
+    columnType: "MySqlCustomColumn";
+    data: string | Date;
+    driverParam: string | Date;
+    enumValues: undefined;
+}>;
+/** MySQL `date` — on INSERT/UPDATE, normalizes ISO / empty strings to `YYYY-MM-DD` (via `toDriver`). */
+export declare const jstDate: (name: string) => import("drizzle-orm/mysql-core").MySqlCustomColumnBuilder<{
+    name: string;
+    dataType: "custom";
+    columnType: "MySqlCustomColumn";
+    data: string | null;
+    driverParam: string | null;
+    enumValues: undefined;
+}>;

package/dist/columns.js

@@ -0,0 +1,38 @@
+/**
+ * Shared Drizzle column helpers. Removes the need for a thin `custom-types.ts` / `columns.ts` wrapper
+ * in each repo.
+ *
+ * @remarks
+ * `drizzle-orm` is a **peer** (the consumer resolves a single copy); this package does not bundle it. The
+ * return types are the `customType` inference as-is (`MySqlCustomColumnBuilder<…>`) with no `any`, so
+ * the column's semantic type (`string | Date`, etc.) propagates to the consumer table's `$inferSelect`.
+ *
+ * **Precondition (a single drizzle copy)**: Drizzle's `SQL` is a **nominal** type carrying a private
+ * field `shouldInlineParams`, so if the package and consumer resolve different copies of drizzle,
+ * `jstTimestamp(…).default(sql\`…\`)` fails with `TS2345: separate declarations of a private property
+ * 'shouldInlineParams'`. A direct `file:` link can nest a second copy of drizzle under the package.
+ * Pin `drizzle-orm` to the consumer's **own single copy** with tsconfig
+ * `paths` (see the "Drizzle column helpers" section of the README). The published package (a single
+ * copy) is already unified.
+ *
+ * **DEFAULT / ON UPDATE CURRENT_TIMESTAMP** is a server-side default (an INSERT / UPDATE that omits the
+ * column). The connection's `timezone:'+09:00'` ({@link hyperdriveConnectionOptions}) only applies when
+ * the **app binds a `Date`**. Do not conflate the two (see the `datetime-wire` / `drizzle-smoke` JST
+ * tests).
+ */
+import { sql } from 'drizzle-orm';
+import { customType } from 'drizzle-orm/mysql-core';
+import { jstDateParams, jstDatetimeParams, jstTimestampParams } from './jst.js';
+/**
+ * SQL expression for `ON UPDATE CURRENT_TIMESTAMP` (the MySQL session clock).
+ * customType columns have no `.onUpdateNow()`, so pair this with `.$onUpdateFn(() => jstOnUpdateNow(fsp))`.
+ *
+ * @param fsp - optional fractional-seconds precision; when provided, emits `CURRENT_TIMESTAMP(fsp)`.
+ */
+export const jstOnUpdateNow = (fsp) => fsp != null ? sql `(CURRENT_TIMESTAMP(${sql.raw(String(fsp))}))` : sql `(CURRENT_TIMESTAMP)`;
+/** MySQL `timestamp` — pass-through. A `Date` is formatted as JST by mysql2 via the connection `timezone:'+09:00'`. */
+export const jstTimestamp = (name, opts) => customType(jstTimestampParams(opts?.fsp))(name);
+/** MySQL `datetime` — same pass-through policy as {@link jstTimestamp}. */
+export const jstDatetime = (name, opts) => customType(jstDatetimeParams(opts?.fsp))(name);
+/** MySQL `date` — on INSERT/UPDATE, normalizes ISO / empty strings to `YYYY-MM-DD` (via `toDriver`). */
+export const jstDate = (name) => customType(jstDateParams())(name);

package/dist/connection.d.ts

@@ -0,0 +1,76 @@
+import type { Connection } from 'mysql2/promise';
+/** Minimal structural shape retained by the compatibility connection-lifecycle API. */
+export interface ExecutionContextLike {
+    waitUntil(promise: Promise<unknown>): void;
+}
+/**
+ * Minimal structural shape of a Cloudflare Hyperdrive binding.
+ *
+ * @remarks
+ * Declared structurally to avoid a dependency on `@cloudflare/workers-types`; any object with these
+ * connection fields satisfies it.
+ */
+export interface HyperdriveLike {
+    /** Database host to connect to. */
+    host: string;
+    /** Database user. */
+    user: string;
+    /** Database password. */
+    password: string;
+    /** Database name. */
+    database: string;
+    /** Database port. */
+    port: number;
+}
+/**
+ * Build mysql2 `createConnection` options from a Hyperdrive binding, applying the package defaults.
+ *
+ * @remarks
+ * Three defaults are applied and can each be overridden via `extra`:
+ *
+ * - `disableEval: true` — `eval` is unavailable in the Workers runtime, so the driver's eval-based
+ *   fast paths must be disabled.
+ * - `decimalNumbers: true` — return `DECIMAL`/`NEWDECIMAL` columns as JS `number` rather than
+ *   strings, so raw-SQL reads and Drizzle's inferred types align on a single numeric domain type.
+ *   This assumes no column's precision exceeds the JS safe-integer range.
+ * - `timezone: '+09:00'` — interpret and serialize JavaScript `Date` values as JST. This is a
+ *   mysql2 client-side conversion option; it does not issue `SET time_zone` or change the MySQL
+ *   session timezone. Non-JST deployments can override it via `extra: { timezone: '...' }`.
+ *
+ * @param hyperdrive - the Hyperdrive binding to derive connection fields from.
+ * @param extra - additional mysql2 options merged last, overriding the defaults above.
+ * @returns a plain options object to pass to mysql2 `createConnection`.
+ */
+export declare function hyperdriveConnectionOptions(hyperdrive: HyperdriveLike, extra?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Open primary and replica connections in parallel and run `fn` with them.
+ *
+ * Cloudflare Workers automatically cleans up connections created during an invocation. Calling
+ * `Connection.end()` is unnecessary and can race work registered with `waitUntil`. The `ctx`
+ * parameter remains for API compatibility and is intentionally not used for connection teardown.
+ *
+ * @typeParam T - resolved value produced by `fn`.
+ * @param hyperdrives - the primary and replica Hyperdrive bindings to connect to.
+ * @param ctx - the request execution context, retained for API compatibility.
+ * @param fn - callback invoked with the open `primary` and `replica` connections.
+ * @param connectionOptions - extra mysql2 options forwarded to {@link hyperdriveConnectionOptions}.
+ * @returns the value resolved by `fn`.
+ * @example
+ * ```ts
+ * const data = await withMysqlConnections(
+ *   { primary: env.PRIMARY, replica: env.REPLICA },
+ *   ctx,
+ *   async ({ primary, replica }) => {
+ *     const [rows] = await replica.query('SELECT 1');
+ *     return rows;
+ *   },
+ * );
+ * ```
+ */
+export declare function withMysqlConnections<T>(hyperdrives: {
+    primary: HyperdriveLike;
+    replica: HyperdriveLike;
+}, ctx: ExecutionContextLike, fn: (connections: {
+    primary: Connection;
+    replica: Connection;
+}) => Promise<T>, connectionOptions?: Record<string, unknown>): Promise<T>;

package/dist/connection.js

@@ -0,0 +1,67 @@
+import { createConnection } from 'mysql2/promise';
+import { MYSQL_TIMEZONE } from './jst.js';
+/**
+ * Build mysql2 `createConnection` options from a Hyperdrive binding, applying the package defaults.
+ *
+ * @remarks
+ * Three defaults are applied and can each be overridden via `extra`:
+ *
+ * - `disableEval: true` — `eval` is unavailable in the Workers runtime, so the driver's eval-based
+ *   fast paths must be disabled.
+ * - `decimalNumbers: true` — return `DECIMAL`/`NEWDECIMAL` columns as JS `number` rather than
+ *   strings, so raw-SQL reads and Drizzle's inferred types align on a single numeric domain type.
+ *   This assumes no column's precision exceeds the JS safe-integer range.
+ * - `timezone: '+09:00'` — interpret and serialize JavaScript `Date` values as JST. This is a
+ *   mysql2 client-side conversion option; it does not issue `SET time_zone` or change the MySQL
+ *   session timezone. Non-JST deployments can override it via `extra: { timezone: '...' }`.
+ *
+ * @param hyperdrive - the Hyperdrive binding to derive connection fields from.
+ * @param extra - additional mysql2 options merged last, overriding the defaults above.
+ * @returns a plain options object to pass to mysql2 `createConnection`.
+ */
+export function hyperdriveConnectionOptions(hyperdrive, extra) {
+    return {
+        host: hyperdrive.host,
+        user: hyperdrive.user,
+        password: hyperdrive.password,
+        database: hyperdrive.database,
+        port: hyperdrive.port,
+        disableEval: true,
+        decimalNumbers: true,
+        timezone: MYSQL_TIMEZONE,
+        ...extra,
+    };
+}
+/**
+ * Open primary and replica connections in parallel and run `fn` with them.
+ *
+ * Cloudflare Workers automatically cleans up connections created during an invocation. Calling
+ * `Connection.end()` is unnecessary and can race work registered with `waitUntil`. The `ctx`
+ * parameter remains for API compatibility and is intentionally not used for connection teardown.
+ *
+ * @typeParam T - resolved value produced by `fn`.
+ * @param hyperdrives - the primary and replica Hyperdrive bindings to connect to.
+ * @param ctx - the request execution context, retained for API compatibility.
+ * @param fn - callback invoked with the open `primary` and `replica` connections.
+ * @param connectionOptions - extra mysql2 options forwarded to {@link hyperdriveConnectionOptions}.
+ * @returns the value resolved by `fn`.
+ * @example
+ * ```ts
+ * const data = await withMysqlConnections(
+ *   { primary: env.PRIMARY, replica: env.REPLICA },
+ *   ctx,
+ *   async ({ primary, replica }) => {
+ *     const [rows] = await replica.query('SELECT 1');
+ *     return rows;
+ *   },
+ * );
+ * ```
+ */
+export async function withMysqlConnections(hyperdrives, ctx, fn, connectionOptions) {
+    void ctx;
+    const [primary, replica] = await Promise.all([
+        createConnection(hyperdriveConnectionOptions(hyperdrives.primary, connectionOptions)),
+        createConnection(hyperdriveConnectionOptions(hyperdrives.replica, connectionOptions)),
+    ]);
+    return fn({ primary, replica });
+}

package/dist/database.d.ts

@@ -0,0 +1,249 @@
+import type { Connection, Pool } from 'mysql2/promise';
+import type { HyperdriveLike } from './connection.js';
+/**
+ * Dual-connection data layer that separates reads from writes.
+ *
+ * @remarks
+ * The two sides of the database are deliberately handled differently:
+ *
+ * - Reads go to the **replica** as raw SQL (`QueryRunner.query`) by default, returning plain rows.
+ *   Hyperdrive-backed databases also expose `query()` for freshness-sensitive primary SELECTs.
+ * - Writes and transactions go to the **primary** through the Drizzle ORM for type safety, but only
+ *   via `write(fn)` / `transaction(fn)` — the raw query builder is never exposed. The builder is
+ *   awaited inside those methods, which removes a foot-gun: a Drizzle builder is a lazy thenable, so
+ *   a bare `return builder` would silently become a no-op.
+ *
+ * Both sides retry on `ER_LOCK_DEADLOCK`.
+ *
+ * This package deliberately avoids depending on the type identity of `drizzle-orm`: the consumer creates
+ * the ORM instance with its own copy of `drizzle-orm` and passes it in, and {@link Database} is
+ * generic over that ORM type (`TDrizzle`). This keeps the ORM's `MySqlTable`/`SQL` brands from
+ * clashing even when the package and consumer resolve separate copies of `drizzle-orm`.
+ */
+/**
+ * Minimal connection interface used for reads.
+ *
+ * @remarks
+ * A mysql2 `Connection` or `Pool` satisfies this structurally.
+ */
+export interface QueryRunner {
+    /**
+     * Run a parameterized SQL query.
+     *
+     * @param sql - the SQL text, with `?` placeholders for `params`.
+     * @param params - optional positional parameters.
+     * @returns the driver's raw result (typically `[rows, fields]`).
+     */
+    query(sql: string, params?: unknown[]): Promise<unknown>;
+}
+/**
+ * Extract the transaction-handle type that a Drizzle instance passes to its `.transaction(cb)`
+ * callback.
+ *
+ * @typeParam TDrizzle - the consumer's Drizzle ORM type.
+ */
+export type TxOf<TDrizzle> = TDrizzle extends {
+    transaction(cb: (tx: infer Tx) => Promise<unknown>): Promise<unknown>;
+} ? Tx : unknown;
+/**
+ * The read/write surface of the data layer.
+ *
+ * @typeParam TDrizzle - the consumer's Drizzle ORM type used for writes and transactions.
+ * @typeParam TTx - the transaction-handle type, inferred from `TDrizzle` by default.
+ */
+export interface Database<TDrizzle, TTx = TxOf<TDrizzle>> {
+    /**
+     * Run a raw SQL read against the replica. Hyperdrive-backed databases retry deadlocks and repeat
+     * the SELECT once on a fresh connection after mysql2 reports a fatal connection error.
+     *
+     * @typeParam T - the row shape.
+     * @param sql - the SQL text, with `?` placeholders for `params`.
+     * @param params - optional positional parameters.
+     * @returns the rows returned by the query.
+     */
+    read<T>(sql: string, params?: unknown[]): Promise<T[]>;
+    /**
+     * Run a single INSERT/UPDATE/DELETE against the primary, awaited with deadlock retry.
+     *
+     * @typeParam T - the value resolved by `fn`.
+     * @param fn - callback that receives the Drizzle ORM and returns the awaited write.
+     * @returns the value resolved by `fn`.
+     */
+    write<T>(fn: (dz: TDrizzle) => Promise<T>): Promise<T>;
+    /**
+     * Run multiple writes inside a single transaction; the whole transaction is retried on deadlock.
+     *
+     * @typeParam T - the value resolved by `fn`.
+     * @param fn - callback that receives the transaction handle and returns the awaited work.
+     * @returns the value resolved by `fn`.
+     */
+    transaction<T>(fn: (tx: TTx) => Promise<T>): Promise<T>;
+}
+/**
+ * A {@link Database} that opens its own connections.
+ *
+ * @remarks
+ * Used by variants that open connections internally. Lifecycle behavior depends on the backing
+ * implementation: pool-backed databases close their pool, while Hyperdrive-backed databases leave
+ * invocation-scoped connection cleanup to the Workers runtime.
+ *
+ * @typeParam TDrizzle - the consumer's Drizzle ORM type.
+ * @typeParam TTx - the transaction-handle type, inferred from `TDrizzle` by default.
+ */
+export interface DisposableDatabase<TDrizzle, TTx = TxOf<TDrizzle>> extends Database<TDrizzle, TTx> {
+    /**
+     * Release resources owned by the implementation. Hyperdrive-backed databases keep this method as
+     * a compatibility no-op; pool-backed databases use it to close their pool.
+     *
+     * @returns a promise that resolves after implementation-specific cleanup.
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * A Hyperdrive-backed database with an explicit primary query path.
+ *
+ * @remarks
+ * Use `query()` only for SELECTs that require read-after-write consistency or cannot use the
+ * configured replica. Fatal connection errors recreate the primary connection and repeat the
+ * SELECT at most once. Writes and transactions are never repeated for connection errors.
+ * Read-only transactions are serialized on a separately cached primary connection so their
+ * snapshot boundaries cannot mix with ordinary primary operations or with each other. Do not call
+ * `readTransaction()` recursively from its own callback.
+ *
+ * @typeParam TDrizzle - the consumer's Drizzle ORM type.
+ * @typeParam TTx - the transaction-handle type, inferred from `TDrizzle` by default.
+ */
+export interface HyperdriveDatabase<TDrizzle, TTx = TxOf<TDrizzle>> extends DisposableDatabase<TDrizzle, TTx> {
+    /**
+     * Run a raw SQL SELECT against the primary database.
+     *
+     * @typeParam T - the complete rows result type (for example, `User[]`).
+     * @param sql - the SQL text, with `?` placeholders for `params`.
+     * @param params - optional positional parameters.
+     * @returns the rows returned by the query, typed as `T`.
+     */
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<T>;
+    /**
+     * Run a repeatable-read, consistent snapshot on the primary database.
+     *
+     * @remarks
+     * The callback is repeated at most once on a fresh connection after a fatal connection error.
+     * This is safe only because the transaction is declared read-only. Use {@link transaction} for
+     * writes; write transactions are never repeated after connection loss. Calls are serialized on
+     * one dedicated connection, so recursive `readTransaction()` calls are not supported.
+     */
+    readTransaction<T>(fn: (reader: ReadTransaction<TTx>) => Promise<T>): Promise<T>;
+}
+/** Primary read-only transaction handles that share one consistent snapshot. */
+export interface ReadTransaction<TTx> {
+    /**
+     * The consumer's Drizzle transaction handle.
+     *
+     * @remarks
+     * Drizzle's type does not distinguish read-only transactions. MySQL enforces read-only mode at
+     * runtime; applications may expose a narrower SELECT-only facade when they need compile-time
+     * enforcement.
+     */
+    orm: TTx;
+    /** Run raw SQL on the same primary connection and snapshot. */
+    query: <T = unknown>(sql: string, params?: unknown[]) => Promise<T>;
+}
+/**
+ * Options for {@link createMysqlDatabase}.
+ *
+ * @typeParam TDrizzle - the consumer's Drizzle ORM type.
+ */
+export interface CreateMysqlDatabaseOptions<TDrizzle> {
+    /**
+     * The Drizzle ORM used for writes, created by the consumer with its own `drizzle-orm`
+     * (e.g. `drizzle(primary, { schema, ... })`).
+     */
+    orm: TDrizzle;
+    /** The connection used for reads (raw SQL). */
+    replica: QueryRunner;
+}
+/**
+ * Assemble a {@link Database} from an already-connected ORM and replica.
+ *
+ * @remarks
+ * The caller (typically the worker entry point) owns creating the connections and the ORM, and is
+ * responsible for closing the connections; this variant does not manage their lifecycle.
+ *
+ * @typeParam TDrizzle - the consumer's Drizzle ORM type.
+ * @param options - the write ORM and the read connection.
+ * @returns a {@link Database} backed by the supplied ORM and replica.
+ * @example
+ * ```ts
+ * const db = createMysqlDatabase({
+ *   orm: drizzle(primary, { schema, ...DRIZZLE_ORM_OPTIONS }),
+ *   replica,
+ * });
+ * const rows = await db.read<User>('SELECT * FROM users WHERE id = ?', [id]);
+ * ```
+ */
+export declare function createMysqlDatabase<TDrizzle>(options: CreateMysqlDatabaseOptions<TDrizzle>): Database<TDrizzle>;
+/**
+ * Options for {@link createHyperdriveDatabase}.
+ *
+ * @typeParam TDrizzle - the consumer's Drizzle ORM type.
+ */
+export interface CreateHyperdriveDatabaseOptions<TDrizzle> {
+    /** The Hyperdrive binding for the primary (write) connection. */
+    primaryHyperdrive: HyperdriveLike;
+    /** The Hyperdrive binding for the replica (read) connection. */
+    replicaHyperdrive: HyperdriveLike;
+    /**
+     * Factory that builds the write ORM from the primary connection, using the consumer's
+     * `drizzle-orm`.
+     */
+    createOrm: (primary: Connection) => TDrizzle;
+    /**
+     * Extra options forwarded to mysql2 `createConnection`, merged on top of the defaults applied by
+     * {@link hyperdriveConnectionOptions} (`disableEval: true`, `decimalNumbers: true`, and
+     * `timezone: '+09:00'`). Pass a field here to override any of those defaults.
+     */
+    connectionOptions?: Record<string, unknown>;
+}
+/**
+ * Create a {@link HyperdriveDatabase} that lazily opens its connections from Hyperdrive bindings.
+ *
+ * @remarks
+ * Construct one per request. Connections and the ORM are created on first use and reused for the
+ * lifetime of the instance. `read()` uses the replica, while `query()` provides an explicit
+ * primary SELECT path. Workers automatically cleans up connections at the end of the invocation,
+ * so callers do not need to close them manually. Either SELECT path is repeated once on a fresh
+ * connection after a fatal mysql2 connection error. Writes and transactions are never repeated
+ * for connection errors because their commit state can be ambiguous.
+ *
+ * @typeParam TDrizzle - the consumer's Drizzle ORM type.
+ * @param options - the primary/replica Hyperdrive bindings, the ORM factory, and connection options.
+ * @returns a {@link HyperdriveDatabase} whose compatibility `dispose()` method is a no-op; Workers
+ *   cleans up its invocation-scoped connections automatically.
+ * @example
+ * ```ts
+ * const db = createHyperdriveDatabase({
+ *   primaryHyperdrive: env.PRIMARY,
+ *   replicaHyperdrive: env.REPLICA,
+ *   createOrm: (primary) => drizzle(primary, { schema, ...DRIZZLE_ORM_OPTIONS }),
+ * });
+ * await db.write((dz) => dz.insert(users).values(user));
+ * ```
+ */
+export declare function createHyperdriveDatabase<TDrizzle>(options: CreateHyperdriveDatabaseOptions<TDrizzle>): HyperdriveDatabase<TDrizzle>;
+/**
+ * Internal helper that assembles a {@link Database} from an ORM and a replica connection.
+ *
+ * @typeParam TDrizzle - the consumer's Drizzle ORM type.
+ * @param orm - the Drizzle ORM used for writes and transactions.
+ * @param replica - the connection used for reads.
+ * @returns a {@link Database} wiring reads to `replica` and writes to `orm`, both with deadlock retry.
+ * @internal
+ */
+export declare function databaseFrom<TDrizzle>(orm: TDrizzle, replica: QueryRunner): Database<TDrizzle>;
+/**
+ * Re-export of the mysql2 `Connection` and `Pool` types.
+ *
+ * @remarks
+ * Both are structurally assignable to this package's {@link QueryRunner}.
+ */
+export type { Connection, Pool };