@rdlabo/workers-mysql 0.1.0

package/dist/database.js

@@ -0,0 +1,196 @@
+import { createConnection } from 'mysql2/promise';
+import { hyperdriveConnectionOptions } from './connection.js';
+import { retryWhenDeadlock } from './retry.js';
+/**
+ * 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 function createMysqlDatabase(options) {
+    return databaseFrom(options.orm, options.replica);
+}
+/**
+ * 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 function createHyperdriveDatabase(options) {
+    const { primaryHyperdrive, replicaHyperdrive, createOrm, connectionOptions } = options;
+    let primaryConn;
+    let replicaConn;
+    let readTransactionConn;
+    let orm;
+    let readTransactionOrm;
+    let readTransactionTail;
+    const primary = () => (primaryConn ??= connect(primaryHyperdrive, connectionOptions));
+    const replica = () => (replicaConn ??= connect(replicaHyperdrive, connectionOptions));
+    const readTransactionConnection = () => (readTransactionConn ??= connect(primaryHyperdrive, connectionOptions));
+    const ormFor = async () => (orm ??= createOrm(await primary()));
+    const readFrom = (connection, sql, params) => retryWhenDeadlock(async () => {
+        const [rows] = (await (await connection).query(sql, params));
+        return rows;
+    });
+    const readWithRecovery = async (connectionFor, reset, sql, params) => {
+        const connection = connectionFor();
+        const outcome = await readFrom(connection, sql, params).then((rows) => ({ ok: true, rows }), (error) => ({ ok: false, error }));
+        if (outcome.ok) {
+            return outcome.rows;
+        }
+        if (!isFatalConnectionError(outcome.error)) {
+            throw outcome.error;
+        }
+        reset(connection);
+        return readFrom(connectionFor(), sql, params);
+    };
+    const resetPrimary = (failedConnection) => {
+        if (primaryConn === failedConnection) {
+            primaryConn = undefined;
+            orm = undefined;
+        }
+    };
+    const resetReadTransaction = (failedConnection) => {
+        if (readTransactionConn === failedConnection) {
+            readTransactionConn = undefined;
+            readTransactionOrm = undefined;
+        }
+    };
+    const withReadTransactionLock = (fn) => {
+        const result = readTransactionTail ? readTransactionTail.then(fn, fn) : fn();
+        readTransactionTail = result.then(() => undefined, () => undefined);
+        return result;
+    };
+    const runReadTransaction = async (connection, fn) => {
+        const conn = await connection;
+        const dz = (readTransactionOrm ??= createOrm(conn));
+        return retryWhenDeadlock(async () => {
+            await conn.query('SET TRANSACTION READ ONLY');
+            return dz.transaction((tx) => fn({
+                orm: tx,
+                query: async (sql, params = []) => {
+                    const [rows] = (await conn.query(sql, params));
+                    return rows;
+                },
+            }), { isolationLevel: 'repeatable read', withConsistentSnapshot: true });
+        });
+    };
+    return {
+        read(sql, params = []) {
+            return readWithRecovery(replica, (failedConnection) => {
+                if (replicaConn === failedConnection) {
+                    replicaConn = undefined;
+                }
+            }, sql, params);
+        },
+        query(sql, params = []) {
+            return readWithRecovery(primary, resetPrimary, sql, params);
+        },
+        async readTransaction(fn) {
+            return withReadTransactionLock(async () => {
+                const connection = readTransactionConnection();
+                const outcome = await runReadTransaction(connection, fn).then((value) => ({ ok: true, value }), (error) => ({ ok: false, error }));
+                if (outcome.ok) {
+                    return outcome.value;
+                }
+                if (!isFatalConnectionError(outcome.error)) {
+                    throw outcome.error;
+                }
+                resetReadTransaction(connection);
+                return runReadTransaction(readTransactionConnection(), fn);
+            });
+        },
+        async write(fn) {
+            const dz = await ormFor();
+            return retryWhenDeadlock(() => fn(dz));
+        },
+        async transaction(fn) {
+            const dz = (await ormFor());
+            return retryWhenDeadlock(() => dz.transaction(fn));
+        },
+        /** @deprecated Workers cleans up invocation-scoped connections automatically. */
+        async dispose() {
+            return;
+        },
+    };
+}
+/**
+ * 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 function databaseFrom(orm, replica) {
+    const drizzleLike = orm;
+    return {
+        read(sql, params = []) {
+            return retryWhenDeadlock(async () => {
+                const [rows] = (await replica.query(sql, params));
+                return rows;
+            });
+        },
+        write(fn) {
+            return retryWhenDeadlock(() => fn(orm));
+        },
+        transaction(fn) {
+            return retryWhenDeadlock(() => drizzleLike.transaction(fn));
+        },
+    };
+}
+function connect(hyperdrive, extra) {
+    return createConnection(hyperdriveConnectionOptions(hyperdrive, extra));
+}
+function isFatalConnectionError(error) {
+    let current = error;
+    const seen = new Set();
+    while (typeof current === 'object' && current !== null && !seen.has(current)) {
+        seen.add(current);
+        const value = current;
+        if (value.fatal === true ||
+            value.code === 'PROTOCOL_CONNECTION_LOST' ||
+            value.code === 'ECONNRESET' ||
+            value.code === 'EPIPE' ||
+            (typeof value.message === 'string' &&
+                (value.message.includes('Connection lost:') ||
+                    value.message.includes("Can't add new command when connection is in closed state")))) {
+            return true;
+        }
+        current = value.cause;
+    }
+    return false;
+}

package/dist/drizzle.d.ts

@@ -0,0 +1,6 @@
+/** Drizzle adapters for `@rdlabo/workers-mysql`. Requires the optional `drizzle-orm` peer. */
+export { jstTimestamp, jstDatetime, jstDate, jstOnUpdateNow } from './columns.js';
+export { DRIZZLE_ORM_OPTIONS, workersDrizzleConfig, resolveDbSecret } from './orm-config.js';
+export { honoDrizzleConfig } from './orm-config.js';
+export type { WorkersDrizzleConfigOptions, ResolvedDbSecret } from './orm-config.js';
+export type { HonoDrizzleConfigOptions } from './orm-config.js';

package/dist/drizzle.js

@@ -0,0 +1,5 @@
+/** Drizzle adapters for `@rdlabo/workers-mysql`. Requires the optional `drizzle-orm` peer. */
+export { jstTimestamp, jstDatetime, jstDate, jstOnUpdateNow } from './columns.js';
+export { DRIZZLE_ORM_OPTIONS, workersDrizzleConfig, resolveDbSecret } from './orm-config.js';
+// eslint-disable-next-line @typescript-eslint/no-deprecated -- public compatibility alias
+export { honoDrizzleConfig } from './orm-config.js';

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * MySQL, Hyperdrive, and Drizzle infrastructure for Cloudflare Workers.
+ *
+ * @packageDocumentation
+ */
+export { retryWhenDeadlock } from './retry.js';
+export { createMysqlDatabase, createHyperdriveDatabase, databaseFrom } from './database.js';
+export type { Database, DisposableDatabase, HyperdriveDatabase, ReadTransaction, QueryRunner, TxOf, CreateMysqlDatabaseOptions, CreateHyperdriveDatabaseOptions, Connection, Pool, } from './database.js';
+export { insertIdOf, affectedRowsOf, insertedIdsOf } from './write-result.js';
+export type { DzWriteResult } from './write-result.js';
+export { hyperdriveConnectionOptions, withMysqlConnections } from './connection.js';
+export type { HyperdriveLike, ExecutionContextLike } from './connection.js';
+export { MYSQL_TIMEZONE, toJstDate, jstTimestampParams, jstDatetimeParams, jstDateParams } from './jst.js';

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * MySQL, Hyperdrive, and Drizzle infrastructure for Cloudflare Workers.
+ *
+ * @packageDocumentation
+ */
+export { retryWhenDeadlock } from './retry.js';
+export { createMysqlDatabase, createHyperdriveDatabase, databaseFrom } from './database.js';
+export { insertIdOf, affectedRowsOf, insertedIdsOf } from './write-result.js';
+export { hyperdriveConnectionOptions, withMysqlConnections } from './connection.js';
+export { MYSQL_TIMEZONE, toJstDate, jstTimestampParams, jstDatetimeParams, jstDateParams } from './jst.js';

package/dist/jst.d.ts

@@ -0,0 +1,43 @@
+/**
+ * JST wire conversion and DATE-column normalization for MySQL / Drizzle.
+ *
+ * @remarks
+ * This module owns the MySQL fixed `+09:00` contract independently of any business-time
+ * package, plus the DATE column's `toDriver` and the column `customType` params.
+ */
+/** Default mysql2 connection `timezone` (for the existing JST DB deployment). */
+export declare const MYSQL_TIMEZONE = "+09:00";
+/**
+ * Normalize a client input to `YYYY-MM-DD` (a JST business calendar date) for a MySQL `DATE` column.
+ * Accepts ISO 8601 / `YYYY-MM-DD` / empty strings. A `YYYY-MM-DD` value is passed through without
+ * constructing a `Date`.
+ *
+ * @param value - the string or nullish input to normalize.
+ * @returns the business date as `YYYY-MM-DD`, or `null` when the input cannot be resolved.
+ */
+export declare function toJstDate(value: string | null | undefined): string | null;
+/**
+ * Build the params for a `customType` backing a MySQL `timestamp` column with `Date` pass-through.
+ *
+ * @param fsp - optional fractional-seconds precision; when provided, emits `timestamp(fsp)`.
+ */
+export declare const jstTimestampParams: (fsp?: number) => {
+    dataType: () => string;
+};
+/**
+ * Build the params for a `customType` backing a MySQL `datetime` column with `Date` pass-through.
+ *
+ * @param fsp - optional fractional-seconds precision; when provided, emits `datetime(fsp)`.
+ */
+export declare const jstDatetimeParams: (fsp?: number) => {
+    dataType: () => string;
+};
+/**
+ * Build the params for a `customType` backing a MySQL `date` column with JST normalization.
+ *
+ * @returns params with `toDriver` running {@link toJstDate}.
+ */
+export declare const jstDateParams: () => {
+    dataType: () => string;
+    toDriver: (value: string | null) => string | null;
+};

package/dist/jst.js

@@ -0,0 +1,59 @@
+/**
+ * JST wire conversion and DATE-column normalization for MySQL / Drizzle.
+ *
+ * @remarks
+ * This module owns the MySQL fixed `+09:00` contract independently of any business-time
+ * package, plus the DATE column's `toDriver` and the column `customType` params.
+ */
+/** Default mysql2 connection `timezone` (for the existing JST DB deployment). */
+export const MYSQL_TIMEZONE = '+09:00';
+const JST_OFFSET_MILLISECONDS = 9 * 60 * 60 * 1_000;
+const pad2 = (value) => String(value).padStart(2, '0');
+function fixedJstDate(instant) {
+    const wallClock = new Date(instant.getTime() + JST_OFFSET_MILLISECONDS);
+    return `${String(wallClock.getUTCFullYear()).padStart(4, '0')}-${pad2(wallClock.getUTCMonth() + 1)}-${pad2(wallClock.getUTCDate())}`;
+}
+/**
+ * Normalize a client input to `YYYY-MM-DD` (a JST business calendar date) for a MySQL `DATE` column.
+ * Accepts ISO 8601 / `YYYY-MM-DD` / empty strings. A `YYYY-MM-DD` value is passed through without
+ * constructing a `Date`.
+ *
+ * @param value - the string or nullish input to normalize.
+ * @returns the business date as `YYYY-MM-DD`, or `null` when the input cannot be resolved.
+ */
+export function toJstDate(value) {
+    const trimmed = value?.trim();
+    if (!trimmed) {
+        return null;
+    }
+    if (/^\d{4}-\d{2}-\d{2}$/.test(trimmed)) {
+        return trimmed;
+    }
+    const instant = new Date(trimmed);
+    return Number.isNaN(instant.getTime()) ? null : fixedJstDate(instant);
+}
+/**
+ * Build the params for a `customType` backing a MySQL `timestamp` column with `Date` pass-through.
+ *
+ * @param fsp - optional fractional-seconds precision; when provided, emits `timestamp(fsp)`.
+ */
+export const jstTimestampParams = (fsp) => ({
+    dataType: () => (fsp != null ? `timestamp(${fsp})` : 'timestamp'),
+});
+/**
+ * Build the params for a `customType` backing a MySQL `datetime` column with `Date` pass-through.
+ *
+ * @param fsp - optional fractional-seconds precision; when provided, emits `datetime(fsp)`.
+ */
+export const jstDatetimeParams = (fsp) => ({
+    dataType: () => (fsp != null ? `datetime(${fsp})` : 'datetime'),
+});
+/**
+ * Build the params for a `customType` backing a MySQL `date` column with JST normalization.
+ *
+ * @returns params with `toDriver` running {@link toJstDate}.
+ */
+export const jstDateParams = () => ({
+    dataType: () => 'date',
+    toDriver: (value) => toJstDate(value),
+});

package/dist/migrate.d.ts

@@ -0,0 +1,51 @@
+import type { QueryRunner } from './database.js';
+/** Identifying info for the baseline (i.e. first) migration. */
+export interface BaselineEntry {
+    /** The migration tag (e.g. `0000_melted_weapon_omega`). */
+    tag: string;
+    /** The `when` from `_journal.json` (= drizzle's `created_at` / `folderMillis`). */
+    when: number;
+    /** The sha256 of the raw `<tag>.sql` contents (the same algorithm as drizzle). */
+    hash: string;
+}
+/**
+ * Read the baseline (first) entry from `migrationsFolder` (drizzle's `out`, e.g. `./drizzle`).
+ *
+ * @param migrationsFolder - the folder containing `meta/_journal.json` and `<tag>.sql`.
+ * @returns the baseline entry (tag/when/hash).
+ * @throws Error when the journal is missing, the entries are empty, or `<tag>.sql` is missing.
+ */
+export declare function readBaselineEntry(migrationsFolder: string): BaselineEntry;
+/** Options for {@link baselineMigrations}. */
+export interface BaselineMigrationsOptions {
+    /** A QueryRunner for raw SQL (a mysql2 `Connection`/`Pool` is assignable). Must already be connected to the target DB. */
+    db: QueryRunner;
+    /** Drizzle's `out` folder (defaults to `./drizzle`). */
+    migrationsFolder?: string;
+}
+/** The result of {@link baselineMigrations}. */
+export type BaselineResult = {
+    status: 'inserted';
+    tag: string;
+    when: number;
+    hash: string;
+} | {
+    status: 'already-baselined';
+    tag: string;
+    when: number;
+};
+/**
+ * Record the baseline (0000) as "applied" on an existing DB. Idempotent, with safety guards.
+ *
+ * @remarks
+ * Guards:
+ * - If a baseline marker (`created_at = when`) already exists → **no-op** (`already-baselined`).
+ * - If there is no marker but `__drizzle_migrations` has other rows → **abort** (unexpected state).
+ * - If the target DB has no base tables (an empty DB) → **abort** (skipping 0000 on an empty DB would
+ *   never create the tables; use `db:migrate` for a fresh DB).
+ *
+ * @param options - the connection and migrations folder; see {@link BaselineMigrationsOptions}.
+ * @returns whether a marker was inserted or the DB was already baselined.
+ * @throws Error when one of the guards above trips.
+ */
+export declare function baselineMigrations(options: BaselineMigrationsOptions): Promise<BaselineResult>;

package/dist/migrate.js

@@ -0,0 +1,109 @@
+/**
+ * Brownfield baseline for Drizzle MySQL migrations.
+ *
+ * An existing (in-production) DB already has its schema, so running the committed baseline migration
+ * (`drizzle/0000_*.sql` = the CREATE TABLE statements introspected from the current schema) via
+ * `db:migrate` fails as every table collides. Instead, 0000 is **recorded as "applied" without being
+ * executed**.
+ *
+ * How "applied" is decided (drizzle-orm/mysql-core dialect.migrate): it determines the pending set from
+ * **only the maximum `created_at`** in `__drizzle_migrations(id, hash, created_at)`, running just the
+ * migrations where `max(created_at) < entry.when`. The hash is stored but not used for the decision. So
+ * inserting one row as the 0000 marker — `(hash, created_at = that entry's when)` — makes subsequent
+ * `db:migrate` runs apply only the later 0001+ (larger `when`) and skip 0000. A fresh / test DB has no
+ * marker, so the full chain runs (behavior unchanged).
+ *
+ * This function does not depend on `drizzle-orm` (it reads the journal/SQL itself and hashes with the
+ * same sha256 as drizzle). It runs raw SQL against a QueryRunner (a mysql2 `Connection`/`Pool` is
+ * structurally assignable).
+ *
+ * @packageDocumentation
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** The default migration-tracking table name used by drizzle. */
+const MIGRATIONS_TABLE = '__drizzle_migrations';
+/**
+ * Read the baseline (first) entry from `migrationsFolder` (drizzle's `out`, e.g. `./drizzle`).
+ *
+ * @param migrationsFolder - the folder containing `meta/_journal.json` and `<tag>.sql`.
+ * @returns the baseline entry (tag/when/hash).
+ * @throws Error when the journal is missing, the entries are empty, or `<tag>.sql` is missing.
+ */
+export function readBaselineEntry(migrationsFolder) {
+    const journalPath = join(migrationsFolder, 'meta', '_journal.json');
+    if (!existsSync(journalPath)) {
+        throw new Error(`Can't find meta/_journal.json under ${migrationsFolder}. Run \`drizzle-kit generate\` first.`);
+    }
+    const journal = JSON.parse(readFileSync(journalPath, 'utf8'));
+    const entries = journal.entries ?? [];
+    if (entries.length === 0) {
+        throw new Error(`No migration entries in ${journalPath}.`);
+    }
+    // The origin is always the first entry (0000). Later 0001+ are "new changes" that should run even on
+    // an existing DB.
+    const first = entries[0];
+    const sqlPath = join(migrationsFolder, `${first.tag}.sql`);
+    if (!existsSync(sqlPath)) {
+        throw new Error(`Can't find ${first.tag}.sql under ${migrationsFolder}.`);
+    }
+    const sql = readFileSync(sqlPath, 'utf8');
+    return { tag: first.tag, when: first.when, hash: createHash('sha256').update(sql).digest('hex') };
+}
+async function rowsOf(db, sql, params) {
+    const result = (await db.query(sql, params));
+    return result[0] ?? [];
+}
+/**
+ * Record the baseline (0000) as "applied" on an existing DB. Idempotent, with safety guards.
+ *
+ * @remarks
+ * Guards:
+ * - If a baseline marker (`created_at = when`) already exists → **no-op** (`already-baselined`).
+ * - If there is no marker but `__drizzle_migrations` has other rows → **abort** (unexpected state).
+ * - If the target DB has no base tables (an empty DB) → **abort** (skipping 0000 on an empty DB would
+ *   never create the tables; use `db:migrate` for a fresh DB).
+ *
+ * @param options - the connection and migrations folder; see {@link BaselineMigrationsOptions}.
+ * @returns whether a marker was inserted or the DB was already baselined.
+ * @throws Error when one of the guards above trips.
+ */
+export async function baselineMigrations(options) {
+    const { db, migrationsFolder = './drizzle' } = options;
+    const baseline = readBaselineEntry(migrationsFolder);
+    // Same DDL as the migrator (a no-op if it already exists).
+    await db.query(`create table if not exists \`${MIGRATIONS_TABLE}\` (
+      id serial primary key,
+      hash text not null,
+      created_at bigint
+    )`);
+    // If a baseline marker already exists, this is an idempotent no-op.
+    const existing = await rowsOf(db, `select id from \`${MIGRATIONS_TABLE}\` where created_at = ? limit 1`, [
+        baseline.when,
+    ]);
+    if (existing.length > 0) {
+        return { status: 'already-baselined', tag: baseline.tag, when: baseline.when };
+    }
+    // No marker but rows exist = already in some other state. Abort to avoid misfiring.
+    const countRows = await rowsOf(db, `select count(*) as n from \`${MIGRATIONS_TABLE}\``);
+    const rowCount = Number(countRows[0]?.n ?? 0);
+    if (rowCount > 0) {
+        throw new Error(`${MIGRATIONS_TABLE} already has ${rowCount} row(s) but no baseline marker (created_at=${baseline.when}). ` +
+            `Migration state is unexpected — refusing to insert. Inspect \`${MIGRATIONS_TABLE}\` manually.`);
+    }
+    // Baselining an empty DB is dangerous (treating 0000 as skipped would never create the tables).
+    // Confirm this is a brownfield DB.
+    const tableRows = await rowsOf(db, `select count(*) as n from information_schema.tables
+      where table_schema = DATABASE() and table_type = 'BASE TABLE' and table_name <> ?`, [MIGRATIONS_TABLE]);
+    const baseTableCount = Number(tableRows[0]?.n ?? 0);
+    if (baseTableCount === 0) {
+        throw new Error(`Target DB has no base tables. baseline records 0000 as applied WITHOUT creating tables — this is only ` +
+            `for existing (brownfield) DBs. For a fresh/empty DB run \`drizzle-kit migrate\` instead.`);
+    }
+    await db.query(`insert into \`${MIGRATIONS_TABLE}\` (\`hash\`, \`created_at\`) values (?, ?)`, [
+        baseline.hash,
+        baseline.when,
+    ]);
+    return { status: 'inserted', tag: baseline.tag, when: baseline.when, hash: baseline.hash };
+}

package/dist/migrations.d.ts

@@ -0,0 +1,5 @@
+/** Node.js migration helpers for `@rdlabo/workers-mysql`. */
+export { baselineMigrations, readBaselineEntry } from './migrate.js';
+export type { BaselineMigrationsOptions, BaselineResult, BaselineEntry } from './migrate.js';
+export { resolveDbSecret } from './orm-config.js';
+export type { ResolvedDbSecret } from './orm-config.js';

package/dist/migrations.js

@@ -0,0 +1,3 @@
+/** Node.js migration helpers for `@rdlabo/workers-mysql`. */
+export { baselineMigrations, readBaselineEntry } from './migrate.js';
+export { resolveDbSecret } from './orm-config.js';

package/dist/orm-config.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Centralizes Drizzle column-name casing so it is fixed (standard: `snake_case`) in both the
+ * config and the runtime ORM.
+ *
+ * @remarks
+ * Casing is configured in two distinct places:
+ *
+ * 1. The top-level `casing` in `drizzle.config.ts` decides the column names that `db:generate`
+ *    **creates** (see {@link workersDrizzleConfig}).
+ * 2. The `drizzle(conn, { …casing })` call decides the column names the **runtime write builder**
+ *    resolves to (see {@link DRIZZLE_ORM_OPTIONS}).
+ *
+ * If these two disagree, a multi-word camelCase column without an explicit column name will be
+ * generated with one name but queried with another, producing a runtime `Unknown column` error —
+ * something neither the type-check nor the migration surface, so it is caught late. Sourcing both
+ * from here makes the mismatch structurally impossible. Casing is ignored for columns that declare
+ * an explicit name, so this is a pure safety net that does not change existing behavior.
+ *
+ * The runtime `drizzle()` call itself is made by the consuming app with its own `drizzle-orm`; the
+ * package only provides values, never the ORM instance, to avoid splitting `drizzle-orm` into two
+ * copies and breaking type identity.
+ */
+/**
+ * Runtime ORM options shared by the consuming app's `drizzle()` call.
+ *
+ * Spread into the runtime ORM as `drizzle(conn, { schema, ...DRIZZLE_ORM_OPTIONS })` so the write
+ * builder resolves column names as `snake_case`, matching what `db:generate` creates.
+ *
+ * @remarks
+ * Fixes `mode: 'default'` and `casing: 'snake_case'`. See the module-level documentation for why
+ * the same casing must be used by both the config and the runtime ORM.
+ */
+export declare const DRIZZLE_ORM_OPTIONS: {
+    readonly mode: "default";
+    readonly casing: "snake_case";
+};
+/**
+ * Options for {@link workersDrizzleConfig}.
+ */
+export interface WorkersDrizzleConfigOptions {
+    /** drizzle-kit `dbCredentials.database` — the database name to connect to. */
+    database: string;
+    /** Database host; defaults to `process.env.DB_HOST` then `127.0.0.1`. */
+    host?: string;
+    /** Database port; defaults to `process.env.DB_PORT` then `3306`. */
+    port?: number;
+    /** Database user; defaults to `process.env.DB_USER` then `root`. */
+    user?: string;
+    /** Database password; defaults to `process.env.DB_PASSWORD` then `root`. */
+    password?: string;
+    /** Path to the schema directory; defaults to `'./src/db/schemes'`. */
+    schema?: string;
+    /** Output directory for generated migrations; defaults to `'./drizzle'`. */
+    out?: string;
+    /**
+     * Optional table allow-list. Use this to restrict drizzle-kit to the schema's own tables when the
+     * database is shared with another application.
+     */
+    tablesFilter?: string[];
+    /**
+     * Optional `db:introspect` (DB → JS) casing. This is an independent axis from the generation-side
+     * `casing: 'snake_case'` and only affects introspection output.
+     */
+    introspect?: {
+        casing: 'camel' | 'preserve';
+    };
+}
+/**
+ * Build a `drizzle.config.ts` configuration object with the Workers MySQL defaults.
+ *
+ * Fixes `casing: 'snake_case'`, the `schema`/`out` paths, and `dbCredentials` (with env-based
+ * defaults), while leaving `tablesFilter` and `introspect` opt-in.
+ *
+ * @remarks
+ * Returns a plain object rather than a typed drizzle-kit config so that `drizzle-kit` need not be a
+ * dependency of this package; the drizzle-kit CLI only reads the default export.
+ *
+ * @param options - configuration overrides; only `database` is required.
+ * @returns a plain configuration object suitable for `export default` in `drizzle.config.ts`.
+ * @example
+ * ```ts
+ * // drizzle.config.ts
+ * import { workersDrizzleConfig } from '@rdlabo/workers-mysql/drizzle';
+ *
+ * export default workersDrizzleConfig({ database: 'app' });
+ * ```
+ */
+export declare function workersDrizzleConfig(options: WorkersDrizzleConfigOptions): {
+    dbCredentials: {
+        host: string;
+        port: number;
+        user: string;
+        password: string;
+        database: string;
+    };
+    introspect?: {
+        casing: "camel" | "preserve";
+    } | undefined;
+    tablesFilter?: string[] | undefined;
+    dialect: "mysql";
+    schema: string;
+    out: string;
+    casing: "snake_case";
+};
+/**
+ * @deprecated Use {@link workersDrizzleConfig}; retained for source compatibility with
+ * `@rdlabo/workers-hono-kit/db`.
+ */
+export declare const honoDrizzleConfig: typeof workersDrizzleConfig;
+/** @deprecated Use {@link WorkersDrizzleConfigOptions}. */
+export type HonoDrizzleConfigOptions = WorkersDrizzleConfigOptions;
+/** The return value of {@link resolveDbSecret} (normalized connection info). */
+export interface ResolvedDbSecret {
+    host: string;
+    port: number;
+    dbname: string;
+    username: string;
+    password: string;
+}
+/**
+ * Resolve an AWS RDS managed secret (a JSON string placed in `DB_SECRET`).
+ *
+ * @remarks
+ * - `DB_SECRET` unset → `undefined` (the normal local / `db:generate` fallback).
+ * - When set, it must be complete connection info: **invalid JSON / a missing required key throws**
+ *   (rather than silently falling back to localhost and causing an incident). A missing `port` alone
+ *   defaults to 3306.
+ *
+ * Both `workersDrizzleConfig` (db:migrate) and the compatibility baseline command use this logic.
+ *
+ * @returns the resolved connection info, or `undefined` when `DB_SECRET` is unset.
+ * @throws Error when `DB_SECRET` is set but is not valid JSON or is missing a required key.
+ */
+export declare function resolveDbSecret(): ResolvedDbSecret | undefined;