@rdlabo/workers-hono-kit 0.11.1 → 0.11.2

package/dist/db/database.d.ts

@@ -106,6 +106,9 @@ export interface DisposableDatabase<TDrizzle, TTx = TxOf<TDrizzle>> extends Data
  * 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.
@@ -120,6 +123,30 @@ export interface HyperdriveDatabase<TDrizzle, TTx = TxOf<TDrizzle>> extends Disp
      * @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}.

package/dist/db/database.js

@@ -52,9 +52,13 @@ 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));
@@ -72,6 +76,37 @@ export function createHyperdriveDatabase(options) {
         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) => {
@@ -81,12 +116,21 @@ export function createHyperdriveDatabase(options) {
             }, sql, params);
         },
         query(sql, params = []) {
-            return readWithRecovery(primary, (failedConnection) => {
-                if (primaryConn === failedConnection) {
-                    primaryConn = undefined;
-                    orm = undefined;
+            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;
                 }
-            }, sql, params);
+                if (!isFatalConnectionError(outcome.error)) {
+                    throw outcome.error;
+                }
+                resetReadTransaction(connection);
+                return runReadTransaction(readTransactionConnection(), fn);
+            });
         },
         async write(fn) {
             const dz = await ormFor();
@@ -137,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, HyperdriveDatabase, 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

@@ -4,10 +4,10 @@ Requires the `drizzle-orm` and `mysql2` peers. Reads use raw SQL against the rep
 
 | Export | Description |
 | --- | --- |
-| `createHyperdriveDatabase(options)` | `HyperdriveDatabase` that lazily opens primary/replica connections from Hyperdrive bindings per request. `read()` targets the replica and `query()` targets the primary; either 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` / `HyperdriveDatabase` / `QueryRunner` / `TxOf` | The `read` / `query` / `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. `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. After a fatal mysql2 connection error, either read path 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';
@@ -18,8 +18,17 @@ 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.1",
+  "version": "0.11.2",
   "private": false,
   "publishConfig": {
     "access": "public"