@rdlabo/workers-hono-kit 0.11.0 → 0.11.1-beta.pr46.sha8ccc8da384f0

package/dist/db/database.d.ts

@@ -6,8 +6,8 @@ import type { HyperdriveLike } from './connection.js';
  * @remarks
  * The two sides of the database are deliberately handled differently:
  *
- * - Reads go to the **replica** as raw SQL (`QueryRunner.query`) for transparency, returning plain
- *   rows.
+ * - 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
@@ -99,6 +99,55 @@ export interface DisposableDatabase<TDrizzle, TTx = TxOf<TDrizzle>> extends Data
      */
     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}.
  *
@@ -156,19 +205,19 @@ export interface CreateHyperdriveDatabaseOptions<TDrizzle> {
     connectionOptions?: Record<string, unknown>;
 }
 /**
- * Create a {@link DisposableDatabase} that lazily opens its connections from Hyperdrive bindings.
+ * 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; the read/write/transaction surface is identical to
- * {@link createMysqlDatabase}. Workers automatically cleans up connections at the end of the
- * invocation, so callers do not need to close them manually. Replica SELECTs are 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.
+ * 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 DisposableDatabase} whose compatibility `dispose()` method is a no-op; Workers
+ * @returns a {@link HyperdriveDatabase} whose compatibility `dispose()` method is a no-op; Workers
  *   cleans up its invocation-scoped connections automatically.
  * @example
  * ```ts
@@ -180,7 +229,7 @@ export interface CreateHyperdriveDatabaseOptions<TDrizzle> {
  * await db.write((dz) => dz.insert(users).values(user));
  * ```
  */
-export declare function createHyperdriveDatabase<TDrizzle>(options: CreateHyperdriveDatabaseOptions<TDrizzle>): DisposableDatabase<TDrizzle>;
+export declare function createHyperdriveDatabase<TDrizzle>(options: CreateHyperdriveDatabaseOptions<TDrizzle>): HyperdriveDatabase<TDrizzle>;
 /**
  * Internal helper that assembles a {@link Database} from an ORM and a replica connection.
  *

package/dist/db/database.js

@@ -24,19 +24,19 @@ export function createMysqlDatabase(options) {
     return databaseFrom(options.orm, options.replica);
 }
 /**
- * Create a {@link DisposableDatabase} that lazily opens its connections from Hyperdrive bindings.
+ * 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; the read/write/transaction surface is identical to
- * {@link createMysqlDatabase}. Workers automatically cleans up connections at the end of the
- * invocation, so callers do not need to close them manually. Replica SELECTs are 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.
+ * 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 DisposableDatabase} whose compatibility `dispose()` method is a no-op; Workers
+ * @returns a {@link HyperdriveDatabase} whose compatibility `dispose()` method is a no-op; Workers
  *   cleans up its invocation-scoped connections automatically.
  * @example
  * ```ts
@@ -52,28 +52,85 @@ 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 {
-        async read(sql, params = []) {
-            const connection = replica();
-            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;
-            }
-            if (replicaConn === connection) {
-                replicaConn = undefined;
-            }
-            return readFrom(replica(), sql, params);
+        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();
@@ -124,7 +181,13 @@ function isFatalConnectionError(error) {
     while (typeof current === 'object' && current !== null && !seen.has(current)) {
         seen.add(current);
         const value = current;
-        if (value.fatal === true) {
+        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;

package/dist/db/index.d.ts

@@ -11,7 +11,7 @@
  */
 export { retryWhenDeadlock } from './retry.js';
 export { createMysqlDatabase, createHyperdriveDatabase, databaseFrom } from './database.js';
-export type { Database, DisposableDatabase, QueryRunner, TxOf, CreateMysqlDatabaseOptions, CreateHyperdriveDatabaseOptions, Connection, Pool, } 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';

package/dist/db/retry.js

@@ -32,8 +32,7 @@ export async function retryWhenDeadlock(fn, retries = 3, delay = 100) {
         if (outcome.ok) {
             return outcome.value;
         }
-        const code = outcome.error.code;
-        if (code === 'ER_LOCK_DEADLOCK' && attempt < retries - 1) {
+        if (isDeadlock(outcome.error) && attempt < retries - 1) {
             await new Promise((resolve) => setTimeout(resolve, delay * (attempt + 1)));
             continue;
         }
@@ -42,3 +41,16 @@ export async function retryWhenDeadlock(fn, retries = 3, delay = 100) {
     // Unreachable: the loop returns on success and throws on the final failed attempt.
     throw new Error('retryWhenDeadlock: exhausted retries');
 }
+function isDeadlock(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.code === 'ER_LOCK_DEADLOCK') {
+            return true;
+        }
+        current = value.cause;
+    }
+    return false;
+}

package/docs/api-db.md

@@ -1,13 +1,13 @@
 # API: `@rdlabo/workers-hono-kit/db`
 
-Requires the `drizzle-orm` and `mysql2` peers. Reads run against a replica via raw SQL; writes/transactions run against the primary through the Drizzle ORM with deadlock retry. The kit deliberately does not depend on the ORM's type identity — you pass the Drizzle instance in.
+Requires the `drizzle-orm` and `mysql2` peers. Reads use raw SQL against the replica by default, with an explicit primary read path for freshness; writes/transactions run against the primary through the Drizzle ORM with deadlock retry. The kit deliberately does not depend on the ORM's type identity — you pass the Drizzle instance in.
 
 | Export | Description |
 | --- | --- |
-| `createHyperdriveDatabase(options)` | `DisposableDatabase` that lazily opens primary/replica connections from Hyperdrive bindings per request. A replica SELECT is repeated at most once on a fresh connection after a fatal mysql2 connection error; writes and transactions are not repeated. Workers cleans connections up at invocation end; the legacy `dispose()` is a no-op. |
+| `createHyperdriveDatabase(options)` | `HyperdriveDatabase` that lazily opens primary/replica connections from Hyperdrive bindings per request. `read()` targets the replica, `query()` targets the primary, and `readTransaction()` pins raw and Drizzle reads to one primary consistent snapshot. Read transactions are serialized on a separately cached connection and must not be recursively nested. A SELECT or complete read-only transaction is repeated at most once on a fresh connection after a fatal mysql2 connection error. Writes and write transactions are not repeated. Workers cleans connections up at invocation end; the legacy `dispose()` is a no-op. |
 | `createMysqlDatabase(options)` | Assemble a `Database` from an already-connected Drizzle ORM + replica `QueryRunner`. |
 | `databaseFrom(orm, replica)` | Build a `Database` from an existing Drizzle instance + replica handle. |
-| `Database` / `DisposableDatabase` / `QueryRunner` / `TxOf` | The `read` / `write` / `transaction` API and its supporting types. |
+| `Database` / `DisposableDatabase` / `HyperdriveDatabase` / `ReadTransaction` / `QueryRunner` / `TxOf` | The `read` / `query` / `readTransaction` / `write` / `transaction` API and its supporting types. |
 | `hyperdriveConnectionOptions(hyperdrive, overrides?)` / `HyperdriveLike` / `ExecutionContextLike` | Build mysql2 `createConnection` options from a Hyperdrive binding (`disableEval`, `decimalNumbers`, `timezone '+09:00'` by default). `timezone` controls mysql2's JavaScript `Date` conversion; it does not change the MySQL session timezone. |
 | `withMysqlConnections(...)` | Open primary/replica connections in parallel and run a function. Workers cleans them up at invocation end. |
 | `retryWhenDeadlock(fn, retries?, delay?)` | Same deadlock-retry helper as the root export. |

package/docs/data-layer.md

@@ -2,7 +2,7 @@ Import database helpers from `@rdlabo/workers-hono-kit/db`. This entry point req
 
 ## Hyperdrive database
 
-`createHyperdriveDatabase()` lazily opens primary and replica connections from Hyperdrive bindings. Reads use the replica query runner; writes and transactions use the primary Drizzle instance. After a fatal mysql2 connection error, a replica read opens a fresh connection and repeats the SELECT at most once. Writes and transactions are not repeated because their commit state may be ambiguous. Workers owns connection cleanup at invocation end.
+`createHyperdriveDatabase()` lazily opens primary and replica connections from Hyperdrive bindings. `read()` uses the replica query runner; `query()` provides an explicit raw primary SELECT for read-after-write consistency; writes and transactions use the primary Drizzle instance. `readTransaction()` runs Drizzle and raw reads against one primary repeatable-read snapshot. Read transactions are serialized on one separately cached connection so their boundaries cannot mix with each other or with ordinary primary operations. After a fatal mysql2 connection error, a single read or the complete read-only transaction opens a fresh connection and repeats at most once. Writes and write transactions are not repeated because their commit state may be ambiguous. Workers owns connection cleanup at invocation end.
 
 ```ts
 import { createHyperdriveDatabase } from '@rdlabo/workers-hono-kit/db';
@@ -15,10 +15,20 @@ const db = createHyperdriveDatabase({
 });
 
 const rows = await db.read<Item>('SELECT * FROM items WHERE id = ?', [id]);
+const freshRows = await db.query<Item[]>('SELECT * FROM items WHERE id = ?', [id]);
 await db.write((dz) => dz.insert(items).values(input));
 await db.transaction((tx) => tx.insert(items).values(input));
+
+const snapshot = await db.readTransaction(async ({ orm, query }) => ({
+  items: await orm.select().from(items),
+  count: await query<{ count: number }[]>('SELECT COUNT(*) count FROM items'),
+}));
 ```
 
+MySQL enforces `READ ONLY` for every transaction attempt. Drizzle does not provide a distinct read-only transaction type, so applications can wrap `orm` in a SELECT-only facade when they also want compile-time enforcement.
+
+Do not call `readTransaction()` recursively from inside its callback. Calls share one serialized snapshot lane, so a nested call would wait for its own outer transaction to finish. Consumers that expose nested snapshot helpers should reuse the outer reader instead.
+
 Use `hyperdriveConnectionOptions()` when constructing lower-level mysql2 connections. The default JavaScript date conversion timezone is `+09:00`; it does not change the MySQL session timezone.
 
 ## Writes and retries

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rdlabo/workers-hono-kit",
-  "version": "0.11.0",
+  "version": "0.11.1-beta.pr46.sha8ccc8da384f0",
   "private": false,
   "publishConfig": {
     "access": "public"