Using Liquibase with MySQL

MySQL is a fast, multi-user SQL database service. MySQL Server is intended for mission-critical, heavy-load production systems as well as for embedding into mass-deployed software.

Note: For more information, see the MySQL documentation page.

Supported Versions

8.0 – officially certified (V4.2+) and tested with Test Harness
5.7 – officially certified (V4.2+) and tested with Test Harness
5.6 – community and Test Harness tested
5.5 – community tested

Prerequisites

Before using Liquibase and MySQL, ensure you have completed the following:

Completed Liquibase Installation.
Created a Liquibase project folder to store all Liquibase files.
Created a new liquibase.properties file or are using the existing liquibase.properties file included in the installation package. For more information, see Creating and configuring a liquibase.properties file.

Driver Information

To use Liquibase and MySQL, you need to have the JDBC file:

Ensure you have downloaded the MySQL JDBC Driver to connect to MySQL.
Place the mysql-connector-java-version.jar file in the liquibase/lib directory.

Note: If you put the mysql-connector-java-version.jar file in any other directory, specify the path to it in the liquibase.properties file: classpath:../path_to_drivers/mysql-connector-java-version.jar. For more information, see Creating and configuring a liquibase.properties file.

If you use Maven, you also need to download the MySQL driver jar file and put the driver in a location that your Maven build can access. Configure the Maven pom.xml file to use the local copy of the driver jar file. For example:

<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
<version>8.0.21</version>
</dependency>

Testing Your Connection

For Liquibase and MySQL to work, you need to:

Ensure your MySQL is configured. You can check the status by running:

The sudo service mysql status command for Linux.
The net start MySQL or services.msc command for Windows. The services.msc command will open a new window and display the list of services available on your system. Find MySQL and check the status column. You can also run mysql -u root -p to see if MySQL works.

Specify the database URL in your liquibase.properties file:

url: jdbc:mysql://<servername>:<port>/<dbname>

Tip: If you already have a Liquibase Pro key and want to apply it to your project, add the following property to your liquibase.properties file: liquibaseProLicenseKey: <paste license key>.

Create a text file called changelog (.xml, .sql, .json, or .yaml) in your project directory and add a changeset.

XML example

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog						
xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:pro="http://www.liquibase.org/xml/ns/pro"						
xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.1.xsd
http://www.liquibase.org/xml/ns/pro http://www.liquibase.org/xml/ns/pro/liquibase-pro-4.1.xsd">						
<changeSet id="1" author="Liquibase">
   <createTable tableName="test_table">
     <column name="test_id" type="int">
        <constraints primaryKey="false"/>
     </column>
     <column name="test_column" type="varchar(10)"/>
   </createTable>
</changeSet>
</databaseChangeLog>

SQL example

-- liquibase formatted sql

-- changeset Liquibase:1 
CREATE TABLE test_table (test_id INT NULL, test_column VARCHAR(10) NULL);

Note: Formatted SQL changelogs generated by using Liquibase versions previous to 4.2 might cause issues because of the lack of space after a double dash ( -- ).

Tip: To fix those issues, add a space after the double dash. For example: -- liquibase formatted sql instead of --liquibase formatted sql and -- changeset myname:create-table instead of --changeset myname:create-table

YAML example

databaseChangeLog:
- changeSet:
   id: 1
   author: Liquibase
   changes:
   - createTable:
	   columns:
	   - column:
		   name: test_id
		   type: INT
	   - column:
		   name: test_column
		   type: VARCHAR(10)
	   tableName: test_table

JSON example

{ "databaseChangeLog": [
  {
	"changeSet": {
	  "id": "1",
	  "author": "Liquibase",
	  "changes": [
	    {
		  "createTable": {
			"columns": [
			  {
				"column": {
				   "name": "test_id",
				   "type": "INT"
				 }
			  },
			  {
				"column": {
				   "name": "test_column",
				   "type": "VARCHAR(10)"
				}
			 }]
		   ,
		   "tableName": "test_table"
		}
	 }]
      
   }
 }
  
]}

Run the status command to see whether the connection is successful. Specify the name of the changelog you created in place of changelog.xml. Also, to run Liquibase commands, you need to specify your username and password in the liquibase.properties file or on the command line. However, the username and password attributes are not required for connections and systems which use alternate means of authentication.

liquibase --username=test --password=test --changeLogFile=changelog.xml status

Note: Alternatively, you can add the changeLogFile attribute to your liquibase.properties file.

Run your first update with the Liquibase update command, which will make changes to your database. You can also run the updateSQL command if you want to inspect the SQL before running the update command.

liquibase --changeLogFile=changelog.xml updateSQL
liquibase --changeLogFile=changelog.xml update

After your first update, you will see a new table along with the DATABASECHANGELOG and DATABASECHANGELOGLOCK tables added to the database:

DATABASECHANGELOG table. This table keeps a record of all the changesets that were deployed. When you deploy, the changesets in the changelog are compared with the DATABASECHANGELOG tracking table, and only the new changesets that were not found in the DATABASECHANGELOG will be deployed.
DATABASECHANGELOGLOCK table. This table is used internally by Liquibase to manage access to the DATABASECHANGELOG table during deployment and ensure only one instance of Liquibase is updating the database at a time, whether that is creating, updating or deleting changes.

Supported Commands and Change Types

Change Type	Supported	Command	Supported
`addAutoIncrement`	Supported	`calculateCheckSum <id>`	Supported
`addCheckConstraint`	Not Supported	`changelogSync`	Supported
`addColumn`	Supported	`changelogSyncSQL`	Supported
`addDefaultValue`	Supported	`changelogSyncToTag`	Supported
`addForeignKeyConstraint`	Supported	`changelogSyncToTagSQL`	Supported
`addLookupTable`	Supported	`clearCheckSums`	Supported
`addNotNullConstraint`	Supported	`dbDoc`	Supported
`addPrimaryKey`	Supported	`deactivateChangeLog`	Supported
`addUniqueConstraint`	Supported	`diff`	Supported
`alterSequence`	Not Supported	`diff JSON`	Supported
`createFunction`	Supported	`diffChangeLog`	Supported
`createIndex`	Supported	`dropAll`	Supported
`createPackage`	Supported	`futureRollbackCountSQL <value>`	Supported
`createPackageBody`	Supported	`future-rollback-from-tag-sql <tag>`	Supported
`createProcedure`	Supported	`futureRollbackSQL`	Supported
`createSequence`	Not Supported	`generateChangeLog`	Supported
`createSynonym`	Not Supported	`help`	Supported
`createTable`	Supported	`history`	Supported
`createTrigger`	Supported	`listLocks`	Supported
`createView`	Supported	`markNextChangeSetRan`	Supported
`customChange`	Supported	`markNextChangeSetRanSQL`	Supported
`delete`	Supported	`registerChangeLog`	Supported
`disableCheckConstraint`	Not Supported	`releaseLocks`	Supported
`disableTrigger`	Not Supported	`rollback <tag>`	Supported
`dropAllForeignKeyConstraints`	Supported	`rollbackCount <value>`	Supported
`dropCheckConstraint`	Not Supported	`rollbackCountSQL <value>`	Supported
`dropColumn`	Supported	`rollbackOneChangeSet`	Supported
`dropDefaultValue`	Supported	`rollbackOneChangeSetSQL`	Supported
`dropForeignKeyConstraint`	Supported	`rollbackOneUpdate`	Supported
`dropFunction`	Supported	`rollbackOneUpdateSQL`	Supported
`dropIndex`	Supported	`rollbackSQL <tag>`	Supported
`dropNotNullConstraint`	Supported	`rollbackToDate`	Supported
`dropPackage`	Supported	`rollbackToDateSQL`	Supported
`dropPackageBody`	Supported	`snapshot`	Supported
`dropPrimaryKey`	Supported	`snapshotReference`	Supported
`dropProcedure`	Supported	`status --verbose`	Supported
`dropSequence`	Not Supported	`syncHub`	Supported
`dropSynonym`	Not Supported	`tag <tag string>`	Supported
`dropTable`	Supported	`tagExists <tag string>`	Supported
`dropTrigger`	Supported	`unexpectedChangeSets`	Supported
`dropUniqueConstraint`	Supported	`update`	Supported
`dropView`	Supported	`updateSQL`	Supported
`empty`	Supported	`updateCount <value>`	Supported
`enableCheckConstraint`	Not Supported	`updateCountSQL <value>`	Supported
`enableTrigger`	Not Supported	`updateTestingRollback`	Supported
`executeCommand`	Supported	`updateToTag <tag>`	Supported
`insert`	Supported	`updateToTagSQL <tag>`	Supported
`loadData`	Supported	`validate`	Supported
`loadUpdateData`	Supported
`markUnused`	Not Supported
`mergeColumns`	Supported
`modifyDataType`	Supported
`output`	Supported
`renameColumn`	Supported
`renameSequence`	Not Supported
`renameTable`	Supported
`renameTrigger`	Not Supported
`renameView`	Supported
`setColumnRemarks`	Supported
`setTableRemarks`	Supported
`sql`	Supported
`sqlFile`	Supported
`stop`	Supported
`tagDatabase`	Supported
`update`	Supported

Using Liquibase with MySQL

Supported Versions

Prerequisites

Driver Information

Testing Your Connection

Supported Commands and Change Types

Related Links