# FusionAuth Database Migrations Learn how FusionAuth migrates your database schema during an update, and how to run the migrations yourself. > For the index of this section of the site, see [llms.txt](https://fusionauth.io/docs/llms.txt) 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](https://fusionauth.io/docs/release-notes.md) say which versions include a database migration. Caution Always back up your database before you update, so you can [roll back](https://fusionauth.io/docs/update/rollback.md) in an emergency. ## 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](https://fusionauth.io/docs/reference/configuration.md) reference, and the [Silent Mode guide](https://fusionauth.io/docs/get-started/download-and-install/reference/silent-mode.md). | Runtime Mode | Silent Mode | Migration Behavior | | --- | --- | --- | | `development` | `true` | Migration applied automatically | | `development` | `false` | Maintenance Mode UI displayed, user prompted to run migrations | | `production` | `true` | Migration applied automatically | | `production` | `false` | Migration never applied by FusionAuth, must be applied out of band | Caution All FusionAuth nodes in a multi-node cluster must use the **same** runtime mode. Changing the runtime mode of an existing deployment requires stopping all running nodes before starting new nodes with a different runtime mode. Plan for brief downtime during this process. ### Development In the development runtime mode, FusionAuth enters an interactive [Maintenance Mode](#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](#run-migrations-out-of-band). To use the production runtime mode, configure all database and (optional) search engine properties in the [Configuration Reference](https://fusionauth.io/docs/reference/configuration.md). 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](https://fusionauth.io/docs/update/prod-instance.md#choose-an-update-strategy), 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](https://fusionauth.io/direct-download.md) page. Caution Only run the scripts in the `migrations` folder. The base files `mysql.sql` and `postgresql.sql` are only for a clean installation when no database schema is present. 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 Note Maintenance Mode is only available in the development runtime mode. Never use Maintenance Mode in production. 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. Related [Update Update a Development Instance of FusionAuth Learn how to update an instance of FusionAuth that isn't used for production purposes. upgrade fusionauthupdate fusionauthversion update](https://fusionauth.io/docs/update/dev-instance.md) [Update Update to a Newer Version of FusionAuth Learn how to update FusionAuth instances, FusionAuth Cloud deployments, and client libraries to a newer version. upgrade fusionauthupdate fusionauthversion update](https://fusionauth.io/docs/update.md) [Update Update a Production Instance of FusionAuth Learn how to plan, perform, and verify an update of a FusionAuth instance in a production environment. upgrade fusionauthupdate fusionauthversion update](https://fusionauth.io/docs/update/prod-instance.md) [Update Roll Back a FusionAuth Update Learn how to roll back FusionAuth to a previous version. upgrade fusionauthupdate fusionauthversion update](https://fusionauth.io/docs/update/rollback.md) --- ## Other pages in Update > For the full index of this section, see [Update](https://fusionauth.io/docs/llms-update.txt). - [Deprecation Policy](https://fusionauth.io/docs/update/deprecation-policy.md): Learn more about the FusionAuth deprecation policy. - [Update a Development Instance of FusionAuth](https://fusionauth.io/docs/update/dev-instance.md): Learn how to update an instance of FusionAuth that isn't used for production purposes. - [Early Access Program](https://fusionauth.io/docs/update/early-access-program.md): Learn about how to get your hands on new versions of FusionAuth before the official release. - [Update a Production Instance of FusionAuth](https://fusionauth.io/docs/update/prod-instance.md): Learn how to plan, perform, and verify an update of a FusionAuth instance in a production environment. - [Roadmap](https://fusionauth.io/docs/update/roadmap.md): Learn more about the FusionAuth roadmap and planning process. - [Roll Back a FusionAuth Update](https://fusionauth.io/docs/update/rollback.md): Learn how to roll back FusionAuth to a previous version.