@mediamonks/canopy-cli 0.5.1 → 0.6.0

package/dist/{db-BW1ZolWn.mjs → db-BpnjQUkF.mjs}

@@ -1,5 +1,6 @@
-import { a as projectFlagArgs, s as resolveProject } from "./site-BJjoePQS.mjs";
-import { i as unwrap, l as withContext, n as reportErrors, o as apiDataRequest, r as requireTty } from "./ui-DThlyHgo.mjs";
+import { c as resolveProject, o as projectFlagArgs } from "./site-DQnysZ3W.mjs";
+import { i as unwrap, l as withContext, n as reportErrors, o as apiDataRequest, r as requireTty } from "./ui-BhzMeKQl.mjs";
+import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-B0kJarjr.mjs";
 import { defineCommand } from "citty";
 import { readFileSync, writeFileSync } from "node:fs";
 import * as p from "@clack/prompts";
@@ -12,6 +13,7 @@ import * as p from "@clack/prompts";
 * snapshot  store a dump server-side (restorable from CLI or dashboard)
 * snapshots list stored snapshots
 * restore   replace ALL project data from a snapshot or a local .sql file
+* migrate   apply pending schema migrations (docs/13-migrations-and-drizzle.md)
 *
 * The project comes from canopy.json in the current directory, or
 * --project <slug>.
@@ -20,7 +22,7 @@ const formatSize = (bytes) => bytes < 1024 * 1024 ? `${(bytes / 1024).toFixed(1)
 const dbCommand = defineCommand({
 	meta: {
 		name: "db",
-		description: "Data tools: pull, snapshot, snapshots, restore"
+		description: "Data tools: pull, snapshot, snapshots, restore, migrate"
 	},
 	subCommands: {
 		pull: defineCommand({
@@ -141,6 +143,43 @@ const dbCommand = defineCommand({
 				else if (file) await withContext(apiDataRequest("POST", "/db/restore", slug, readFileSync(file, "utf8"), "application/sql"), restoreContext);
 				p.log.success(`Restored ${slug}.`);
 			})
+		}),
+		migrate: defineCommand({
+			meta: {
+				name: "migrate",
+				description: "Apply pending schema migrations to the project database"
+			},
+			args: {
+				...projectFlagArgs,
+				plan: {
+					type: "boolean",
+					default: false,
+					description: "Dry run: list pending migrations without applying anything"
+				}
+			},
+			run: reportErrors("db migrate", async ({ args }) => {
+				const { dir, slug } = resolveProject(args);
+				const files = readMigrationFiles(dir);
+				if (files === void 0) throw new Error("No migrations directory configured — set \"migrations\" in canopy.json (e.g. {\"migrations\": \"./migrations\"}, pointing at your drizzle-kit output).");
+				if (args.plan) {
+					const result = await withContext(migrateProject(slug, files, true), { action: `plan migrations for "${slug}"` });
+					if (result.pending.length === 0) console.log(`Nothing pending (${result.applied.length} applied previously).`);
+					else for (const name of result.pending) console.log(`pending ${name}`);
+					for (const line of describeMigrateResult(result)) console.log(line);
+					return;
+				}
+				const spin = p.spinner();
+				spin.start(`Migrating ${slug}…`);
+				let result;
+				try {
+					result = await withContext(migrateProject(slug, files), { action: `migrate "${slug}"` });
+				} catch (err) {
+					spin.error("Migrate failed.");
+					throw err;
+				}
+				spin.stop(result.appliedNow.length === 0 ? `Nothing pending for ${slug}.` : `Applied ${result.appliedNow.length} migration(s) to ${slug}.`);
+				for (const line of describeMigrateResult(result)) console.log(`  ${line}`);
+			})
 		})
 	}
 });

package/dist/{deploy-alC2--pZ.mjs → deploy-DdSSL227.mjs}

@@ -1,5 +1,6 @@
-import { a as projectFlagArgs, c as tryReadCanopyJson, i as projectDirArgs, n as siteConfig, o as projectUrl, s as resolveProject } from "./site-BJjoePQS.mjs";
-import { c as apiRequest, i as unwrap, l as withContext, n as reportErrors, s as apiDownload } from "./ui-DThlyHgo.mjs";
+import { a as projectDirArgs, c as resolveProject, l as tryReadCanopyJson, n as siteConfig, o as projectFlagArgs, s as projectUrl } from "./site-DQnysZ3W.mjs";
+import { c as apiRequest, i as unwrap, l as withContext, n as reportErrors, o as apiDataRequest, s as apiDownload } from "./ui-BhzMeKQl.mjs";
+import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-B0kJarjr.mjs";
 import { defineCommand } from "citty";
 import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -46,6 +47,10 @@ async function bundleWorker(projectDir, entry) {
 *
 * Reads canopy.json in the project root:
 *   { "slug": "my-app", "dist": ".", "build": "npm run build" }
+*
+* A "migrations" dir in canopy.json adds a schema step (docs/13): pending
+* migrations apply after the bundle is staged and before the version flips —
+* schema first, then code. A migration failure aborts the deploy.
 */
 /** Must match apps/api/src/routes/deploys.ts WORKER_BUNDLE_PATH. */
 const WORKER_BUNDLE_PATH = "_canopy/worker.mjs";
@@ -97,12 +102,23 @@ const deployCommand = defineCommand({
 			default: true,
 			description: "Run the canopy.json build command first",
 			negativeDescription: "Skip the build, deploy the output directory as-is"
+		},
+		migrate: {
+			type: "boolean",
+			default: true,
+			description: "Apply pending schema migrations before the version goes live",
+			negativeDescription: "Skip migrations, deploy the code only"
 		}
 	},
 	run: reportErrors("deploy", async ({ args }) => {
 		const { dir, slug } = resolveProject(args);
 		const config = tryReadCanopyJson(dir) ?? {};
 		if (config.build && args.build) await runBuild(config.build, dir);
+		const migrations = args.migrate ? readMigrationFiles(dir) : void 0;
+		if (migrations !== void 0 && config.dialect) try {
+			const { dialect } = await apiDataRequest("GET", "/platform", slug);
+			if (dialect !== config.dialect) p.log.warn(`canopy.json pins dialect "${config.dialect}" but this site's database speaks ${dialect} — the migrations below were probably written for a different target.`);
+		} catch {}
 		const distDir = resolve(dir, config.dist ?? ".");
 		let paths;
 		try {
@@ -140,6 +156,7 @@ const deployCommand = defineCommand({
 		const workerNote = workerBytes ? " + worker" : "";
 		spin.start(`Deploying ${files.length} files${workerNote} (${(total / 1024).toFixed(0)} kB) → ${slug}`);
 		let result;
+		let migrateResult;
 		try {
 			const { upload } = await withContext(apiRequest("POST", `/projects/${slug}/deploys`, { worker: workerBytes !== null }, void 0, source), { action: `deploy "${slug}"` });
 			const uploads = [...files, ...workerBytes ? [{
@@ -147,6 +164,15 @@ const deployCommand = defineCommand({
 				data: workerBytes
 			}] : []];
 			await uploadFiles(upload.grant, uploads);
+			if (migrations !== void 0 && migrations.length > 0) {
+				spin.message(`Applying schema migrations → ${slug}`);
+				try {
+					migrateResult = await withContext(migrateProject(slug, migrations), { action: `migrate "${slug}"` });
+				} catch (err) {
+					spin.error("Deploy aborted — migrations failed; the live version is unchanged.");
+					throw err;
+				}
+			}
 			({deploy: result} = await withContext(apiRequest("POST", `/projects/${slug}/deploys/${upload.version}/complete`, { grant: upload.grant }, void 0, source), { action: `deploy "${slug}"` }));
 		} catch (err) {
 			spin.error("Deploy failed.");
@@ -154,6 +180,7 @@ const deployCommand = defineCommand({
 		}
 		const backend = result.worker?.serviceUrl ? ` · backend ${result.worker.serviceUrl}` : "";
 		spin.stop(`Live: ${projectUrl(slug)} (v${result.version})${backend}`);
+		if (migrateResult !== void 0) for (const line of describeMigrateResult(migrateResult)) console.log(`  ${line}`);
 	})
 });
 const UPLOAD_CONCURRENCY = 8;

package/dist/dev-DV5ud7AJ.mjs

@@ -0,0 +1,2 @@
+import { t as devCommand } from "./dev-OxeYndd1.mjs";
+export { devCommand };

package/dist/{dev-CQQhMOoD.mjs → dev-OxeYndd1.mjs}

@@ -1,5 +1,6 @@
-import { i as projectDirArgs, n as siteConfig, s as resolveProject } from "./site-BJjoePQS.mjs";
-import { a as ApiError, c as apiRequest, l as withContext, n as reportErrors } from "./ui-DThlyHgo.mjs";
+import { a as projectDirArgs, c as resolveProject, i as projectDialect, l as tryReadCanopyJson, n as siteConfig } from "./site-DQnysZ3W.mjs";
+import { a as ApiError, c as apiRequest, l as withContext, n as reportErrors } from "./ui-BhzMeKQl.mjs";
+import { r as readMigrationFiles } from "./migrations-B0kJarjr.mjs";
 import { createRequire } from "node:module";
 import { defineCommand } from "citty";
 import { join } from "node:path";
@@ -91,14 +92,19 @@ async function devRemote(flags, slug) {
 	} } });
 	console.log(`\n  ${slug} — remote-first dev against LIVE project data`);
 	console.log("  (worried about a risky change? `canopy db snapshot` first, or work");
-	console.log("   on a local copy instead: `canopy dev --local --pull`)\n");
+	console.log("   on a local copy instead: `canopy dev --local --pull`)");
+	if (tryReadCanopyJson(flags.dir)?.migrations) {
+		console.log("  migrations apply on `canopy deploy`, never from dev — use --local");
+		console.log("  while the schema is in flux");
+	}
+	console.log("");
 	server.printUrls();
 	console.log(`\n  Dev token expires ${expires_at} — restart canopy dev after that.`);
 }
 async function devLocal(flags, slug) {
 	let dump;
 	if (flags.pull) {
-		const { fetchProjectDump } = await import("./local-C5-GWJcx.mjs");
+		const { fetchProjectDump } = await import("./local-D9OVEHDg.mjs");
 		console.log(`Pulling a fresh export of ${slug}…`);
 		dump = await fetchProjectDump(slug);
 	}
@@ -113,16 +119,22 @@ async function devLocal(flags, slug) {
 		const reason = err instanceof ApiError ? err.explain().why : String(err);
 		console.log(`Note: ai/services will be unavailable — could not reach the platform (${reason}).`);
 	}
-	const { createSandbox } = await import("./local-C5-GWJcx.mjs");
+	const { createSandbox } = await import("./local-D9OVEHDg.mjs");
 	const sandbox = await createSandbox({
 		slug,
 		persistDir: join(flags.dir, ".canopy", "local"),
-		email: siteConfig().email
+		email: siteConfig().email,
+		dialect: flags.dialect
 	});
 	if (dump !== void 0) {
 		await sandbox.applyDump(dump);
 		console.log(`Hydrated the sandbox (${(dump.length / 1024).toFixed(1)} kB of SQL).`);
 	}
+	const migrationFiles = readMigrationFiles(flags.dir);
+	if (migrationFiles !== void 0 && migrationFiles.length > 0) {
+		const { applied } = await sandbox.applyMigrations(migrationFiles);
+		if (applied.length > 0) console.log(`Applied ${applied.length} pending migration(s): ${applied.join(", ")}`);
+	}
 	const handleApi = async (req, res) => {
 		const chunks = [];
 		for await (const chunk of req) chunks.push(chunk);
@@ -170,8 +182,10 @@ async function devLocal(flags, slug) {
 		apiServer.close();
 		sandbox.dispose();
 	});
-	console.log(`\n  ${slug} — LOCAL sandbox (PGlite + filesystem blobs in .canopy/local/)`);
+	const engine = flags.dialect === "sqlite" ? "SQLite" : "PGlite";
+	console.log(`\n  ${slug} — LOCAL sandbox (${engine} + filesystem blobs in .canopy/local/)`);
 	console.log("  data is yours alone: db and blob writes never reach the platform");
+	if (flags.dialect === void 0) console.log("  raw sql() speaks postgres here — on a D1 site? lock \"dialect\" in canopy.json");
 	if (dump === void 0) console.log("  (want prod data? restart with --pull to hydrate from a fresh export)");
 	console.log("  blobs are not pulled — the local blob store starts empty");
 	console.log(remote ? "  ai/services pass through to the platform (metered as usual)" : "  ai/services answer 501 until you log in and restart");
@@ -192,7 +206,7 @@ const devCommand = defineCommand({
 		local: {
 			type: "boolean",
 			default: false,
-			description: "Local-data sandbox (PGlite + blobs under .canopy/local/) instead of live data"
+			description: "Local-data sandbox (database + blobs under .canopy/local/) instead of live data"
 		},
 		pull: {
 			type: "boolean",
@@ -209,7 +223,8 @@ const devCommand = defineCommand({
 			dir,
 			port,
 			local: args.local,
-			pull: args.pull
+			pull: args.pull,
+			dialect: projectDialect(dir)
 		};
 		await (flags.local ? devLocal(flags, slug) : devRemote(flags, slug));
 	})

package/dist/docs/ci.md

@@ -1,10 +1,8 @@
 ---
 title: CI and deploy tokens
-summary: Push-to-main deploys using a project-scoped deploy token.
+description: Push-to-main deploys using a project-scoped deploy token.
 ---
 
-# CI and deploy tokens
-
 Interactive `canopy login` is for humans at a terminal. For automated deploys
 (GitHub Actions, etc.) use a **deploy token**: a project-scoped credential that
 can deploy that one project and nothing else.

package/dist/docs/cli.md

@@ -1,12 +1,11 @@
 ---
 title: CLI command reference
-summary: Every canopy command, its flags, and what it does.
+description: Every canopy command, its flags, and what it does.
 ---
 
-# CLI command reference
-
 Run `canopy <command> --help` for the authoritative flags of any command. This
-is the overview.
+is the one-page overview; the docs site's [CLI reference](https://docs.canopy.website/cli) section
+has a full page per command.
 
 ## Auth
 

package/dist/docs/data.md

@@ -1,10 +1,8 @@
 ---
 title: Working with project data
-summary: Pulling, snapshotting, and restoring your project database.
+description: Pulling, snapshotting, and restoring your project database.
 ---
 
-# Working with project data
-
 Each Canopy project gets its own database and blob storage (D1 and R2 on the
 Cloudflare target; Postgres and GCS on GCP). Your app reads and writes them
 through the Canopy SDK at runtime; the CLI gives you tools to manage the data
@@ -65,7 +63,10 @@ risky change.
 
 ## Restore — destructive
 
-Restoring **replaces ALL project data**:
+> **Warning:** Restoring **replaces ALL project data**. Take a snapshot first — a snapshot taken seconds earlier
+> is your undo button.
+
+Restore from either source:
 
 ```bash
 canopy db restore backup.sql          # from a local dump

package/dist/docs/deploy.md

@@ -1,10 +1,8 @@
 ---
 title: Deploying a project
-summary: How canopy deploy builds, uploads, and makes a version live.
+description: How canopy deploy builds, uploads, and makes a version live.
 ---
 
-# Deploying a project
-
 From inside a project directory:
 
 ```bash

package/dist/docs/dev.md

@@ -1,10 +1,8 @@
 ---
 title: Local development
-summary: Running a project locally against live or sandboxed data.
+description: Running a project locally against live or sandboxed data.
 ---
 
-# Local development
-
 From inside a project directory:
 
 ```bash
@@ -20,14 +18,14 @@ develop against realistic state.
 ## Offline sandbox
 
 To develop without touching live data — for example on a plane, or before you
-trust a destructive change — use a local sandbox backed by PGlite (embedded
-Postgres) and a filesystem blob store:
+trust a destructive change — use a local sandbox backed by an embedded database
+and a filesystem blob store:
 
 ```bash
 canopy dev --local
 ```
 
-This creates local Postgres data and blobs under `.canopy/local/` in your
+This creates a local database and blobs under `.canopy/local/` in your
 project. The sandbox starts empty.
 
 To seed the sandbox from a fresh copy of production data first:
@@ -38,11 +36,15 @@ canopy dev --local --pull
 
 `.canopy/local/` is disposable — delete it to reset the sandbox.
 
-One caveat: the sandbox database is Postgres, so raw `canopy.db.sql()` speaks
-the postgres dialect there, while your deployed project speaks whatever its
-platform target speaks (`canopy.db.dialect()` tells you — sqlite on
-Cloudflare). Collections (`canopy.db.collection(...)`) behave the same in both,
-so this only matters for hand-written SQL — see `canopy docs data`.
+By default the sandbox runs PGlite (embedded Postgres), so raw
+`canopy.db.sql()` speaks the postgres dialect there, while your deployed
+project speaks whatever its platform target speaks (`canopy.db.dialect()`
+tells you — sqlite on Cloudflare). Collections (`canopy.db.collection(...)`)
+behave the same in both, so this only matters for hand-written SQL — see
+`canopy docs data`. If your project's raw SQL targets a sqlite site, lock the
+dialect in `canopy.json` (`"dialect": "sqlite"`) and the sandbox runs an
+embedded SQLite engine instead, so the same SQL works locally and deployed —
+see [canopy dev](https://docs.canopy.website/cli/dev).
 
 ## Which mode should an agent use?
 

package/dist/docs/getting-started.md

@@ -1,10 +1,8 @@
 ---
 title: Getting started
-summary: Install the CLI, sign in with OneLogin, and ship your first project.
+description: Install the CLI, sign in with OneLogin, and ship your first project.
 ---
 
-# Getting started with Canopy
-
 Canopy is Monks' managed platform for vibecoded projects. You build a small web
 app, and Canopy hosts it, gives it a database, blob storage, and AI — no
 infrastructure to manage.

package/dist/docs/infrastructure.md

@@ -1,4 +1,7 @@
-# Infrastructure as code & standing up a Cloudflare account
+---
+title: Infrastructure as code
+description: Terraform for the account-level Cloudflare pieces Canopy needs.
+---
 
 Canopy's Cloudflare footprint is small on purpose: almost everything
 per-project is provisioned at runtime by canopy-api (`apps/api/src/cf.ts`,
@@ -19,8 +22,8 @@ Scope of a fresh stand-up:
 
 1. the **platform workers** — `canopy-api` and `canopy-gateway` — deployed and
    healthy (these aren't optional; nothing works without them), and
-2. the **three core projects** — `dashboard`, `www`, `kitchen-sink` — re-created
-   and deployed _on_ the platform like any other project.
+2. the **four core projects** — `dashboard`, `www`, `docs`, `kitchen-sink` —
+   re-created and deployed _on_ the platform like any other project.
 
 Everyone else's projects are **not** carried over — a new account starts with
 an empty control-plane registry (see [Non-goals](#non-goals)).
@@ -39,8 +42,8 @@ config file per Cloudflare site (same names as CLI profiles). Deployed with
 is local `wrangler dev` only.
 
 **`canopy deploy`** (`canopy.json` in each project): the core projects
-(`dashboard`, `www`, `kitchen-sink`) — ordinary platform projects that
-dogfood the product, not infrastructure.
+(`dashboard`, `www`, `docs`, `kitchen-sink`) — ordinary platform projects
+that dogfood the product, not infrastructure.
 
 **Bootstrap scripts** (`infra/scripts/`): runtime API tokens, worker secrets,
 AI Gateway BYOK keys + spend rule.
@@ -53,9 +56,9 @@ enable paid Workers products. Plus OneLogin: redirect URIs for the new host
 ## Non-goals
 
 - **No project-data migration.** Per-project D1s, R2 blobs, and deploy history
-  stay in the old account. The new control-plane D1 is empty; the three core
-  projects are re-created from scratch (they hold no precious data — `www` and
-  `dashboard` are stateless, `kitchen-sink` is a demo), and everyone else's
+  stay in the old account. The new control-plane D1 is empty; the core
+  projects are re-created from scratch (they hold no precious data — `www`,
+  `dashboard`, and `docs` are stateless, `kitchen-sink` is a demo), and everyone else's
   projects are re-created as needed. (If that ever changes, the export/import
   primitives already exist in `apps/api/src/cf.ts` and `canopy db snapshot|restore`.)
 - **No Tofu management of Workers/secrets/per-project resources** — see the
@@ -95,10 +98,15 @@ export CLOUDFLARE_ACCOUNT_ID="<account_id>"   # required when you belong to >1 a
    (You can confirm via API once the bootstrap token exists — an empty zone is
    fine.)
 4. **R2** must work (creating a probe bucket is enough to confirm). **Workers
-   Paid** and **Workers for Platforms** are _not_ required for the current CF
-   platform path (no dispatch namespaces; `capabilities.workers` is false).
-   Enable them later when you actually need paid Worker limits or Phase-2
-   per-project Workers. **No Advanced Certificate Manager** — `*.canopy.website`
+   Paid + Workers for Platforms** are required for per-project workers
+   (Phase 2 item 1, D18): once the subscriptions are active, run
+   `infra/scripts/create-dispatch-namespace.sh` to create the
+   `canopy-projects` dispatch namespace (the `dispatch_namespaces` bindings in
+   `apps/api/wrangler.main.jsonc` and `apps/gateway/wrangler.main.jsonc` fail
+   to deploy without it), and make sure `CF_API_TOKEN` carries **Workers
+   Scripts Write** (re-mint with `create-api-tokens.sh` if it predates this).
+   A site without the binding still runs — workers/schedules/secrets simply
+   answer 501. **No Advanced Certificate Manager** — `*.canopy.website`
    is a single-level wildcard covered by free Universal SSL. (ACM would only
    be needed if nesting as `*.canopy.<some-other-domain>`.)
 
@@ -283,8 +291,8 @@ If you already configured these for `canopy.website` before the move, skip.
 
 ### 10. Log in, grant yourself admin, then deploy the core projects
 
-The three core projects are ordinary platform projects that dogfood the product.
-Two of their slugs (`dashboard`, `www`) are in `RESERVED_SLUGS`
+The four core projects are ordinary platform projects that dogfood the product.
+Three of their slugs (`dashboard`, `www`, `docs`) are in `RESERVED_SLUGS`
 (`apps/api/src/routes/projects.ts`), so **only an admin can create them** —
 hence the ordering here.
 
@@ -326,6 +334,10 @@ export CANOPY_PROJECT_PROTOCOL="https"
    canopy-dev --profile main create "Canopy" --slug www --no-scaffold
    canopy-dev --profile main deploy
 
+   cd ../docs
+   canopy-dev --profile main create "Canopy Docs" --slug docs --no-scaffold
+   canopy-dev --profile main deploy
+
    cd ../../examples/kitchen-sink
    canopy-dev --profile main create "Kitchen Sink" --slug kitchen-sink --no-scaffold
    # CF target: capabilities.workers = false — strip worker for this deploy
@@ -371,7 +383,7 @@ same as the old `thanarie.dev` setup). Client-password mode is the only
 anonymous path. Smoke through a real browser session:
 
 1. `https://dashboard.canopy.website` → OneLogin login works; the project list
-   shows all three under **Core projects**.
+   shows all four under **Core projects**.
 2. `https://www.canopy.website` → marketing site + `/changelog` render (after
    SSO).
 3. `https://kitchen-sink.canopy.website` → exercise `db`, `blob`, and `ai.chat`

package/dist/docs/migrations.md

@@ -0,0 +1,166 @@
+---
+title: Migrations & Drizzle
+description: Evolve your own tables with versioned SQL migrations — generated by Drizzle or written by hand — applied safely by canopy deploy.
+---
+
+The document API (`canopy.db.collection(…)`) needs no schema and no migrations —
+if it covers your project, skip this page. But developers who define their own
+tables through raw `canopy.db.sql()` eventually need to _change_ those tables,
+and that's what migrations are for: versioned `.sql` files in your repo,
+applied exactly once each, in order, by the platform.
+
+[Drizzle](https://orm.drizzle.team) is the recommended way to produce those
+files (a typed schema plus generated SQL), but the mechanism is ORM-agnostic —
+hand-written `.sql` files work identically.
+
+## How it works
+
+1. Your `canopy.json` names a migrations directory:
+
+   ```json
+   {
+     "slug": "my-app",
+     "dialect": "sqlite",
+     "migrations": "./migrations"
+   }
+   ```
+
+2. The directory holds ordered `.sql` files (`0000_init.sql`, `0001_add_email.sql`, …),
+   applied in filename order.
+
+3. The platform journals each applied file in the project database, so a file
+   applies **exactly once**, and takes an automatic **pre-migrate snapshot**
+   before applying anything — a bad migration is one
+   `canopy db restore` away.
+
+4. Three surfaces apply them:
+   - **`canopy deploy`** — the main path. Pending migrations apply after the new
+     bundle is staged and before it goes live, so schema and code ship
+     together and the new code never sees the old schema. A failure aborts the
+     deploy with the old version still live.
+   - **`canopy dev --local`** — the sandbox applies pending migrations on boot,
+     so local dev always matches the repo.
+   - **`canopy db migrate [--plan]`** — apply (or dry-run) without deploying.
+
+Remote-first `canopy dev` never applies migrations — it points at the
+production database, and schema changes belong to deploys. While a schema
+change is in flux, develop against `--local` (add `--pull` for a copy of real
+data).
+
+## The rules
+
+- **Never edit an applied migration.** The platform hashes each file and
+  refuses edited history — write a new migration instead. (This is how every
+  mainstream migration tool works.)
+- **Prefer additive changes** (new tables, new nullable columns), and do
+  removals in a _later_ release once nothing references the old shape. This
+  "expand/contract" habit makes every edge case boring.
+- **Don't touch `_canopy_*` tables.** They're the platform's (the document
+  store, the migration journal) — the platform rejects migrations that
+  reference them.
+- **There are no down-migrations.** Roll forward with a new migration, or
+  restore the automatic pre-migrate snapshot.
+
+## Setting up Drizzle
+
+Pin your dialect first — a Drizzle schema is written for one SQL flavor. Check
+what your project's site runs on (`await canopy.db.dialect()` or the
+[data guide](https://docs.canopy.website/guides/data)) and set `"dialect"` in `canopy.json`: `"sqlite"`
+on Cloudflare-backed sites, `"postgres"` on GCP-backed ones. That same field
+makes `canopy dev --local` run a matching local engine.
+
+Install the tools and describe your schema:
+
+```bash
+npm install drizzle-orm
+npm install -D drizzle-kit
+```
+
+```ts title="src/schema.ts"
+import { sqliteTable, text } from "drizzle-orm/sqlite-core";
+
+export const users = sqliteTable("users", {
+  id: text("id").primaryKey(),
+  email: text("email").notNull(),
+});
+```
+
+```ts title="drizzle.config.ts"
+import { defineConfig } from "drizzle-kit";
+
+export default defineConfig({
+  dialect: "sqlite", // match canopy.json "dialect" ("postgresql" for postgres)
+  schema: "./src/schema.ts",
+  out: "./migrations",
+});
+```
+
+(On a postgres site, import from `drizzle-orm/pg-core` and set
+`dialect: "postgresql"` — everything else is identical.)
+
+Generate a migration whenever the schema changes:
+
+```bash
+npx drizzle-kit generate
+```
+
+This is fully local — it diffs your schema files and writes `.sql` into
+`./migrations`. **No database connection is involved, ever.** Then
+`canopy deploy` (or `canopy db migrate`) applies it.
+
+## Querying with Drizzle
+
+Canopy never hands out connection strings — Drizzle talks to your data through
+the handles Canopy already provides.
+
+**In a project worker on a Cloudflare-backed site**, `env.DB` is a real D1
+handle:
+
+```ts title="worker/index.ts"
+import { drizzle } from "drizzle-orm/d1";
+import { users } from "../src/schema.ts";
+
+export default {
+  async fetch(request, env) {
+    const db = drizzle(env.DB);
+    const all = await db.select().from(users);
+    return Response.json(all);
+  },
+};
+```
+
+**In the browser (or anywhere the SDK runs)**, wrap `canopy.db.sql()` with
+Drizzle's proxy driver:
+
+```ts title="src/db.ts"
+import { drizzle } from "drizzle-orm/sqlite-proxy";
+import { canopy } from "./canopy.ts";
+
+export const db = drizzle(async (sql, params, method) => {
+  const rows = await canopy.db.sql<Record<string, unknown>>(sql, params);
+  const values = rows.map((row) => Object.values(row));
+  return { rows: method === "get" ? (values[0] ?? []) : values };
+});
+```
+
+(On a postgres site use `drizzle-orm/pg-proxy` the same way; in a GCP project
+worker, `env.DB.query(text, params)` fits `pg-proxy` directly.)
+
+## What deliberately doesn't work
+
+- **`drizzle-kit push` / `migrate` / `studio` / `introspect`** — these need a
+  database connection, which Canopy never exposes. Generating is local;
+  applying is Canopy's job. Don't invent a `DATABASE_URL` — there isn't one.
+  For browsing data, use the dashboard's data browser or `canopy db pull`.
+- **Drizzle's runtime `migrate()`** — the platform journals migrations in its
+  own `_canopy_migrations` table; running Drizzle's applier would double-apply.
+- **Cross-dialect portability.** A project with a Drizzle schema is pinned to
+  its dialect. The document API remains the portable path.
+
+## Coexistence
+
+Your Drizzle tables live alongside the document store in the same project
+database. Snapshots, restore, `canopy db pull`, and the graduation export all
+operate on the whole database, so they cover your tables automatically — and
+since your schema history is in the repo and the journal travels with the
+data, a graduated project takes its full migration story with it.