@lunora/cli 1.0.0-alpha.45 → 1.0.0-alpha.451

package/skills/lunora-setup-hyperdrive/SKILL.md

@@ -1,90 +1,65 @@
 ---
 name: lunora-setup-hyperdrive
-description: Connects an existing Postgres/MySQL database to a Lunora app from an action via Cloudflare Hyperdrive. Use for `@lunora/hyperdrive`, `ctx.sql`, `createHyperdrive` + `fromPostgresJs`/`fromNodePg`/`fromMysql2`, the `HYPERDRIVE` binding, `wrangler hyperdrive create`, and the action-only / non-reactive guardrails (live queries don't track external writes).
+description: Connects an existing, externally owned Postgres/MySQL database to a Lunora app through Cloudflare Hyperdrive. Lunora does not own its schema. Covers `@lunora/hyperdrive`, the action-only, non-reactive `ctx.sql` client (`createHyperdrive` + `fromPostgresJs`/`fromNodePg`/`fromMysql2`, wired with the app builder's `.hyperdrive()`), the `HYPERDRIVE` binding and `wrangler hyperdrive create`, and making external rows live through a projection or a `.source()` ingest table. Use when the user wants to "query our existing Postgres", "read the legacy DB from an action", "connect Neon/RDS/Supabase", or sync external rows into Lunora, or sees `ctx.sql` / `hyperdrive_outside_action` errors. For storing Lunora's own `.global()` tables in Postgres/MySQL with reactive live queries, use `lunora-setup-hyperdrive-global` instead.
 ---
 
 # Lunora Setup Hyperdrive
 
-Wire an **existing** Postgres/MySQL database into a Lunora app using
-`@lunora/hyperdrive`, which surfaces a [Cloudflare
-Hyperdrive](https://developers.cloudflare.com/hyperdrive/) binding's connection
-string and a driver-agnostic `ctx.sql` client — usable **only inside an
-`action`**.
-
-> **Integrate, don't replace.** Hyperdrive talks to a database Lunora has no
-> visibility into. Queries through `ctx.sql` are **non-deterministic** (forbidden
-> in `query`/`mutation`, enforced by the `hyperdrive_outside_action` advisor
-> lint) and external writes are **invisible to Lunora live queries** —
-> subscriptions will NOT re-run when external rows change. Use it to read/write a
-> legacy DB from an action; if you want that data reactive, write a projection
-> into a `defineSchema` DO/D1 table.
-
-## When to Use
-
-- Reading/writing an existing Postgres or MySQL database from a Lunora action.
-- Incrementally migrating off a legacy DB while standing up Lunora alongside it.
-- Backfilling/syncing external rows into reactive Lunora tables (projection).
-
-## When Not to Use
-
-- You want the external data to be **reactive** out of the box — it can't be;
-  Hyperdrive writes don't hit the change-feed. Project into a `defineSchema`
-  table instead.
-- You're reaching for `ctx.sql` inside a `query` or `mutation` — forbidden by
-  design (the advisor lint flags it). Move the access into an `action`.
-- The app has no Lunora backend yet — use `lunora-quickstart` first.
-- You'd be replacing `defineSchema` entirely — then you lose realtime, OCC,
-  optimistic updates, the offline queue, and the advisors. Use Lunora's own data
-  layer for app state.
-
-## Workflow
-
-1. Install `@lunora/hyperdrive` and one SQL driver.
-2. Create the Hyperdrive config (`wrangler hyperdrive create`) and add the
-   `HYPERDRIVE` binding to `wrangler.jsonc`.
-3. Regenerate types with `lunora codegen` so `ctx.sql` appears on `ActionCtx`.
-4. Read/write the external DB from an action via `ctx.sql`.
-5. (Optional) Project external rows into a `defineSchema` table to make them
-   reactive.
-
-## Step 1: Install the package + a driver
+`@lunora/hyperdrive` exposes a Cloudflare Hyperdrive binding as a
+driver-agnostic `ctx.sql` client that is available only inside an `action`. It integrates
+a database Lunora doesn't own. Don't use it to replace `defineSchema`, because you'd lose
+realtime, OCC, optimistic updates, the offline queue and the advisors.
+
+> **`ctx.sql` is not reactive.** Lunora cannot see this database, so subscriptions
+> do not re-run when its rows change, including rows you write through `ctx.sql`.
+> Queries are non-deterministic, so `ctx.sql` exists only on `ActionCtx`.
+> The `hyperdrive_outside_action` advisor lint flags any use in a
+> `query`/`mutation`. To make the data live, see Step 5. If you instead want Lunora-owned tables
+> stored in Postgres/MySQL and fully reactive, use `lunora-setup-hyperdrive-global`.
+
+## Step 1: Install the package + one driver
 
 ```bash
 pnpm add @lunora/hyperdrive
-# choose ONE driver (optional peer deps — none is bundled):
-pnpm add postgres        # postgres.js  → fromPostgresJs ($1, $2 placeholders)
-# or
-pnpm add pg              # node-postgres → fromNodePg     ($1, $2 placeholders)
-# or
-pnpm add mysql2          # mysql2        → fromMysql2      (?  placeholders)
+pnpm add postgres   # → fromPostgresJs   ($1, $2 placeholders)
+# or: pnpm add pg      → fromNodePg       ($1, $2)
+# or: pnpm add mysql2  → fromMysql2       (?)
 ```
 
+The drivers are optional peer dependencies, so none ships with the package.
+The package never rewrites SQL, so use your driver's native placeholders.
+
 ## Step 2: Create the binding
 
+Nothing to write by hand: `lunora dev` and `lunora deploy` add a `HYPERDRIVE` binding
+to `wrangler.jsonc` with a placeholder `id`.
+
+- **Dev.** `ctx.sql` runs on an embedded Postgres (PGlite), data in
+  `.wrangler/state/lunora-pglite`. Install its two optional packages:
+
 ```bash
-wrangler hyperdrive create my-db --connection-string="postgres://user:pass@host:5432/db" # gitleaks:allow -- placeholder, not a real secret
+pnpm add -D @electric-sql/pglite @electric-sql/pglite-socket
 ```
 
-This prints an `id`. Add the binding to `wrangler.jsonc`, using
-`localConnectionString` so `lunora dev` connects to your DB directly (no edge
-proxy locally):
-
-```jsonc
-{
-    "hyperdrive": [
-        {
-            "binding": "HYPERDRIVE",
-            "id": "<the id from the command above>",
-            "localConnectionString": "postgres://user:pass@localhost:5432/db", // gitleaks:allow -- placeholder, not a real secret
-        },
-    ],
-}
+To use your own database, set `localConnectionString` on the binding or
+`CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING>`; neither is overridden.
+
+- **Deploy.** Give `lunora deploy` the origin and a token that may edit Hyperdrive:
+
+```bash
+LUNORA_HYPERDRIVE_URL="postgres://user:pass@host:5432/db" lunora deploy # gitleaks:allow -- placeholder, not a real secret
 ```
 
-Lunora validates this binding (errors if `binding` is missing; warns if `id` is
-empty/placeholder — it can't connect), but it does **not** auto-write the `id`:
-that's a remote resource only `wrangler hyperdrive create` can mint. Importing
-`@lunora/hyperdrive` surfaces a hint reminding you to add it.
+(`CLOUDFLARE_API_TOKEN` with Hyperdrive: Edit, and `CLOUDFLARE_ACCOUNT_ID`; the variable is
+`LUNORA_<BINDING>_URL`.) Lunora creates the config, or reuses one of the same name, and writes
+its `id` into `wrangler.jsonc`. The connection string is never written or logged.
+
+To manage the config yourself, run `wrangler hyperdrive create my-db --connection-string=...`
+and put the `id` in the binding. Validation fails without a `binding`.
+
+Hyperdrive caches read results (up to 60 s plus 15 s stale by default) and a write does not
+invalidate them. For reads that must see your own writes, add a second config created with
+`--caching-disabled` and bind it under another name.
 
 ## Step 3: Regenerate types
 
@@ -92,63 +67,117 @@ that's a remote resource only `wrangler hyperdrive create` can mint. Importing
 lunora codegen
 ```
 
-When codegen sees `ctx.sql` used, it adds `sql: SqlClient` to **`ActionCtx`
-only** — never `QueryCtx`/`MutationCtx` — with a JSDoc restating the
-determinism/realtime caveat.
+When `ctx.sql` is used, codegen adds `readonly sql: SqlClient` to `ActionCtx` only. It also
+emits a `.hyperdrive()` method on the generated app builder.
 
-## Step 4: Use `ctx.sql` from an action
+## Step 4: Wire the client on the app builder
 
-```ts
+`ctx.sql` is `readonly`, so assigning it in a handler is a `TS2540` error.
+Codegen can't build the client because it depends on your driver, so supply a
+thunk instead. It runs once per shard construction, not per request:
+
+```ts title="src/server.ts"
+import type { HyperdriveLike } from "@lunora/hyperdrive";
 import { createHyperdrive, fromPostgresJs } from "@lunora/hyperdrive";
 import postgres from "postgres";
 
-import { action, v } from "@lunora/server";
+import { defineApp } from "../lunora/_generated/app.js";
 
-export const listLegacyOrders = action.input({ orgId: v.string() }).action(async ({ ctx, args: { orgId } }) => {
-    const { connectionString } = createHyperdrive(ctx.env.HYPERDRIVE);
-    ctx.sql = fromPostgresJs(postgres(connectionString));
+const app = defineApp<Env>()
+    .shard((env) => env.SHARD)
+    .hyperdrive((env) => fromPostgresJs(postgres(createHyperdrive(env.HYPERDRIVE as HyperdriveLike).connectionString, { fetch_types: false, max: 5 })))
+    .build();
 
-    return ctx.sql.query<{ id: string; total: number }>("select id, total from orders where org = $1", [orgId]);
+export const ShardDO = app.ShardDO;
+```
+
+Then query from any action:
+
+```ts
+import { LunoraError } from "lunorash/server";
+
+import { action, v } from "#lunora/_generated/server.js";
+
+export const listLegacyOrders = action.input({ orgId: v.string() }).action(async ({ ctx, args: { orgId } }) => {
+    if (!ctx.auth.userId) {
+        throw new LunoraError("UNAUTHORIZED", "not signed in");
+    }
+
+    // `orgId` comes from the client: the join scopes it to orgs the caller belongs to.
+    return ctx.sql.query<{ id: string; total: number }>(
+        "select o.id, o.total from orders o join org_members m on m.org_id = o.org where o.org = $1 and m.user_id = $2",
+        [orgId, ctx.auth.userId],
+    );
 });
 ```
 
-The package never rewrites SQL — use your driver's native placeholders (`$1` for
-Postgres, `?` for MySQL).
+**Verify:** call the action from the studio's function runner and check that it returns rows.
 
-## Step 5 (optional): Make it reactive via a projection
+## Step 5 (optional): Make external data reactive
 
-External writes don't hit the change-feed, so a subscription won't re-fire on a
-Postgres change. To make external data reactive, write a projection into a
-`defineSchema` table from the same action — that write _is_ tracked:
+Pick one approach:
+
+**A. Projection from an action.** This works when your app is the writer. Write the row into a
+`defineSchema` table through a mutation. That write is tracked:
 
 ```ts
+import { LunoraError } from "lunorash/server";
+
+import { internal } from "#lunora/_generated/internal.js";
+
 const [row] = await ctx.sql.query<{ id: string; total: number }>("select id, total from orders where id = $1", [id]);
 
-// This write re-runs live queries reading `orders`:
-await ctx.runMutation("orders:upsert", { id: row.id, total: row.total });
+if (!row) {
+    throw new LunoraError("NOT_FOUND", `order ${id} not found`);
+}
+
+// Re-runs live queries over `orders`. ctx.run* takes a generated reference, not a "file:fn" string.
+await ctx.runMutation(internal.orders.upsert, { id: row.id, total: row.total });
 ```
 
+**B. A `.source()` table.** This works when other systems also write the database. Lunora polls
+the external query on the shard's alarm, diffs the result, materializes it into the
+DO's SQLite and notifies subscribers, so you don't write an action or a cron:
+
+```ts
+// lunora/schema.ts
+messages: defineTable({ body: v.string(), channelId: v.string() })
+    .shardBy("channelId")
+    .source({
+        binding: "HYPERDRIVE",
+        query: 'select id, body, channel_id as "channelId" from messages where channel_id = $1',
+        tenantBy: (shardKey) => [shardKey], // required under .shardBy(): the tenant boundary
+    }),
+```
+
+```ts
+// worker entry: one client per binding name
+.sourceClient((env, binding) => fromPostgresJs(postgres((env[binding] as { connectionString: string }).connectionString, { fetch_types: false, max: 5 })))
+```
+
+How `.source()` behaves:
+
+- Freshness depends on the poll interval: every alarm tick by default,
+  `refresh: { everyMs }` to throttle it, or `"manual"`.
+- The table is read-only from Lunora: rows come only from the ingest loop.
+- The default `mode: "full-pull"` re-reads the whole slice on every tick, which
+  works up to about 10k rows. For larger slices, use `mode: "incremental"` with a
+  `cursor`, plus either `reconcileEveryMs` or `softDeleteColumn` so deletes are
+  still detected.
+- A source table can't also be `.global()`.
+
 ## Common Pitfalls
 
-1. **`ctx.sql` in a query/mutation.** It's action-only by design; the
-   `hyperdrive_outside_action` advisor lint flags it. Move the SQL into an
-   action.
-2. **Expecting external writes to be reactive.** They aren't — Lunora can't see
-   them. Project into a `defineSchema` table if you need reactivity.
-3. **Placeholder / empty `id`.** A Hyperdrive binding with no real `id` can't
-   connect (Lunora warns). Run `wrangler hyperdrive create` and paste the id.
-4. **Bundling a driver as a hard dependency.** Drivers are optional peer deps —
-   install the one you use; don't assume one ships with the package.
-5. **Wrong placeholder syntax.** `$1, $2` for Postgres drivers, `?` for mysql2.
-   The package does not rewrite SQL.
-
-## Checklist
-
-- [ ] `@lunora/hyperdrive` + one driver (`postgres`/`pg`/`mysql2`) installed.
-- [ ] `wrangler hyperdrive create` run; `HYPERDRIVE` binding added to
-      `wrangler.jsonc` with a real `id` and a `localConnectionString` for dev.
-- [ ] `lunora codegen` run so `ctx.sql` is typed on `ActionCtx`.
-- [ ] All `ctx.sql` access lives in actions (advisor clean — no
-      `hyperdrive_outside_action`).
-- [ ] If reactivity is needed, external rows are projected into a `defineSchema`
-      table.
+1. **`ctx.sql` in a query/mutation.** It's action-only. Move the SQL into an action.
+2. **Expecting `ctx.sql` writes to update subscriptions.** They don't. Use Step 5.
+3. **Placeholder `id` at deploy.** The deploy stops until `LUNORA_<BINDING>_URL` is set
+   (Lunora then creates the config) or the real `id` is pasted in. An empty `id` is not
+   provisioned: wrangler rejects it, so remove the entry and let Lunora add it again.
+4. **Wrong placeholders.** Use `$1` for `postgres`/`pg` and `?` for `mysql2`.
+5. **Array or JSON params on postgres.js with `fetch_types: false`.** A JS array bound to
+   `= ANY($1)` fails as a malformed array literal: bind `JSON.stringify(list)` to
+   `IN (SELECT jsonb_array_elements_text($1::text::jsonb))`. Cast JSON params `$1::text::jsonb`,
+   since a bare `$1::jsonb` gets your string JSON-encoded twice.
+6. **Unscoped `.source()` under `.shardBy()`.** Without `tenantBy`, every tenant's
+   rows are copied into each shard. `defineSchema` throws, and the
+   `external_source_unscoped` lint fails the build.

package/skills/lunora-setup-hyperdrive-global/SKILL.md

@@ -1,66 +1,63 @@
 ---
 name: lunora-setup-hyperdrive-global
-description: Use PlanetScale (Postgres/MySQL via Cloudflare Hyperdrive) as a first-class, REACTIVE `.global()` storage backend for a Lunora app — and migrate an existing D1 `.global()` dataset to it. Use for `@lunora/hyperdrive/global`, `.global({ backend: "hyperdrive" })`, `createHyperdriveGlobalCtxDb`, the app-builder `.hyperdriveGlobal()` declaration, the `HYPERDRIVE` binding pointing at PlanetScale, and `lunora migrate d1-to-hyperdrive`. NOT the same as `@lunora/hyperdrive` (which is an action-only, non-reactive `ctx.sql`).
+description: Stores a Lunora app's own `.global()` tables in Postgres or MySQL (PlanetScale, Neon, RDS, or any Hyperdrive-reachable database) through Cloudflare Hyperdrive instead of D1. Lunora owns the schema, and live queries stay fully reactive. Also migrates an existing D1 `.global()` dataset with `lunora migrate d1-to-hyperdrive`. Covers `.global({ backend: "hyperdrive" })`, `@lunora/hyperdrive/global` (`buildPgExec` / `buildMysqlExec`, `createHyperdriveGlobalCtxDb`), the app builder's `.hyperdriveGlobal({ engine, exec })`, and the `HYPERDRIVE` binding. Use when the user wants to "move global tables to PlanetScale/Postgres", "use Postgres instead of D1", or "migrate off D1", or edits `.global({ backend: "hyperdrive" })`. For querying an existing, externally owned database from an action (non-reactive `ctx.sql`), use `lunora-setup-hyperdrive` instead.
 ---
 
 # Lunora Setup: Hyperdrive Global Backend (Postgres/MySQL)
 
-Store Lunora `.global()` tables in a **Postgres or MySQL database reached
-through [Cloudflare Hyperdrive](https://developers.cloudflare.com/hyperdrive/)**
-— **PlanetScale**, Neon, RDS, or any Hyperdrive-reachable database — instead of
-D1, as a **drop-in, fully reactive** backend. (PlanetScale on Cloudflare is the
-headline use case; nothing here is PlanetScale-specific.)
+Store `.global()` (cross-tenant) tables in a Postgres or MySQL database reached
+through Cloudflare Hyperdrive instead of D1. PlanetScale on Cloudflare is the
+typical case, but nothing here is PlanetScale-specific.
 
-> **`@lunora/hyperdrive/global` vs. `@lunora/hyperdrive` (`ctx.sql`).** The
-> `ctx.sql` surface is an action-only, **non-reactive** escape hatch for
-> integrating a legacy database. `@lunora/hyperdrive/global` is different: Lunora
-> **owns** the schema (column-per-field, like D1) and routes every write through
-> its own store core, so live queries stay reactive — the writer is injected as
-> `globalDb` and the shard DO's broadcast hook re-runs subscriptions exactly as
-> with D1.
-
-## When to Use
-
-- You want `.global()` (cross-tenant) tables to live in PlanetScale rather than
-  D1 — e.g. for larger datasets, existing SQL tooling, or unified Cloudflare
-  billing.
-- You're migrating an existing D1 `.global()` dataset to PlanetScale.
+> **This is not `ctx.sql`.** `@lunora/hyperdrive`'s `ctx.sql`
+> (`lunora-setup-hyperdrive`) is an action-only, non-reactive client for a
+> database Lunora doesn't own. `.global({ backend: "hyperdrive" })` is the opposite:
+> Lunora owns the tables (one column per field, like D1), and every write goes
+> through Lunora's store core. Subscriptions re-run exactly as they do with D1.
+> The live-query guarantee covers only writes made through Lunora (`ctx.db`).
+> Rows written to the database directly are invisible to live queries.
 
 ## When Not to Use
 
-- You only need to read/write a **legacy** external DB from an action — use
-  `@lunora/hyperdrive` (`ctx.sql`) instead; it's lighter and action-scoped.
-- Your global data is small and D1 is fine — bare `.global()` (D1) needs no
-  extra binding or driver.
+- You only need to read or write a legacy database from an action: use
+  `lunora-setup-hyperdrive`.
+- Your global data is small and D1 is fine: bare `.global()` needs no extra
+  binding or driver.
 
 ## How it works
 
-PlanetScale reuses Lunora's dialect-parameterized store core (the same one D1
-uses): a `SqlDialect` (Postgres or MySQL) shapes the SQL, and a Hyperdrive-backed
-`SqlExec` runs it from inside the Durable Object that hosts the global writer.
-Values are stored SQLite-shaped (boolean → 1/0, JSON → text/json, bigint →
-decimal), so the value codec is shared with D1.
+The same dialect-parameterized store core that backs D1 runs here with a
+Postgres or MySQL `SqlDialect`. A Hyperdrive-backed `SqlExec` executes it from
+inside the Durable Object that hosts the global writer. Values are stored in the
+same shapes D1 uses (boolean → 1/0, JSON → text/json, bigint → decimal).
 
-## Step 1: Install the package + a driver
+## Step 1: Install
 
 ```bash
-pnpm add @lunora/hyperdrive/global
-# choose the driver matching your engine (optional peer deps — none is bundled):
-pnpm add postgres        # PlanetScale Postgres → fromPostgresJs
-# or
-pnpm add mysql2          # PlanetScale MySQL    → mysql2/promise
+pnpm add @lunora/hyperdrive @lunora/sql-store
+pnpm add postgres   # Postgres engine → buildPgExec(fromPostgresJs(...))
+# or: pnpm add mysql2  → buildMysqlExec(mysql2/promise pool), MySQL 8.0+
 ```
 
-## Step 2: Create the Hyperdrive binding pointing at PlanetScale
+`@lunora/hyperdrive/global` is a subpath export of `@lunora/hyperdrive`, not a
+separate package. Codegen requires `@lunora/sql-store` too, because the generated
+`_generated/app.ts` imports its `SqlExec` types. Install the driver that matches
+your engine. Drivers are optional peer dependencies.
 
-Create a PlanetScale database from the Cloudflare dashboard (unified billing),
-then a Hyperdrive config over its connection string:
+## Step 2: Create the Hyperdrive binding
 
 ```bash
-wrangler hyperdrive create my-db --connection-string="postgres://user:pass@host/db" # gitleaks:allow -- placeholder
+wrangler hyperdrive create my-db --connection-string="postgres://user:pass@host/db" --caching-disabled # gitleaks:allow -- placeholder
 ```
 
-Add the binding to `wrangler.jsonc` (use `localConnectionString` for `lunora dev`):
+**Query caching must be off** for the config behind `.global()`. Hyperdrive
+caches reads by default (60 s plus 15 s stale-while-revalidate) and a write does
+not invalidate them, so the store would read its own rows stale: OCC retries
+reread the cached version and fail with spurious conflicts, and live queries
+re-run onto old data. For a config that already exists, run
+`wrangler hyperdrive update <id> --caching-disabled`. When `lunora deploy`
+creates the config from `LUNORA_<BINDING>_URL`, it turns caching off itself. For a
+binding that already has an id, it only warns (given Cloudflare API credentials).
 
 ```jsonc
 {
@@ -70,10 +67,14 @@ Add the binding to `wrangler.jsonc` (use `localConnectionString` for `lunora dev
 }
 ```
 
-> **Read-your-writes:** point the Hyperdrive config at the **primary** (or pin
-> writes to it) so a write then immediate read isn't served by a stale replica.
+A binding is required. Without any `hyperdrive` entry, config validation errors
+and `lunora dev` / `lunora deploy` won't start. You choose the name: the
+validator only checks that at least one binding exists, and your `exec` selector picks it.
+
+Point Hyperdrive at the primary (or pin writes to it) so you can read your own
+writes. A replica can serve a stale read right after a write.
 
-## Step 3: Mark tables `.global({ backend: "hyperdrive" })`
+## Step 3: Mark tables
 
 ```ts
 // lunora/schema.ts
@@ -84,88 +85,120 @@ export default defineSchema({
 });
 ```
 
-A bare `.global()` stays on D1. **One backend per app** — mixing D1- and
-PlanetScale-backed global tables in the same app isn't supported yet (codegen
-errors clearly).
+Bare `.global()` stays on D1. An app can use only one global backend: codegen fails
+if the schema mixes D1 and Hyperdrive global tables.
 
-## Step 4: Wire `.hyperdriveGlobal()` in the app composition
+## Step 4: Wire `.hyperdriveGlobal()`
 
-Codegen emits a `.hyperdriveGlobal()` builder method. Supply the engine and an `exec`
-built from the Hyperdrive binding (cache the driver on the DO instance; rebuild
-lazily after hibernation):
+Codegen emits a `.hyperdriveGlobal({ engine, exec, origin? })` builder method.
+`exec` builds a `SqlExec` from `env`:
 
 ```ts
-import { buildPgExec } from "@lunora/hyperdrive/global";
 import { fromPostgresJs } from "@lunora/hyperdrive";
+import { buildPgExec } from "@lunora/hyperdrive/global";
 import postgres from "postgres";
 
-export default defineApp<Env>()
+import { defineApp } from "../lunora/_generated/app.js";
+
+const app = defineApp<Env>()
     .shard((env) => env.SHARD)
     .hyperdriveGlobal({
         engine: "postgres",
-        exec: (env) => buildPgExec(fromPostgresJs(postgres(env.HYPERDRIVE.connectionString))),
-    });
+        exec: (env) => buildPgExec(fromPostgresJs(postgres(env.HYPERDRIVE.connectionString, { fetch_types: false, max: 5 }))),
+    })
+    .build();
+
+export const ShardDO = app.ShardDO;
 ```
 
-For MySQL, create the pool with the **`FOUND_ROWS`** flag (the optimistic-concurrency
-guard needs matched-row counts, or idempotent writes raise spurious conflicts):
+For MySQL, create the pool with the `FOUND_ROWS` flag. The optimistic-concurrency
+guard needs matched-row counts. Without the flag, an idempotent write reports
+zero affected rows and raises a spurious conflict. `buildMysqlExec` throws at
+construction when the flag is missing. If it can't read the flag, it warns once instead.
 
 ```ts
 import { buildMysqlExec } from "@lunora/hyperdrive/global";
 import mysql from "mysql2/promise";
 
+// inside the builder chain:
 .hyperdriveGlobal({
     engine: "mysql",
-    exec: (env) => buildMysqlExec(mysql.createPool({ uri: env.HYPERDRIVE.connectionString, flags: ["FOUND_ROWS"] })),
-});
+    // disableEval: mysql2 needs it to run on Workers.
+    exec: (env) => buildMysqlExec(mysql.createPool({ uri: env.HYPERDRIVE.connectionString, disableEval: true, flags: ["FOUND_ROWS"] })),
+})
 ```
 
-## Step 5: Regenerate + run
+Outside the app builder, for example in tests or a custom host,
+`createHyperdriveGlobalCtxDb({ engine, exec, ... })` builds the same reactive writer
+directly.
+
+## Step 5: Regenerate and run
 
 ```bash
-lunora codegen   # wires config.hyperdriveGlobal and the .hyperdriveGlobal() method
+lunora codegen
 lunora dev
 ```
 
-Tables auto-provision on first use (the runtime runs the PlanetScale DDL through
-the dialect — no manual migration needed), and subscriptions are reactive.
+Tables provision automatically on first use, because the runtime runs the DDL
+through the dialect. You don't write or commit SQL migrations. `CREATE TABLE IF NOT EXISTS` never
+reshapes an existing table, though. When a column's validator starts accepting
+null, the store reports the `ALTER` statement to run. MySQL tables created before
+the `utf8mb4_0900_bin` column collation need a one-off
+`ALTER TABLE … CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_bin`.
+See `lunora-migration-helper` for schema changes.
 
-## Migrating an existing D1 dataset → PlanetScale
+**Verify:** subscribe to a query over a hyperdrive-backed table, write through a
+mutation, and confirm that the subscription updates.
 
-Blue-green: deploy the new PlanetScale-backed worker alongside the old D1 one,
-then copy the `.global()` data:
+Postgres deployments can also serve `ctx.vectors` from pgvector instead of a Vectorize
+binding with `createPgVectorIndex` (from `@lunora/hyperdrive/global`). It supports
+equality-only metadata filters.
+
+## Migrating an existing D1 dataset
+
+The flow is blue-green: deploy the Hyperdrive-backed worker next to the D1 one,
+then copy the data:
 
 ```bash
 lunora migrate d1-to-hyperdrive \
-  --from-url https://old-d1.example.com   --from-token "$D1_ADMIN_TOKEN" \
-  --to-url   https://new-ps.example.com   --to-token   "$PS_ADMIN_TOKEN" \
-  --tables settings,orders                # omit to move every global table
-  # --out dump.ndjson                      # keep the intermediate dump to inspect
+  --from-url https://old-d1.example.com --from-token "$D1_ADMIN_TOKEN" \
+  --to-url   https://new-hd.example.com --to-token   "$HD_ADMIN_TOKEN" \
+  --tables settings,orders   # omit to move every global table; --out dump.ndjson keeps the dump
 ```
 
-It streams the source's global rows to NDJSON, imports them into the target
-(whose `.global({ backend: "hyperdrive" })` tables route the writes to
-PlanetScale), and verifies the row counts match. Rows whose `_id` already exists
-are reported as conflicts, not duplicated.
-
-> **Direct external writes** to PlanetScale (bypassing Lunora) are invisible to
-> live queries — same as D1. Let Lunora own the writes.
+The command exports the source's global rows to NDJSON, imports them into the
+target, and compares row counts. It refuses to run when the source and target
+resolve to the same URL, and non-localhost URLs must use https. Rows whose `_id`
+already exists in the target are reported as conflicts and not duplicated.
+A count mismatch is a warning: inspect it with `--out`, resolve it, and re-run.
+Tokens default to `--token` / `LUNORA_ADMIN_TOKEN`.
+
+To roll back, run `lunora migrate hyperdrive-to-d1` with the same flags, the
+Hyperdrive deployment as `--from-url` and the D1 one as `--to-url`. The target's
+`.global()` backend decides where the rows land, so the copy works the same way
+in both directions.
+
+Without `--replace` the rollback restores rows missing from D1, not edits made
+on Hyperdrive since cutover: a row D1 already holds is a conflict and keeps its
+D1 values. Add `--replace` (plus `--tables` naming the `.global()` tables, and
+`--yes` for a remote target) to overwrite those
+rows with the Hyperdrive values, or keep the dump with `--out` and reconcile by
+hand. Neither mode carries deletions over: a row deleted on Hyperdrive since
+cutover is still in D1 afterwards, so remove those by hand.
 
 ## Common Pitfalls
 
-1. **Mixing backends.** One global backend per app (codegen errors on a mix).
-2. **Missing driver.** `postgres`/`mysql2` are optional peer deps — install the
-   one matching your engine.
-3. **Stale-replica reads.** Point Hyperdrive at the primary for read-your-writes.
-4. **Expecting external writes to be reactive.** They aren't — route writes
-   through Lunora (`ctx.db`).
-
-## Checklist
-
-- [ ] `@lunora/hyperdrive/global` + the engine's driver installed.
-- [ ] Hyperdrive binding (`HYPERDRIVE`) created over the PlanetScale connection
-      string, with a `localConnectionString` for dev.
-- [ ] Target tables marked `.global({ backend: "hyperdrive" })` (one backend per app).
-- [ ] `.hyperdriveGlobal({ engine, exec })` wired in the app composition.
-- [ ] `lunora codegen` run; `lunora dev` serves the tables reactively.
-- [ ] (Migrating) `lunora migrate d1-to-hyperdrive` run; row counts verified.
+1. **Installing `@lunora/hyperdrive/global` as a package name.** It's a subpath.
+   Install `@lunora/hyperdrive` and `@lunora/sql-store`.
+2. **Mixing D1 and Hyperdrive global tables.** Codegen rejects this.
+3. **Missing `FOUND_ROWS` on MySQL.** It causes spurious OCC conflicts on idempotent writes.
+4. **Stale-replica reads.** Point Hyperdrive at the primary.
+5. **Query caching left on.** Spurious OCC conflicts and live queries stuck up to
+   75 s behind writes. Disable caching on the config (`--caching-disabled`). Local dev
+   has no cache, so this shows up only once deployed.
+6. **MySQL with `NO_BACKSLASH_ESCAPES` in `sql_mode`.** Unsupported: statements are
+   sent as text and a backslash in a string is escaped as `\\`, which that mode stores as
+   two backslashes. Quotes are doubled, so no value can leave its literal under either
+   mode. MySQL's default `sql_mode` doesn't include it.
+7. **Writing to the database directly.** Live queries won't see those writes. Route writes
+   through `ctx.db`.