Feedback on migrate command names

[jasonkuhrt]

Problem

1. It is confusing to switch between prisma db ... and prisma migrate ...

2. The command name prisma migrate dev is confusing because the convention of dev (I feel) is to enter some kind of watch mode.

Suggested solution

So there are three commands:

prisma migrate dev
prisma migrate deploy
prisma db push

Locally, we use db push mostly, reserving migrate dev for right before committing (for details on our workflow refer to #5714). The migrate deploy step is like some kind of production-safe version of db push to us (IIUC one difference is that deploy is based on the migrations and push is based on the prisma schema).

The following is an attempt at naming that matching how I think/use these commands. This might not align with how others see it/use it, of course!

prisma migrate preview   <-- prisma db push
prisma migrate commit    <-- prisma migrate dev
prisma migrate deploy

Firstly, I think one command namespace is easier to understand than two. But maybe there are future plans for these namespaces that would make me reconsider?

1. prisma migrate preview

   We see this as the first step in the workflow. It doesn't save a migration file and it is based on the state of the the Prisma schema file, not the migrations. Thus its a kind of "preview". As a user I think to myself

   I want to check out/try out the current state of my PSL+app right now. I don't know if this will work or is what I want, let's find out.

2. prisma migrate commit (alt ideas: prisma migrate create, prisma migrate save)

   This follows from a preview. It is the point where I'm ready to commit to the changes in my PSL. The word "commit" here is intentionally trying to align with git terminology. The analogy is that migrations are like git commits––a sequential diff timeline and an artifact saved to disk.

   However, "commit" might be confusing to users with an ops point of view, thinking that "commit" means some kind of deployment. Thus perhaps prisma migrate create or prisma migrate save are better words here.

3. prisma migrate deploy (alt ideas: prisma migrate up, prisma migrate apply)

   Finally deployment comes. This name seems reasonable to me. I think a case could be made for up and apply too though. For example Terraform uses the apply term.

[albertoperdomo]

Thanks for the comprehensive and detailed feedback @jasonkuhrt.
I wanted to shed some light on our thinking before closing this.

On problem 1

It is worth noting that there is a db namespace with other commands. Right now these are:

• prisma db push
• prisma db pull
• prisma db seed

All of these commands can be used independently from Prisma Migrate, e.g. when using the introspection workflow or when doing prototyping and migrations are not needed.

Hence, we don't think it makes sense to move db push under the migrate namespace.
We could, however, add an alias for db push under migrate, .e.g prisma migrate push or prisma migrate preview.

One thing to take into account is that this command would skip using any migrations, and the fact that the command would live under migrate could cause confusion.

On problem 2

The command name prisma migrate dev is confusing because the convention of dev (I feel) is to enter some kind of watch mode.

RIt's true that dev is often used for commands that are watching files and there has been some feedback that it is not very intuitive for some.

We considered a number of alternative names, but ultimately decided to go with dev, because we also found that it is helpful to signal that this command is meant to be used only in development and never in production, CI, etc.

We recently brainstormed names again, but there is a challenge since this command is also different from migrate deploy in that leverages the shadow database to handle drift, migration history conflicts, etc.

On your suggested solution

We currently have two different commands that will apply pending migrations:

• prisma migrate deploy - just applies pending migrations, errors out on conflict, ignores certain edge cases
• prisma migrade dev - leverages shadow database, handles drift (e.g. when using push) and migration history conflicts (missing applied migrations, modified migrations, etc.) via reset

The way the tool is designed right now, it does not make sense to conflate the two. Hence, we can't simplify it to have just one command, e.g. migrate apply

On customizing your workflow

We believe we should enable developers to build their own workflows and for that, we could make it possible to use migrate dev or equivalent functionality in a way that just creates migrations without applying them, or just applies migrations without picking up changes in your schema.

This would enable you to have your three aliases and a workflow that suits your particular style. However, we prefer to wait to get more signal from developers and find out what is the way to surface these, e.g. via flags, or dedicated commands, etc.

We don't have a lot to work with right now and we are worried about introducing something prematurely with a poor design. Since these changes are basically additive, there is nothing preventing us from making these improvements after GA.

I hope you find my response useful and I am interested in hearing your follow-up feedback if you have any.