Interactive migrations

[Electroid]

Durable Objects require some extra coordination on script upload. Before a Durable Object can be created, renamed, deleted, or transferred to another script, a migration must be defined. One of the reasons migrations exist is to avoid accidental data loss. For instance, let's say you upload a new version of your script and don't properly export a Durable Object class; you wouldn't want the data from that class be accidentally deleted.

While this migration mechanism is "safer," its current use in wrangler makes the experience terse. In #337, you can see that when you create a script for the first time, you get an obscure error unless you define migrations in the wrangler.toml. While, in theory, migrations don't happen that often, it's important to make this experience smoother.

If wrangler encounters a particular error(s) on upload, it knows that a migration needs to happen. Then, it should compare the list of previous class exports (from the API) with the list of current class exports (from esbuild's outputs) to determine what to do.

If it detects a class has been added, it should ask:

• is this a new class?
• is this an existing class that has been renamed?
  • if so, ask for which class is being renamed.

If it detects a class has been removed, it should ask:

• are you sure you want to delete this class? and its data?

Then, it should make an "ad-hoc" migration, meaning that it does not need to update the wrangler.toml. If a user always uses wrangler in an interactive mode, they'll never need to save their migrations in a configuration.

If wrangler is running in non-interactive mode, it should error and print out the migration configuration that needs to be added; assuming that added classes are always new and deleted classes are intended to be deleted.

The new "happy path" is that wrangler detects and guides you through the migration process and you only need to edit your configuration when using wrangler in an interactive environment, like in CI/CD.

[koeninger]

IMO initial creation is the 90% use case. Stop deprecating ad-hoc migration, make the message super clear that you just need to run --new-class.

[threepointone]

It wasn't our decision to deprecate it. Is this messaging not true anymore?

[koeninger]

What I am saying, and what I have said in conversations with you in the past, is that in my opinion deprecating ad-hoc migrations is a mistake. We haven't removed it, we have no concrete plans to remove it. If it makes sense to Ashcon, I think we should just remove any documentation around deprecation and make the workflow for using adhoc migrations once on initial DO creation clearer. @xortive

[xortive]

Working towards an interactive experience for migrating DOs is what I'd like to see -- interactivity means this is one less thing that needs to be read in the docs to get the initial user experience right. I agree with @koeninger that we should undo the deprecation of the adhoc commands in the meantime, as that's much simpler to implement.

Improving error messaging in the API/wrangler2 is another improvement we should make, and I'm happy to help with.