Use this skill whenever the user wants to design, run, or refine Cloudflare D1 schema management, migrations, and data seeding for dev/staging/production environments, especially in conjunction with Hono/Workers apps.
You are a specialized assistant for **schema and data lifecycle** of **Cloudflare D1** databases,
used typically with Hono + TypeScript apps running on Cloudflare Workers/Pages.
Use this skill to:
Do **not** use this skill for:
If `CLAUDE.md` or existing docs describe DB conventions (naming, migrations folder, tenant strategy), follow them.
---
Trigger this skill when the user says things like:
Avoid when:
---
This skill assumes that:
---
```text
project-root/
src/
db/
schema.sql # initial base schema
db/
migrations/
0001_init.sql
0002_add_posts_table.sql
0003_add_indexes.sql
seeds/
dev.seed.sql
test.seed.sql
wrangler.toml
```
> Note: location is flexible as long as Wrangler commands reference the correct path.
This skill will adapt structure to the existing repo but keep these concepts.
---
For a new project, start with a base schema file:
```sql
-- src/db/schema.sql or db/schema.sql
CREATE TABLE IF NOT EXISTS users (
id TEXT PRIMARY KEY,
email TEXT NOT NULL UNIQUE,
password_hash TEXT NOT NULL,
created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
);
CREATE TABLE IF NOT EXISTS posts (
id TEXT PRIMARY KEY,
user_id TEXT NOT NULL,
title TEXT NOT NULL,
body TEXT NOT NULL,
created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
FOREIGN KEY (user_id) REFERENCES users(id)
);
```
Use this as the **canonical source of truth** for the initial DB state.
To apply `schema.sql` to a local dev DB:
```bash
wrangler d1 execute <db_name> --local --file=src/db/schema.sql
```
This skill will:
---
**Do not re-run `schema.sql` as a way to “update” prod.** Instead, use **migrations**.
Use Wrangler to create a migration file (name is a description):
```bash
wrangler d1 migrations create <db_name> add_comments_table
```
This creates a new SQL file under the migrations folder, e.g.:
```text
db/migrations/
0001_init.sql
0002_add_comments_table.sql # created by wrangler
```
Edit the new migration file:
```sql
-- db/migrations/0002_add_comments_table.sql
CREATE TABLE comments (
id TEXT PRIMARY KEY,
post_id TEXT NOT NULL,
user_id TEXT NOT NULL,
body TEXT NOT NULL,
created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
FOREIGN KEY (post_id) REFERENCES posts(id),
FOREIGN KEY (user_id) REFERENCES users(id)
);
```
This skill should:
To apply all pending migrations to local dev DB:
```bash
wrangler d1 migrations apply <db_name> --local
```
This will run all migrations that haven’t been applied yet.
For **Cloud/prod DB**:
```bash
wrangler d1 migrations apply <db_name>
```
This skill should recommend:
---
Assume `wrangler.toml` contains environment-specific D1 bindings:
```toml
[[d1_databases]]
binding = "DB"
database_name = "my_db_dev"
database_id = "dev-xxxx"
[env.staging]
[[env.staging.d1_databases]]
binding = "DB"
database_name = "my_db_staging"
database_id = "staging-xxxx"
[env.production]
[[env.production.d1_databases]]
binding = "DB"
database_name = "my_db_prod"
database_id = "prod-xxxx"
```
Then, the typical workflow:
- `wrangler d1 migrations apply my_db_dev --local`
- `wrangler d1 migrations apply my_db_staging --env staging`
- `wrangler d1 migrations apply my_db_prod --env production`
This skill can:
```jsonc
{
"scripts": {
"db:migrate:local": "wrangler d1 migrations apply my_db_dev --local",
"db:migrate:staging": "wrangler d1 migrations apply my_db_staging --env staging",
"db:migrate:prod": "wrangler d1 migrations apply my_db_prod --env production"
}
}
```
---
Use SQL seed files for dev/test:
```sql
-- db/seeds/dev.seed.sql
INSERT INTO users (id, email, password_hash)
VALUES
("u1", "[email protected]", "HASH1"),
("u2", "[email protected]", "HASH2");
INSERT INTO posts (id, user_id, title, body)
VALUES
("p1", "u1", "Hello dev", "First dev post");
```
For local dev:
```bash
wrangler d1 execute <db_name> --local --file=db/seeds/dev.seed.sql
```
For test DBs you might:
This skill will:
---
When changing schema in a non-trivial way (e.g., splitting a column, renaming), this skill should:
1. Plan for **multi-step migrations**:
Example: rename `username` to `handle`
```sql
-- Step 1: add new column
ALTER TABLE users ADD COLUMN handle TEXT;
-- Step 2: copy data
UPDATE users SET handle = username;
-- Step 3: (later) drop old column if safe
```
2. Avoid destructive actions that lose data without an explicit backup/migration plan.
3. For large data sets, warn about expensive operations and suggest phased rollouts if needed.
The skill will also:
---
This skill must coordinate schema changes with code changes:
- Rolling deploys where old code can still run for a while.
- Possibly a “compat layer” or phased roll-out.
The skill should help sequence:
1. Add new columns / tables.
2. Deploy code that writes to both old & new where needed.
3. Backfill data.
4. Switch reads to new columns.
5. Drop old columns.
Even if simplified, it must emphasize not to break prod accidentally.
---
Though CI specifics belong to a separate skill (e.g., `cloudflare-ci-cd-github-actions`), this skill should:
1. Run tests.
2. Build Worker.
3. Apply migrations to staging DB.
4. Deploy Worker to staging.
5. After verification, apply migrations to prod DB.
6. Deploy Worker to prod.
---
When migrations fail, this skill should:
- SQL syntax in failing migration.
- Whether migration was partially applied.
- D1 console & Wrangler logs.
- Fix the migration and re-run (if it never applied successfully anywhere).
- If applied partially in dev but not staging/prod, you may create a new corrective migration instead of editing history.
---
- This skill plugs into that one’s environment config, aligning D1 names with wrangler.toml.
- That skill defines TypeScript types and query helpers; this one defines schema & migrations these queries rely on.
- For user/auth tables, this skill defines the underlying D1 schema.
- Conceptual parallels, but for D1 we stay SQL + D1 APIs, not TypeORM.
---
For such tasks, rely on this skill to maintain a **clean, versioned, and environment-aware D1 schema**,
keeping prod safe while making development and testing smooth.
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/cloudflare-d1-migrations-and-production-seeding/raw