docs(d1): add baseline migration pattern for existing databases#31812
docs(d1): add baseline migration pattern for existing databases#31812ivoryibu wants to merge 2 commits into
Conversation
ivoryibu
requested review from
a team,
Oxyjun,
elithrar,
irvinebroque,
joshthoward,
lambrospetrou,
rita3ko,
rts-rob and
vy-ton
as code owners
Review
Code ReviewThis code review is in beta and may not always be helpful — use your judgment. Warnings (2)
ConventionsChecks PR title, description, and redirect checklist. No convention issues found. Style Guide ReviewNo style-guide issues found. RedirectsNo missing redirect entries found. CommandsOnly codeowners can run commands. Post a comment with the command to trigger it.
|
github-actions
Bot
added
product:d1
github-actions
Bot
assigned
elithrar,
irvinebroque,
joshthoward,
lambrospetrou,
Oxyjun,
rita3ko,
rts-rob and
vy-ton
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
ask-bonk
Bot
added
documentation
![ask-bonk[bot]](https://avatars.githubusercontent.com/in/2454580?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue needs fixing and 2 suggestions posted.
MEDIUM — Multi-step procedures must use the <Steps> component instead of a bare numbered list.
HIGH — The sqlite_master query only captures tables, missing indexes, views, and triggers. A baseline created from this output will be incomplete for databases that use those features.
LOW — Step 3 mixes action and explanation in one long sentence.
(Note: the import for Steps must also be added on line 11, but that line was not changed in this PR so an inline suggestion could not be posted there.)
| 1. Get your current schema: | ||
|
|
||
| ```sh | ||
| npx wrangler d1 execute <DATABASE_NAME> --remote \ | ||
| --command="SELECT sql FROM sqlite_master WHERE type='table' AND name NOT LIKE '_cf%' AND name != 'sqlite_sequence'" | ||
| ``` | ||
|
|
||
| 2. Create a baseline migration: | ||
|
|
||
| ```sh | ||
| npx wrangler d1 migrations create <DATABASE_NAME> baseline | ||
| ``` | ||
|
|
||
| 3. Paste your existing `CREATE TABLE` statements into the file, adding `IF NOT EXISTS` so the migration is safe to run against the live database that already has these tables: | ||
|
|
||
| ```sql | ||
| -- migrations/0001_baseline.sql | ||
| CREATE TABLE IF NOT EXISTS users ( | ||
| user_id INTEGER PRIMARY KEY, | ||
| email TEXT NOT NULL, | ||
| name TEXT | ||
| ); | ||
| ``` | ||
|
|
||
| 4. Apply locally and remotely: | ||
|
|
||
| ```sh | ||
| npx wrangler d1 migrations apply <DATABASE_NAME> --local | ||
| npx wrangler d1 migrations apply <DATABASE_NAME> --remote | ||
| ``` |
There was a problem hiding this comment.
Wrap the procedure in <Steps> (import it from ~/components on line 11):
| 1. Get your current schema: | |
| ```sh | |
| npx wrangler d1 execute <DATABASE_NAME> --remote \ | |
| --command="SELECT sql FROM sqlite_master WHERE type='table' AND name NOT LIKE '_cf%' AND name != 'sqlite_sequence'" | |
| ``` | |
| 2. Create a baseline migration: | |
| ```sh | |
| npx wrangler d1 migrations create <DATABASE_NAME> baseline | |
| ``` | |
| 3. Paste your existing `CREATE TABLE` statements into the file, adding `IF NOT EXISTS` so the migration is safe to run against the live database that already has these tables: | |
| ```sql | |
| -- migrations/0001_baseline.sql | |
| CREATE TABLE IF NOT EXISTS users ( | |
| user_id INTEGER PRIMARY KEY, | |
| email TEXT NOT NULL, | |
| name TEXT | |
| ); | |
| ``` | |
| 4. Apply locally and remotely: | |
| ```sh | |
| npx wrangler d1 migrations apply <DATABASE_NAME> --local | |
| npx wrangler d1 migrations apply <DATABASE_NAME> --remote | |
| ``` | |
| <Steps> | |
| 1. Get your current schema: | |
| ```sh | |
| npx wrangler d1 execute <DATABASE_NAME> --remote \ | |
| --command="SELECT sql FROM sqlite_master WHERE type='table' AND name NOT LIKE '_cf%' AND name != 'sqlite_sequence'" | |
| ``` | |
| 2. Create a baseline migration: | |
| ```sh | |
| npx wrangler d1 migrations create <DATABASE_NAME> baseline | |
| ``` | |
| 3. Paste your existing `CREATE TABLE` statements into the file. Add `IF NOT EXISTS` to each statement so the migration is safe to run against a live database: | |
| ```sql | |
| -- migrations/0001_baseline.sql | |
| CREATE TABLE IF NOT EXISTS users ( | |
| user_id INTEGER PRIMARY KEY, | |
| email TEXT NOT NULL, | |
| name TEXT | |
| ); | |
| ``` | |
| 4. Apply locally and remotely: | |
| ```sh | |
| npx wrangler d1 migrations apply <DATABASE_NAME> --local | |
| npx wrangler d1 migrations apply <DATABASE_NAME> --remote | |
| ``` | |
| </Steps> |
|
|
||
| ```sh | ||
| npx wrangler d1 execute <DATABASE_NAME> --remote \ | ||
| --command="SELECT sql FROM sqlite_master WHERE type='table' AND name NOT LIKE '_cf%' AND name != 'sqlite_sequence'" |
There was a problem hiding this comment.
This query captures only tables, so the baseline will miss indexes, views, and triggers. Consider expanding the query or adding a note that other schema objects must be captured separately.
|
Review complete for PR #31812. Labels applied: Summary of changes: Issues flagged:
Validation results:
Review posted: #31812 (review) |
|
Preview URL: https://ce3141f2.preview.developers.cloudflare.com Files with changes (up to 15)
|
…r query, clearer step 3 wording
9 participants
Summary
Adds a new section to the D1 migrations page documenting how to adopt the migration system on an existing database that already has tables.
Problem
The current migrations documentation assumes you are starting from scratch. Developers who have an existing D1 database with tables and want to start using
wrangler d1 migrationshave no guidance on how to create a baseline migration that captures the current schema without breaking anything.Changes
Adds an "Adopt migrations on an existing database" section to
src/content/docs/d1/reference/migrations.mdxthat covers:sqlite_masterCREATE TABLE IF NOT EXISTSso it is safe to apply against the live databaseContext
Discovered during hands-on testing of D1 schema management workflows. The
CREATE TABLE IF NOT EXISTSpattern ensures the migration records itself ind1_migrationswithout attempting to recreate tables that already exist.