Skip to content

Email for professionals and teams

docs: require migrations for every dialect on schema changes

Hieu Nguyen (Jack)b141d815a9a9
diff --git a/AGENTS.md b/AGENTS.md
index c71f945..b6244e7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,5 +1,18 @@
# Repository agent instructions
+## Database schema changes: update every dialect
+
+Mailflare runs on SQLite/D1, PostgreSQL and MySQL from one schema file. Any change to `src/db/schema/index.ts` (table, column, index, default) **must ship a migration for all three dialects in the same change**:
+
+1. `npm run db:generate` → `drizzle/migrations/` (SQLite/D1)
+2. `npm run db:generate:pg` → `drizzle/migrations-pg/` (PostgreSQL)
+3. `npm run db:generate:mysql` → `drizzle/migrations-mysql/` (MySQL/MariaDB)
+4. `npm run db:bundle` to refresh `src/lib/migrations/bundle*.json` (commit them).
+5. Touching `messages`, `folders`, `mailboxes` or `mailbox_aliases` behaviour that SQLite does with triggers (JMAP change log, `trashed_at`, search index): add the equivalent trigger SQL to a new hand-written PostgreSQL and MySQL migration too.
+6. Run `node --test tests/*.test.mjs` (`tests/database-dialects.test.mjs` fails if the dialects diverge or a bundle is stale) and, if a database is available, `npm run db:smoke -- <DATABASE_URL>`.
+
+Raw SQL must also work on all three dialects; see "The database is D1 unless `DATABASE_URL` says otherwise" in CLAUDE.md and `docs/databases.md`. Never edit an already-applied migration; add a new one.
+
## Database backup and restore
- Whenever a migration creates, renames, or removes a persisted table, update the backup and restore table lists in the same change, even if the feature is unrelated to backups. Review `BACKUP_TABLES` and `INTERNAL_TABLES` in `src/lib/backups/export.ts`, `BACKUP_TABLE_GROUPS` in `src/lib/backups/table-groups.ts`, and `DatabaseBackupTable` in `src/lib/backups/types.d.ts`.
diff --git a/CLAUDE.md b/CLAUDE.md
index e50dafa..86ed313 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,6 +2,8 @@
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+> **Schema or migration change? Update all three dialects (SQLite, PostgreSQL, MySQL).** See "Database schema changes" in AGENTS.md and "Schema and migrations" below.
+
## Commands
```bash
diff --git a/README.md b/README.md
index 5f360fc..fa5f32e 100644
--- a/README.md
+++ b/README.md
@@ -129,6 +129,7 @@ Add your Cloudflare credentials to `.dev.vars`, then open [http://localhost:3000
The Cloudflare app uses Vite+, vinext, and the Cloudflare Vite plugin, with local D1, R2, Queues, and Durable Objects. Remote bindings are off by default. To use Workers AI locally, log in with Wrangler, set `CLOUDFLARE_ACCOUNT_ID`, and run `CLOUDFLARE_REMOTE_BINDINGS=true npm run dev`.
+- Changing the database schema means a migration for each dialect: `npm run db:generate`, `db:generate:pg` and `db:generate:mysql`, then `npm run db:bundle`. See [Databases](docs/databases.md#migrations).
- `npm run build`: build the full Worker.
- `npm run start`: preview that build locally.
- `npm run deploy`: build and deploy.