dmacias2 min read

EmDash upgrade from 1.40 to 15.0.

This upgrade was a bit more involved as it required a D1 migration, which was my first time when dealing with an upgrade.

EmDash 1.5.0 shipped on November 11. It is not a security release, so there was no rush, but I upgraded the same week anyway. The short version: the package change was two lines, the database needed a short maintenance window, and the hands-on part was quick. The long version is below, including the exact commands for the DB migration.

The Upgrade

  1. Update your package.json and package-lock.json files.
  2. In astro.config.mjs inside emdash({...}) add:
migrations: { runtime: "check" },
  1. Deploy.
  1. Look at the next section and then come back to this list.
  2. Restore astro.config.mjs without the check line you added in step 2 to return to auto.
  3. Deploy.

The D1 Migration

The build succeeded and deployed, and the site immediately started answering 503 with "Database migrations are required." That looks like an outage if you are not expecting it. It is the design: in check mode the Worker refuses to serve while migrations are pending, instead of applying them itself on the first request.

This assumes you have your CLI configured to access your CF environment. If not, search on getting an API token to make this change. Finally, you need to have your D1 UUID.

From the root folder install dependencies: npm ci. Use npm ci, not npm install, so it uses the lockfile and skips the ERESOLVE issue.

Run the status check. It should show the six new migrations under Pending.

% npx emdash migrate --status --wrangler-config wrangler.jsonc --from-config --d1 <uuid>
Using trusted evaluated Astro configuration.
…
Known applied: 001_initial, 002_media_status, 003_schema_registry, 004_plugins, 005_menus, 006_taxonomy_defs, 007_widgets, 008_auth, 009_user_disabled, 011_sections, 012_search, …091_redirect_artifacts
Pending: 092_plugin_kv_options, 093_menu_item_orphans, 094_media_usage_file_url_reindex, 095_plugin_storage_unique_scope, 096_revision_kind_and_editors, 097_room_storage
Unknown applied: none
Executed: none

Perform the actual migration.

% npx emdash migrate --wrangler-config wrangler.jsonc --from-config --d1 <uuid>
Using trusted evaluated Astro configuration.
...
Apply EmDash migrations to <uuid>/dmaciasdotorg/<uuid>? [y/N] y
Known applied: 001_initial, 002_media_status, 003_schema_registry, 004_plugins, ...095_plugin_storage_unique_scope, 096_revision_kind_and_editors, 097_room_storage
Pending: none
Unknown applied: none
Executed: 092_plugin_kv_options, 093_menu_item_orphans, 094_media_usage_file_url_reindex, 095_plugin_storage_unique_scope, 096_revision_kind_and_editors, 097_room_storage

Check the migration and confirm nothing is Pending or Unknown.

% npx emdash migrate --check --wrangler-config wrangler.jsonc --from-config --d1 <uuid>

Using trusted evaluated Astro configuration.
...
Known applied: 001_initial, 002_media_status, 003_schema_registry, 004_plugins, ...
095_plugin_storage_unique_scope, 096_revision_kind_and_editors, 097_room_storage
Pending: none
Unknown applied: none
Executed: none

Go back to the deploy list above and you should be good to go. Check your deployment and visit your site and you should be up and running.

~david

No comments yet

Continue reading