FusionAuth Database Migrations

Some FusionAuth releases change the database schema. When you update to one of these versions, the database must be migrated to the new schema before FusionAuth can use it. The release notes say which versions include a database migration.

When FusionAuth Applies Migrations#

Two settings decide what happens when FusionAuth starts against a database that needs a migration: the runtime mode and silent mode. See the fusionauth.runtime-mode property and the FUSIONAUTH_RUNTIME_MODE environment variable in the Configuration reference, and the Silent Mode guide.

Development#

In the development runtime mode, FusionAuth enters an interactive Maintenance Mode when you install or update it. Maintenance Mode helps you configure the database and search engine, and applies database migrations.

Production#

Always use the production runtime mode in a production environment. In this mode, Maintenance Mode never runs, so end users never land on a database setup page instead of the login page. Maintenance Mode also can't coordinate migrations across the nodes of a cluster, which can corrupt the database schema.

In the production runtime mode, enable silent mode to apply migrations automatically, or run the migrations out of band.

To use the production runtime mode, configure all database and (optional) search engine properties in the Configuration Reference. The database and search engine must be running and ready to accept connections when FusionAuth starts.

Downtime and Locking#

A database migration can cause downtime that affects end users, depending on the amount of data in your system, the speed of your database, and the schema changes in the release. An update without a schema change may not require any downtime from an end-user perspective.

When silent mode applies a migration, the first updated node to connect immediately locks the database until the migration completes. While the database is locked, it is unavailable to the other nodes in the cluster.

During a rolling update or blue-green deployment, nodes still running the previous version keep serving requests against the migrated schema. They may produce errors once the migration begins. The nature of these errors depends on the code paths that changed and how users interact with the system. Errors should be minimal for core login functionality.

Testing the update in a non-production environment with production-like data is the surest way to learn how long a migration takes.

Run Migrations Out of Band#

In production, you may want to run the database migration yourself instead of letting FusionAuth do it, for example to control timing or to fit the migration into a larger automated release. This is called an out-of-band migration.

The migrations are SQL scripts in the migrations folder of the Database Schema ZIP, which you can download from the Direct Downloads page.

Run the scripts in order, starting with the first migration newer than your current FusionAuth version and ending with the newest migration that is less than or equal to the version you're updating to. For example, to update from version 1.19.1 to 1.22.0, run:

1. 1.20.0.sql
2. 1.21.0.sql
3. 1.22.0.sql

To run the migration:

1. Remove all FusionAuth nodes from your load balancer or proxy.
2. Stop all FusionAuth nodes.
3. Back up your database.
4. Run the migration scripts.
5. Update and start each node with the new version of FusionAuth.
6. Add the nodes back to your load balancer or proxy.

Maintenance Mode#

Maintenance Mode is an interactive setup page that configures the database and search engine and applies database migrations. To open it, visit FusionAuth in your browser. For a local installation, open http://localhost:9011. For a remote server, replace localhost with your server's name.