D1 Database Migrations

Using Actions

Run 00 Deploy Worker normally. New databases receive the full schema and a migration baseline. Existing databases receive applicable pending SQL selected from their structure and ledger. Verification runs before the Worker is published.

Prepare a Manual Deployment

1. Use Node.js 24 and run npm ci in the project root.
2. Point DB in wrangler.toml to the target database. Keep [build] command = "npm run schema:generate" from the template.
3. Set your own CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, and EDGECHAT_D1_DATABASE_ID in the terminal environment. Match the database ID to DB.
4. Export a backup before upgrading an existing database:

npx wrangler d1 export DB --remote --config wrangler.toml --output .tmp/d1-backup.sql

Backups may contain sensitive business data; store them offline. The planner calls Cloudflare directly using the environment credentials above.

Initialize a New Database

For a new, empty database only:

npx wrangler d1 execute DB --remote --config wrangler.toml --file worker/schema.sql

Continue below to record the baseline. Existing databases go directly to the migration flow.

Plan, Apply, and Verify

Run each command separately, continuing only after success:

node .github/scripts/prepare-d1-migrations.mjs
npx wrangler d1 execute DB --remote --config wrangler.toml --file .tmp/edgechat-d1-migrations.sql
node .github/scripts/prepare-d1-migrations.mjs --verify

The first reads structure and generates local SQL, the second applies it, and the third verifies it. Complete new schemas receive baseline records; existing databases receive pending migrations and applicable repairs.

After verification, initialize the administrator and deploy. Let the planner select historical migrations rather than replaying them individually. Rerunning the full schema does not add missing columns to existing tables.

Verification Failures

For missing migrations, inspect logs and rerun normal deployment. For checksum mismatches, unknown migrations, or schema drift, keep the backup and error report and verify the source version and database target. Changes to published SQL require a new migration.

The ledger is edgechat_schema_migrations. Verification checks for tables, columns, indexes, and triggers; the admin panel uses the same manifest.

Accidental Private-Groups Migration Replay

If running 2026-04-05-private-groups.sql after the full schema reports add_new_user_to_general: no such table: main.channels, stop further SQL and run this read-only query:

npx wrangler d1 execute DB --remote --config wrangler.toml --command "SELECT type,name FROM sqlite_master WHERE name IN ('channels','channels_new','add_new_user_to_general'); PRAGMA table_info(channels); PRAGMA table_info(channel_members);"

Send the results, error, and backup details to the maintainer. Review actual structure before planning recovery, keeping triggers and temporary tables available for inspection.

See the repository's D1 maintenance guide for background.