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

package/docs/migration.md

@@ -0,0 +1,28 @@
+---
+title: Migration
+---
+
+# Migration
+
+The database utilities are standalone from kit `0.12.0`. Install `@rdlabo/workers-mysql` directly;
+keep `@rdlabo/workers-hono-kit` only if using its Hono integration. `mysql2` is included, while
+`drizzle-orm` remains an optional peer for `/drizzle` and `/testing`. TypeScript consumers need
+the Node declarations described in the [README](../README.md).
+
+| Previous import                        | New import                         |
+| -------------------------------------- | ---------------------------------- |
+| Kit root `createContainerRuntime`      | `@rdlabo/workers-hono-kit/mysql`   |
+| Kit root `retryWhenDeadlock`           | `@rdlabo/workers-mysql`            |
+| Kit `/db` runtime and JST wire helpers | `@rdlabo/workers-mysql`            |
+| Kit `/db` column/configuration helpers | `@rdlabo/workers-mysql/drizzle`    |
+| Kit `/db` baseline helpers             | `@rdlabo/workers-mysql/migrations` |
+| Kit `/testing` database helpers        | `@rdlabo/workers-mysql/testing`    |
+
+The old `/db` and DB-related `/testing` paths remain available as maintained compatibility
+re-exports with `@deprecated` notices; there is no planned removal. Do not import the legacy
+aggregate `/db` in new Worker code: use the dedicated runtime entry points to keep Node-only
+migration code out of the Worker bundle. Rename `honoDrizzleConfig` to `workersDrizzleConfig` when
+updating configuration.
+
+No Hono dependency is required by this database package. The fixed-JST storage contract also
+remains separate from configurable business timezones; see [Drizzle and dates](./drizzle.md).

package/docs/runtime.md

@@ -0,0 +1,72 @@
+---
+title: Runtime
+---
+
+# Runtime
+
+Enable `nodejs_compat` in your Worker and install the dependencies described in the
+[README](../README.md). `mysql2` is included; the package does not depend on Hono.
+The application supplies its Hyperdrive bindings, schema, and ORM factory.
+
+## Invocation lifetime
+
+Create `createHyperdriveDatabase` inside each invocation, not in module-global state. Connections
+open lazily and are reused by that database instance. The runtime cleans up invocation connections;
+its compatibility `dispose()` method is a no-op.
+
+This complete Worker example uses one Hyperdrive binding for both roles. Applications with a
+replica can supply a separate binding for `replicaHyperdrive`:
+
+```ts
+import { createHyperdriveDatabase, type HyperdriveLike } from '@rdlabo/workers-mysql';
+import { DRIZZLE_ORM_OPTIONS } from '@rdlabo/workers-mysql/drizzle';
+import { drizzle } from 'drizzle-orm/mysql2';
+
+interface Env {
+  DB: HyperdriveLike;
+}
+
+export default {
+  async fetch(_request: Request, env: Env): Promise<Response> {
+    const db = createHyperdriveDatabase({
+      primaryHyperdrive: env.DB,
+      replicaHyperdrive: env.DB,
+      createOrm: (connection) => drizzle(connection, DRIZZLE_ORM_OPTIONS),
+    });
+    const rows = await db.query<Array<{ value: number }>>('SELECT ? AS value', [1]);
+    return Response.json(rows);
+  },
+};
+```
+
+## Read and write paths
+
+| Operation                   | Destination                 | Result type parameter             |
+| --------------------------- | --------------------------- | --------------------------------- |
+| `read<Row>(sql, params?)`   | Replica                     | One row; returns `Row[]`          |
+| `query<Rows>(sql, params?)` | Primary SELECT              | Whole result, for example `Row[]` |
+| `readTransaction(fn)`       | Primary consistent snapshot | Callback result                   |
+| `write(fn)`                 | Primary ORM                 | Awaited callback result           |
+| `transaction(fn)`           | Primary transaction         | Awaited callback result           |
+
+Use `query` for reads that cannot tolerate replica lag. Query caching, if enabled on a Hyperdrive
+binding, is a separate configuration concern. Use parameter placeholders, not interpolated SQL.
+
+`readTransaction` passes `{ orm, query }` on one read-only snapshot. Its calls are serialized on a
+dedicated connection; do not call it recursively inside its callback.
+
+## Retry boundaries
+
+Database operations retry deadlocks. Return/await the write builder or promise from callbacks.
+The whole transaction callback can run again: keep email, payments, and other external side effects
+outside it. Do not add another `retryWhenDeadlock` wrapper around an already-retrying operation.
+
+Hyperdrive SELECTs and read-only transactions can additionally repeat once on a fresh connection
+after a fatal connection error. Writes and write transactions are not replayed for connection loss:
+the outcome may be unknown. Handle application idempotency before retrying such a request.
+
+`createMysqlDatabase({ orm, replica })` and `databaseFrom(orm, replica)` wrap existing handles;
+their caller owns connection cleanup. They expose `Database`, not the extra Hyperdrive primary-read
+methods. For Hono containers, use `@rdlabo/workers-hono-kit/mysql` (kit `0.12.0` or later).
+
+See [Drizzle and dates](./drizzle.md) for connection defaults and [API](./api.md) for exports.

package/docs/tooling.md

@@ -0,0 +1,51 @@
+---
+title: Migrations and testing
+---
+
+# Migrations and testing
+
+These helpers are for Node.js tooling, not Worker request bundles. Import them from their dedicated
+entry points. The consumer owns migrations, credentials, test fixtures, and database provisioning.
+
+## Drizzle configuration
+
+`workersDrizzleConfig` from `/drizzle` builds a MySQL Drizzle Kit configuration with snake-case
+casing. Supply your `database`, `schema`, and `out` paths explicitly.
+`workersDrizzleConfig` automatically reads `DB_SECRET`: when set, its connection details override
+even explicitly supplied `database`, host, port, user, and password options, as well as `DB_*`
+environment variables. Before running migrations, verify the secret's target; specifying a local
+`database` option alone does not restrict the connection to that database.
+`resolveDbSecret()` reads `DB_SECRET` JSON (`host`, `username`, `password`, `dbname`, optional
+`port`). It returns `undefined` if unset and throws for invalid input rather than silently falling
+back. Never commit or log database secrets.
+
+## Existing-database baseline
+
+`baselineMigrations({ db, migrationsFolder })` from `/migrations` records the first migration as
+applied **without executing its schema SQL**. It does not verify that the existing schema matches
+that SQL. Compare them, back up the target, and confirm credentials before invoking it.
+
+For a fresh database, run the normal Drizzle migrator, not baseline. Baseline refuses an empty
+database or unexpected migration history and is a no-op if the baseline marker already exists.
+
+The installed CLI is `workers-mysql-db-baseline --migrations ./drizzle`. It uses `DB_SECRET` or
+`DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, and `DB_NAME`. This command writes migration
+metadata; it is not a dry run. `/baseline-cli` exports `runBaselineCli` for tooling integrations.
+
+## Local tests
+
+`createTestDb({ dbName, migrationsFolder, connection })` from `/testing` returns fixture helpers.
+Use an isolated disposable database and explicit local connection settings:
+
+- `resetSchema()` **drops and recreates the database**, then applies migrations.
+- `truncateAll(pool)` deletes table contents, excluding migration bookkeeping.
+- `seed(pool, table, row)` inserts a fixture.
+- `createTestPool()` creates a pool; close it with `pool.end()` after testing.
+- `mysqlReachable()` probes connectivity, not schema correctness.
+
+Never point these helpers at shared or production data. Distinct test runs should use distinct
+database names. `createPoolDatabase({ pool, orm })` uses one pool for reads/writes and closes it
+on `dispose()`. `createNoopDatabase()` returns empty reads and throws on unexpected writes or
+transactions; it is a stub, not an acceptance test against MySQL.
+
+See [API](./api.md) for the available types.

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@rdlabo/workers-mysql",
+  "version": "0.1.0-beta.pr48.sha371f5792ce8a",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "description": "MySQL and Hyperdrive utilities for Cloudflare Workers",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rdlabo-dev/workers-hono-kit.git",
+    "directory": "packages/mysql"
+  },
+  "bugs": {
+    "url": "https://github.com/rdlabo-dev/workers-hono-kit/issues"
+  },
+  "homepage": "https://github.com/rdlabo-dev/workers-hono-kit/tree/main/packages/mysql#readme",
+  "files": [
+    "dist",
+    "bin",
+    "docs"
+  ],
+  "bin": {
+    "workers-mysql-db-baseline": "./bin/db-baseline.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./drizzle": {
+      "types": "./dist/drizzle.d.ts",
+      "import": "./dist/drizzle.js",
+      "default": "./dist/drizzle.js"
+    },
+    "./migrations": {
+      "types": "./dist/migrations.d.ts",
+      "import": "./dist/migrations.js",
+      "default": "./dist/migrations.js"
+    },
+    "./baseline-cli": {
+      "types": "./dist/baseline-cli.d.ts",
+      "import": "./dist/baseline-cli.js",
+      "default": "./dist/baseline-cli.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js",
+      "default": "./dist/testing/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:package": "node scripts/package-smoke.mjs",
+    "lint": "eslint \"src/**/*.ts\"",
+    "lint:fix": "eslint \"src/**/*.ts\" --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "mysql2": "^3.24.3"
+  },
+  "peerDependencies": {
+    "@types/node": ">=20.19.43",
+    "drizzle-orm": "^0.45.2"
+  },
+  "peerDependenciesMeta": {
+    "drizzle-orm": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@hono/eslint-config": "^2.1.0",
+    "@rdlabo/workers-timezone": "0.1.0-beta.pr48.sha371f5792ce8a",
+    "drizzle-orm": "^0.45.2",
+    "eslint": "^9.39.4",
+    "prettier": "^3.8.4",
+    "typescript": "~5.6.2",
+    "typescript-eslint": "^8.61.1",
+    "vitest": "^2.1.0"
+  }
+}