You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .changeset/deployment-migration-manifest.md
+5-1Lines changed: 5 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,4 +2,8 @@
2
2
"emdash": minor
3
3
---
4
4
5
-
Adds a validated, secret-free deployment migration manifest during Astro build and sync so deployment tooling can run the exact migrations bundled with the site.
5
+
Adds deployment-managed core migrations so production databases can be updated before a new version of the site starts serving traffic.
6
+
7
+
To adopt the workflow, build the site, inspect and apply its migrations with `emdash migrate`, deploy that same build, then run `emdash migrate --check` to verify the database. Existing sites continue applying migrations automatically by default; switch the runtime to `check` only after the deployment migration job is reliable.
8
+
9
+
Follow [Manage Core Database Migrations](https://docs.emdashcms.com/deployment/core-migrations/) for setup, credentials, target confirmation, CI configuration, and rollout guidance.
Copy file name to clipboardExpand all lines: docs/src/content/docs/deployment/core-migrations.mdx
+34-24Lines changed: 34 additions & 24 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,28 +13,30 @@ Runtime migration mode defaults to `auto`, so existing deployments keep applying
13
13
14
14
An Astro build or sync writes `.emdash/migrations.json`. This secret-free manifest records the exact EmDash version, ordered migration set, locale configuration, and adapter migration executor used by that build.
15
15
16
+
<Asidetype="note"title="Ignore the generated manifest">
17
+
Add `.emdash/migrations.json` to `.gitignore`. Deployment jobs generate and consume this file from the build workspace; it does not belong in source control. EmDash templates already include this rule.
18
+
</Aside>
19
+
16
20
Run these commands from the project whose dependencies produced the manifest. First build and inspect the target.
17
21
18
22
```bash
19
23
pnpm build
20
-
pnpm execemdash migrate --status --json
24
+
pnpm emdash migrate --status
21
25
```
22
26
23
-
After reviewing the reported target and recording its fingerprint, apply the migrations, deploy, and check the deployed schema.
27
+
After confirming that the reported target is the intended database, start the interactive migration. Review the target again at the prompt before confirming. Then deploy the same build and check the deployed schema.
`emdash migrate` prints the immutable target before issuing SQL. An interactive, human-readable apply asks for confirmation. Non-interactive apply and every `--json` apply require `--expected-target-fingerprint`; the command fails if it does not match the resolved target.
35
+
`emdash migrate --status` reports applied, pending, and unknown migrations without changing the database. The plain `emdash migrate` command displays the target and asks for confirmation before applying pending migrations.
32
36
33
-
`--check` never applies migrations and exits non-zero when known migrations are pending or the database contains migration records unknown to the build. The [CLI reference](/reference/cli/#emdash-migrate) distinguishes pending, unknown, confirmation, interruption, and operational exit codes. The following command inspects all sets without using check's non-zero "work required" exit status.
37
+
`--check` never applies migrations and exits non-zero when known migrations are pending or the database contains migration records unknown to the build. Use `--status` when you want to inspect the same migration sets without check's non-zero "work required" exit status. The [CLI reference](/reference/cli/#emdash-migrate) distinguishes pending, unknown, confirmation, interruption, and operational exit codes.
34
38
35
-
```bash
36
-
pnpm exec emdash migrate --status --json
37
-
```
39
+
Non-interactive apply and every `--json` apply require `--expected-target-fingerprint`; the command fails if the resolved target does not match. Use these options in automated deployment jobs, not for the interactive workflow above.
38
40
39
41
Use `--manifest path/to/migrations.json` for a manifest stored elsewhere. For local investigation, `--from-config [--config astro.config.mjs]` explicitly evaluates trusted project configuration without running Astro hooks or starting a server. Deployment pipelines should consume the build manifest.
40
42
@@ -68,35 +70,43 @@ Creating a D1 database and migrating its schema are separate operations. `emdash
68
70
1. Provision the database and record its production UUID.
69
71
70
72
```bash
71
-
pnpm execwrangler d1 create my-site-production
73
+
pnpm wrangler d1 create my-site-production
72
74
```
73
75
74
76
2. Add that UUID to the intended binding and environment in `wrangler.jsonc`.
75
77
76
78
3. Build the site so the D1 binding is recorded in `.emdash/migrations.json`.
77
79
78
-
4. Set the account ID and a scoped API token with D1 Edit permission. Inspect the selected target, record its fingerprint, and then migrate it.
80
+
4. Set the account ID and a scoped API token with D1 Edit permission. Inspect the selected target, then run the interactive migration. Confirm the prompt only when the account and database match the intended production database.
You can instead provide `--account-id` with `--d1 <database-uuid-or-name>`. Name lookup must resolve to exactly one database. Preview IDs, placeholder IDs, conflicting accounts, and ambiguous bindings fail closed.
96
97
97
-
## Serialize D1 migration jobs
98
+
## Configure D1 migrations in CI
99
+
100
+
D1 does not provide the advisory migration lock used by PostgreSQL. Run at most one migration job for an account and database UUID.
101
+
102
+
Set the following secret and variables in the CI environment:
103
+
104
+
- Secret `CLOUDFLARE_API_TOKEN`: a scoped token with D1 Edit permission.
105
+
- Variable `CLOUDFLARE_ACCOUNT_ID`: the Cloudflare account ID that owns the database.
106
+
- Variable `D1_DATABASE_ID`: the production D1 database UUID.
107
+
- Variable `EMDASH_TARGET_FINGERPRINT`: the fingerprint printed by `emdash migrate --status` after you have reviewed the account and database locally.
98
108
99
-
D1 does not provide the advisory migration lock used by PostgreSQL. Run at most one migration job for an account and database UUID. The following GitHub Actions workflow keys the concurrency group by both immutable identifiers.
109
+
The following GitHub Actions workflow uses those values and keys the concurrency group by both immutable D1 identifiers. Its apply step is non-interactive, so it supplies the reviewed target fingerprint explicitly.
Store the target fingerprint only after reviewing the target printed by `--status`. The fingerprint contains no credential, but it is an important deployment guard against migrating the wrong database.
159
+
Update `EMDASH_TARGET_FINGERPRINT` only after reviewing a changed target locally. The fingerprint contains no credential, but changing it without checking the account and database removes the guard against migrating the wrong database.
0 commit comments