Skip to main content

Database alteration

When developing new features, or refactoring existing ones, sometimes it is unavoidable to change database schemas.

Things may sound scary, as a user, usually you need to:

  • Double check the difference between two or more versions
  • Alter database in a safe and backward-compatible way
  • Get prepared for potential failure, say have a rollback script
  • Gradually replace running Logto instances to the new version

Hey, we are also developers, and we know it feels unhappy to do all these risky but mandatory stuff. So why don't we give them to someone that won't make mistake, like a CLI?

From now on, your upgrade process will be:

  • Run logto db alt deploy from anywhere that can access to the database
  • Gradually replace running Logto instances to the new version

Let's get started!

Determine the version to deploy​

If you have Logto CLI installed globally, it is highly recommended to upgrade the CLI to the latest version before deploying to get full available database alterations. Then run the command:

logto db alteration deploy

If your database is up-to-date, you'll see the message below:

[info] Found 0 alteration to deploy

If you have undeployed alterations, the CLI will ask you to choose the desired version:

? Choose the alteration target version (Use arrow keys)
> 1.2.0
  1.0.0

Theoretically, the version to deploy should match the version of your Logto instance. In the meantime, you can use the command with a target version:

logto db alteration deploy 1.2.0

It is helpful when you'd like to do the alteration in a non-TTY pipeline, just remember to pass the database URL using --db-url. See Deployment and configuration for setting up a alteration job in your cluster.

note

For each alteration script, the Logto CLI will run the whole script in a transaction. So if a deployment is failed, you can easily continue with the same command after the issue fixed.

Rollback alterations​

Our alteration scripts also come with a down script which can rollback the changes. To rollback the database status to a specific version, replace 1.0.0 with your target version and run the command below:

logto db alteration rollback 1.0.0
note

You can find all alteration scripts in this directory.

For contributors​

The master branch of Logto repository may contain unpublished alteration scripts. You may need to manually deploy "next" alterations by running:

logto db alteration deploy next

If you are developing a feature that requires database alterations, rather than updating the database schema, you also need to provide a script in the following format:

next-[timestamp]-what-to-do.ts

Check this directory for reference.