Improve deployed schema evolution workflow for Cloudflare D1 sites

[khoinguyenpham04]

This Roadmap discussion mirrors #442: Improve deployed schema evolution workflow for Cloudflare D1 sites.

Use this discussion to upvote the roadmap item and discuss priority, use cases, and product feedback. Keep implementation tracking, reproduction details, and PR-specific feedback on the source issue.

• Source issue: #442
• Status: Open
• Labels: enhancement, area/cloudflare, area/docs, roadmap/1.0, roadmap/data-safety
• Original author: oliviercp

Original Issue

Summary

While adapting an EmDash Cloudflare template site away from the starter blog model, the rough edge was not deployment itself, but evolving an already-initialized remote D1 database cleanly.

Fresh setup works. Code deploys work. Content editing works.

What feels underpowered right now is the workflow for changing a deployed site's schema/content model after the first setup.

What happened

I changed an EmDash Cloudflare site from the starter blog structure to a different architecture:

• posts used as notes
• categories reused as domains
• tags reused as labels
• added builds
• added explorations
• removed the public starter taxonomy/archive assumptions at the site layer

The surprising parts were:

1. Deploying new code did not update the already-initialized remote D1 schema/content model.
2. A fresh D1 database triggered setup as expected, but that is a reset path, not an evolution path.
3. The CLI commands (emdash schema, emdash seed, emdash doctor) appear primarily oriented around a local database path, not a deployed Cloudflare D1 target.
4. The seed embedding behavior was easy to miss. If package.json -> emdash.seed is not set (or .emdash/seed.json is not present), the build embeds the default seed, which can make a fresh deployed DB initialize with the wrong model.

Why this matters

For real projects, there are at least four distinct workflows:

1. content edits in admin
2. code-only deploys
3. first-time bootstrap of a fresh database
4. schema/content-model evolution on an already-initialized deployed database

The first three are understandable.

The fourth is where the current workflow feels unclear.

Request

It would help a lot if EmDash had a more explicit story for deployed schema evolution, especially for Cloudflare D1 sites. For example, any combination of:

• clearer docs distinguishing fresh bootstrap vs schema evolution
• a documented remote migration/bootstrap workflow for Cloudflare D1
• a CLI path that can target deployed/admin-backed schema changes, not just local DB files
• a safer or more explicit warning when the build is embedding the default seed instead of a user seed
• recommended patterns for updating an existing deployed content model without resorting to creating a new database

Concrete ask

Could EmDash expose or document a supported way to evolve a deployed Cloudflare D1-backed site's schema/content model over time, rather than treating fresh database setup as the main escape hatch?

That would make EmDash feel much more production-ready for nontrivial sites.

[mhsnook]

Hi I would like to request the option to use code-driven schemas which are not editable by my clients in the CMS (only in local dev). I don't personally want my collection schemas being editable in production in the first place, because you could add a new field to a collection in production, but nothing will use it until I deploy new code. For the sites I'm building, if my users do change the schema in production, the only possible change will be to break something (which is why I only give them access level: Editor, which disables other forms of access I wish they could have).

That said, I do understand why others would want to use the "cms-driven" approach, so my request is to support a second mode "code-driven" collection schemas, which I would use in most cases, like this:

pnpm dev                                        # shape the collection in the admin
pnpm schema:dump --url http://127.0.0.1:4321    # + changes
git commit                                      # the shape is now in source
pnpm schema:push --url https://production.url --dry-run    # make sure it matches 
pnpm schema:push --url https://production.url              # apply changes

I am using these scripts to apply schema changes when I deploy:

• They are additive only, which makes them idempotent and resistant to ordering problems
• They use the HTTP API to make the changes because it supports validations and repeater fields
• If collection fields also had stable IDs, like menu items and other data types also have, it could also handle renames and deletes 😎

These specific scripts are a little janky to use in their nascent form, but for me, they make it feel like a /migrations folder is YAGNI -- if this works for 95% of cases, then in the other 5%, devs can already bail out to use SQL or to the admin. If you wanted to support imperative migrations for particularly messy data-movement (say you have to split and recombine fields), you could still bail out to SQL, and if you wanted to do apply-on-deploy, you could generate deterministic migrations from the same logic the dry-run currently uses so it feels safe to apply them on deploy. (Optionally, use a verification hash for the affected collections, to make sure the starting point is the same as that assumed by the migration's author.)

I think it would be quite dreamy actually, to have a workflow where simpler changes get applied via simple schema-diff, and more complex ones get an imperative migration -- You could run a site for years and make hundreds of changes to the schema, and probably still only have a few files in your migrations folder. That would be neat 🌴🏖️🌴