How to set up Liquibase with an Existing Project and Multiple Environments

The Getting Started Guide works when you want to use Liquibase on a new environment with an empty changelog file that matches your empty database. However, when you have multiple environments and want to set up Liquibase with all of them to match your current database schema, the process differs.

For example, you have an HR database and two different environments called: HR_Dev and HR_Test, and you want them all to match your HR database.

You will learn how to introduce Liquibase to your HR_Dev and HR_Test database environments without affecting your current database schema. You will create a changelog file that matches the current state of your HR database and then apply this changelog file to the HR_Dev and HR_Test databases so it will match all the environments.

Step 1: Create a changelog

First, you will create a changelog file that contains all the SQL changes from the source HR database. You can create a changelog file to match your HR database manually or it can be done automatically by using the generateChangeLog command.

Note: For any database larger than a few tables, use the generateChangeLog command.

To run the generateChangeLog command, you need to specify your driver, class path, URL, and user authentication information in your file. For more information, see Creating and configuring a file. You can also specify these properties in your command line.

Then run the generateChangeLog command:

liquibase --changeLogFile=dbchangelog.xml generateChangeLog

Note: Enter the name of the changelog that you want to use in place of dbchangelog.xml.

The generateChangeLog command generates a changelog file that contains all your objects (represented as changesets) and places the file in the same directory where the command was run.

Note: If there is a project that requires working on multiple schemas in one workflow, you can have the changelog containing multiple schemas by adding the following flags --schemas=<schema1>,<schem2>,<schema3> and --includeSchema=true to the generateChangeLog command.

The changelog file name extension determines the format of the changelog, so if you specify the file name as changelog.xml, you will get an XML formatted changelog. Likewise, if you specify the file name as .yaml, .json, or .sql, you will get changelogs formatted in YAML, JSON, or SQL, respectively.

Note: If you generate an SQL formatted changelog, specify the type name of the targeted database as a part of the file name:


Note: Liquibase does not always detect complex structures like stored procedures or details like an index that is not clustered. Once you have generated a changelog, inspect the output. Review the generated changesets and ensure that the data types look as expected.

Step 2: Populate the DATABASECHANGELOG tracking table

Once you have your changelog file, populate the DATABASECHANGELOG tracking table with the changesets from this changelog.

Liquibase keeps track of your already deployed changes with the help of its DATABASECHANGELOG tracking table.

To create this table for the first time, use the changeLogSync command. The changeLogSync command will populate the DATABASECHANGELOG table with the changesets metadata as if you have been using Liquibase all along.

Another approach you can choose is to add the contexts.

Running the changeLogSyncSQL and changeLogSync commands:

  • Run the changeLogSyncSQL command to inspect the SQL and ensure that everything looks good before executing the changeLogSync command:
liquibase --changelogFile=dbchangelog.xml changelogSyncSQL

Note: Enter the name of the changelog that you want to use in place of dbchangelog.xml.

  • Run the changeLogSync command to ensure that the changesets are treated as already run since they exist in our HR database. The command will mark the changesets in the changelog file as already deployed. This will prevent Liquibase from attempting to redeploy those changesets next time when you run the update command.
liquibase --changelogFile=dbchangelog.xml changelogSync

Note: Enter the name of the changelog that you want to use in place of dbchangelog.xml.

Adding the contexts

Alternatively, you can add contexts to the changesets such as <changeSet ... context="legacy">:

<changeSet  author="diff-generated"  id="1185214997195-8" context="legacy">
	<addPrimaryKey  columnNames="DEPTNO"  tableName="DEPT"/>

The contexts can be added to the changeset to control which changeset will be executed in any run. Only the changesets marked with the specific contexts in your changelog that are used with the --contexts flag during the runtime will be run.

  • When you run the changelog on the HR_Dev and HR_Test database environments, enter the following:
liquibase --contexts=legacy update
  • When you run it on your existing database, which is HR, enter the following:
liquibase --contexts=non-legacy update

After creating a changelog and populating the HR DATABASECHANGELOG table with the changeLogSync command or with the contexts, you can now deploy this generated changelog to the HR_Dev and HR_Test database environments that need to match you HR database.