docs(d1): add ORM migration workflow and Drizzle integration warnings

[ivoryibu]

Summary

Documents the workflow for using ORMs (specifically Drizzle) with D1 migrations, and adds warnings about known gotchas that can cause data loss.

Problem

The D1 docs list Drizzle as a community project and mention its nested migration layout, but do not document:

1. That drizzle-kit migrate does not work with D1 (you must use Wrangler to apply)
2. That drizzle-kit generate will generate DROP TABLE statements for tables not in your schema file — including Wrangler's own d1_migrations tracking table — which can cause data loss if applied blindly
3. The tablesFilter config option that prevents this
4. That Drizzle and Wrangler track migrations separately and don't communicate
5. When to use an ORM vs. raw SQL migrations

Changes

src/content/docs/d1/reference/migrations.mdx

• Adds "Using an ORM for migrations" section explaining the generate-then-apply workflow
• Adds "When to use an ORM vs. raw SQL" guidance

src/content/docs/d1/reference/community-projects.mdx

• Adds a caution callout under the Drizzle ORM entry with the three specific gotchas and their fixes

Context

Discovered during hands-on testing of D1 schema management. When using drizzle-kit generate against a D1 database, the generated migration attempted to drop the d1_migrations table and recreate the application table from scratch (instead of using ALTER TABLE ADD COLUMN). Both behaviors are dangerous if not caught during review.

[cloudflare-docs-bot]

Review

⚠️ 2 warnings, 💡 2 suggestions found in commit 3176f74.

Code Review

This code review is in beta and may not always be helpful — use your judgment.

Warnings (1)

File

Issue

d1/reference/migrations.mdx line 97

Inaccurate Drizzle behavior example — Theadded paragraph says Drizzle's migration generation command (drizzle-kit generate) treats every table not defined in the schema as needing a DROP TABLE statement. drizzle-kit generate generates migrations by comparing schema snapshots over time, so it only drops tables that were previously declared and later removed; unmanaged pre-existing tables are not included as drops. The described behavior matches drizzle-kit push (which syncs schema to DB state), not generate (which produces .sql files). Fix: Either change the example command to drizzle-kit push (and note it applies changes directly) or reword so the destructive-statement warning is accurate for drizzle-kit generate, e.g. mention that drops occur when tables are removed from the schema, not for every unmanaged table.

Conventions

Checks PR title, description, and redirect checklist.

_{No convention issues found.}

Style Guide Review

Warnings (1)

File	Issue
d1/reference/migrations.mdx line 89	Headings should use imperative form, not -ing verbs — Added body heading starts with Using (## Using an ORM for migrations) Fix: Change to ## Use an ORM for migrations

Suggestions (2)

File	Issue
d1/reference/migrations.mdx line 104	Oxford comma — List of four clauses ends with ...writing SQL, or you are the only developer... without a comma before or Fix: Add a comma before the final or: ...writing SQL, or you are the only developer... → ...writing SQL, or you are the only developer...
d1/reference/migrations.mdx line 106	Oxford comma — List of clauses ends with ...source of truth, or you want editor autocompletion... without a comma before or Fix: Add a comma before the final or for clarity: ...source of truth, or you want editor autocompletion... → ...source of truth, or you want editor autocompletion...

Redirects

_{No missing redirect entries found.}

Commands

Only codeowners can run commands. Post a comment with the command to trigger it.

Command	Description
/review	Runs a review now. Incremental if a prior review exists, full if not.
/full-review	Re-reviews the entire PR diff from scratch, ignoring incremental history. Useful after a rebase, when you want a fresh review, or if the bot gets out of sync and reports issues that no longer exist.
/ignore-review-limit	Permanently lifts the 2-review automatic limit for this PR. Future pushes will trigger reviews as normal.
/disable-auto-review	Stops automatic reviews from triggering on future pushes to this PR. Codeowners can still run /review or /full-review manually.

[github-actions]

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
/src/content/docs/d1/	@elithrar, @rita3ko, @irvinebroque, @vy-ton, @ivoryibu, @rts-rob, @joshthoward, @lambrospetrou, @oxyjun, @cloudflare/product-owners

[ask-bonk]

Review of PR #31813

Summary

This PR adds practical, technically accurate documentation for using ORMs (specifically Drizzle) with D1 migrations. It correctly warns readers about two serious gotchas — that Drizzle cannot apply migrations directly to D1, and that drizzle-kit generate can emit destructive DROP TABLE statements for tables it does not manage — which can prevent real data-loss incidents. The content is well-placed: a high-level workflow in the migrations reference, and targeted warnings in the community projects page.

Suggested labels
documentation, d1

Issues requiring maintainer attention

1. Style guide violation: gerund phrase in heading (migrations.mdx, line 89)
## Using an ORM for migrations uses a gerund. The style guide requires headings to be verb or noun phrases: "Install Wrangler" not "Installing Wrangler".
Suggestion: change to ## Migrate with an ORM or ## Generate migrations with an ORM.

2. Style guide suggestion: heading phrasing (migrations.mdx, line 102)
### When to use an ORM vs. raw SQL is borderline; the style guide says subheadings must be verb or noun phrases and not questions.
Suggestion: change to ### ORM vs. raw SQL or ### Choose between an ORM and raw SQL.

3. Style guide issue: config key not monospace (community-projects.mdx, line 70)
tablesFilter is a configuration key and should be wrapped in backticks.

To prevent this, add `tablesFilter`: `["!d1_migrations", "!_cf_KV", "!sqlite_sequence"]` to your `drizzle.config.ts`.

4. Style guide issue: run-on sentence (migrations.mdx, line 106)

An ORM starts to pay off when your schema grows to many tables with foreign key relationships, you build complex queries with joins across multiple tables and want compile-time type safety, multiple developers touch the schema and need a single TypeScript definition as the source of truth, or you want editor autocompletion when writing queries.

This exceeds the recommended sentence length significantly. Break it into shorter sentences or a short list so each idea stands alone.

5. Accuracy note: hardcoded d1_migrations name (community-projects.mdx, line 70)
The tablesFilter example uses d1_migrations, but Wrangler allows customizing this name via migrations_table. Users who changed that setting will still be exposed to the bug if they copy-paste this snippet blindly.
Suggestion: add a brief note such as "Use the same name you configured for migrations_table in Wrangler."

Minor notes

• The caution callout bullets are dense, but given the safety-critical nature of the warnings, the length is justifiable.
• The _cf_KV table is an internal implementation detail. It is useful to warn about it today, but maintainers should be aware that internal table names may change in future D1 releases and this guidance may need updating.

Overall assessment

Approve with minor revisions. The factual content is strong, the warnings address a genuine user pain point, and the structure makes sense. Fixing the heading gerund, adding backticks around tablesFilter, and breaking up the run-on sentence would make this ready to merge.

github run

[github-actions]

Preview URL: https://30fe957e.preview.developers.cloudflare.com
Preview Branch URL: https://docs-d1-drizzle-workflow.preview.developers.cloudflare.com

Files with changes (up to 15)

Original Link	Updated Link
https://developers.cloudflare.com/d1/reference/migrations/	https://docs-d1-drizzle-workflow.preview.developers.cloudflare.com/d1/reference/migrations/
https://developers.cloudflare.com/d1/reference/community-projects/	https://docs-d1-drizzle-workflow.preview.developers.cloudflare.com/d1/reference/community-projects/