--- 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). --- # 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 ```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) ``` ## Step 2: Create the binding ```bash wrangler hyperdrive create my-db --connection-string="postgres://user:pass@host:5432/db" # gitleaks:allow -- placeholder, not a real secret ``` 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 }, ], } ``` 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. ## Step 3: Regenerate types ```bash 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. ## Step 4: Use `ctx.sql` from an action ```ts import { createHyperdrive, fromPostgresJs } from "@lunora/hyperdrive"; import postgres from "postgres"; import { action, v } from "@lunora/server"; export const listLegacyOrders = action.input({ orgId: v.string() }).action(async ({ ctx, args: { orgId } }) => { const { connectionString } = createHyperdrive(ctx.env.HYPERDRIVE); ctx.sql = fromPostgresJs(postgres(connectionString)); return ctx.sql.query<{ id: string; total: number }>("select id, total from orders where org = $1", [orgId]); }); ``` The package never rewrites SQL — use your driver's native placeholders (`$1` for Postgres, `?` for MySQL). ## Step 5 (optional): Make it reactive via a projection 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: ```ts 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 }); ``` ## 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.