☰
Navigation :

Schema Migrations

We have added Liquibase changesets to facilitate database migrations. This section describes how to migrate your database schema by configuring Liquibase and using the Liquibase Maven plugin.

We use the Maven plugin for ease of maintenance, but there are other Liquibase alternatives - such as the CLI, Spring or Docker - which you can also utilize.

note

We recommend following best practices when it comes to updating your database. For example, backing up the database before a migration and testing the scripts against a test instance of your database first. If in doubt, please contact your database administrator.

Overview

There are four main use cases for managing database schema migrations:

Default Schema Custom Schema
With Liquibase Case 1 Case 2
Without Liquibase Case 3 Case 4

i.e.:

  • Case 1: You use the default Atoti Limits schema and want to manage database schema migrations using Liquibase.
  • Case 2: You have customized the Atoti Limits schema and want to manage database schema migrations using Liquibase.
  • Case 3: You use the default Atoti Limits schema and want to manage database schema migrations using some other mechanism.
  • Case 4: You have customized the Atoti Limits schema and want to manage database schema migrations using some other mechanism.

warning

Please carefully select the appropriate case for your business needs. If you plan to use Liquibase, you must first initialize your database schema with Liquibase.

Prerequisites

If you want to use Liquibase to manage your database migrations, you first need to generate your initial database schema with Liquibase. This is because Liquibase stores a checksum in your database to determine where you are in the migration process.

Initializing your Liquibase schema

1. Default Atoti Limits Schema

If you are using the default Atoti Limits schema, you can generate the initial database schema using the provided master-changelog.yaml in the src/main/resources/liquibase folder of the limits-starter module. The master-changelog.yaml file is used to apply all the changesets listed in limits-starter/src/main/resources/liquibase/changelogs in the correct order.

note

The limits-3-3-0-changelog-0.yaml file is used to initialize the schemas for tables internal to Atoti Limits. The limits-3-3-0-changelog-1.yaml file is used to initialize the schemas for tables external to Atoti Limits (eg. Activiti). If you don’t want Liquibase to manage migrations for these external tables you can remove this file from master-changelog.yaml. If you want Liquibase to manage migrations for these external tables, you must ensure that Activiti does not try to migrate the schemas by setting the property spring.database-schema-update = drop-create. See the Activiti documentation for more information.

Here’s how to initialize the database schema:

  1. Configure the liquibase.properties file with the connections to your database. We have provided a sample in limits-starter/src/main/resources/liquibase.

  2. If not on your classpath, add the required database driver to your pom.xml file. See the liquibase example pom.xml for more info.

  3. Ensure your database server is running.

  4. Run mvn liquibase:update to apply the changes to your database.

    note

    You may also run mvn liquibase:updateSQL before the update command to inspect the raw SQL for potential issues.

  5. You can now use Liquibase to manage your database schema migrations.

2. Custom Atoti Limits Schema

If you have customized the Atoti Limits schema, you will need to create your own master-changelog.yaml and include your custom changesets. Please see the Liquibase documentation, specifically Maven’s generateChangeLog goal for how this can be done. You must then apply the same steps as in the previous section.

Migrating your schema

Case 1: Default Schema with Liquibase

  1. Ensure liquibase.properties is configured to point to your database.
  2. Ensure your database is running.
  3. Run mvn liquibase:update from limits-starter.

Case 2: Custom Schema with Liquibase

If you have a custom schema and are using Liquibase, you will need to create a master-changelog.yaml file that includes your custom changesets. Once created, please follow the same steps as in Case 1.

Case 3: Default Schema without Liquibase

If you are not using Liquibase, you can still use the changesets to generate the SQL required for migrations and apply them accordingly. To do so, you can run mvn liquibase:updateSQL to generate the SQL required for the migration. This will create a file by default in limits-starter/src/main/resources/liquibase/migrate.sql which you can then investigate and apply to your database.

Case 4: Custom Schema without Liquibase

If you have a custom schema and are using Liquibase, you will need to create a master-changelog.yaml file that includes your custom changesets. Once created, please follow the same steps as in Case 3.

FAQ

Why not use the SQL changelog format?

Liquibase offers two formats for changelogs: the SQL model and the platform-agnostic model. We chose the platform-agnostic model because it is more flexible and allows us to support multiple databases, which is how persistence in Atoti Limits is natively designed.

Why are the changesets in YAML format?

We felt YAML was the most human-readable format available. The other options were XML and JSON.

Can I print the difference between my existing database and the new database when I run the migration?

Yes, you may use the mvn liquibase:diff command to view any schema differences. This will also generate a changelog.

Can I print the SQL that will be executed before running a migration?

Yes, you may run mvn liquibase:updateSQL to view the raw SQL that will be executed. This will not alter your database.

Can I rollback a migration?

Yes, please see the Maven rollback command for options on how to rollback migrations.