@rdlabo/workers-hono-kit 0.11.0 → 0.11.1

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,28 @@ 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.
+ *
+ * @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>;
+}
 /**
  * Options for {@link createMysqlDatabase}.
  *
@@ -156,19 +178,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 +202,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
@@ -60,20 +60,33 @@ export function createHyperdriveDatabase(options) {
         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);
+    };
     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, (failedConnection) => {
+                if (primaryConn === failedConnection) {
+                    primaryConn = undefined;
+                    orm = undefined;
+                }
+            }, sql, params);
         },
         async write(fn) {
             const dz = await ormFor();

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, 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/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 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. |
 | `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` / `QueryRunner` / `TxOf` | The `read` / `query` / `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. 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.
 
 ```ts
 import { createHyperdriveDatabase } from '@rdlabo/workers-hono-kit/db';
@@ -15,6 +15,7 @@ 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));
 ```

package/package.json

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