Overview

Summary

Extension to support the tool pt-online-schema-change from Percona Toolkit. This extension replaces a couple of the default changes to use pt-online-schema-change instead of SQL. This allows to perform a non-locking database upgrade.

Current Version

4.20.0 (2023-03-10)

Support for Liquibase 4.20.0.

Dependency updates:

Bump liquibase-core from 4.19.1 to 4.20.0 #306 (@dependabot[bot])
Bump tomcat-jdbc from 10.1.6 to 10.1.7 #305 (@dependabot[bot])

	File	Modified
Labels No labels Preview View	Java Archive liquibase-percona-4.20.0.jar	Mar 10, 2023 by Nathan Voxland

Author

Andreas Dangel (andreas.dangel [at] adangel.org)

Issue Tracking

https://github.com/liquibase/liquibase-percona/issues

Source Repository

https://github.com/liquibase/liquibase-percona.git

Maven Coordinates

org.liquibase.ext:liquibase-percona

Supported Database

MySQL, MariaDB (since 4.3.2)

1 Overview
2 Readme
- 2.1 Supported Databases
- 2.2 Supported Changeset Formats
- 2.3 Liquibase version(s) tested against
- 2.4 Supported Changes and examples
  - 2.4.1 AddColumn
  - 2.4.2 AddForeignKeyConstraint
  - 2.4.3 AddPrimaryKey
  - 2.4.4 AddUniqueConstraint
  - 2.4.5 CreateIndex
  - 2.4.6 DropColumn
  - 2.4.7 DropForeignKeyConstraint
  - 2.4.8 DropUniqueConstraint
  - 2.4.9 DropIndex
  - 2.4.10 ModifyDataType
  - 2.4.11 Sql
- 2.5 Configuration
  - 2.5.1 UsePercona flag
  - 2.5.2 PerconaOptions flag
  - 2.5.3 Liquibase Percona extension XSD
  - 2.5.4 System Properties
- 2.6 Using / Installing the extension
  - 2.6.1 Download
  - 2.6.2 Command line liquibase
  - 2.6.3 Via maven
  - 2.6.4 Docker
  - 2.6.5 Using snapshots
- 2.7 Notes
- 2.8 Building this extension
  - 2.8.1 Integration testing
- 2.9 Common Problems
  - 2.9.1 NoSuchMethodError: PerconaDropColumnChange.getColumns()Ljava/util/List
- 2.10 References
- 2.11 Old Versions and Release Notes

Readme

Supported Databases

MySQL and MariaDB (since 4.3.2) are the only supported databases. The extension checks whether it is being run against a MySQL/MariaDB database. If not, it falls back to the default changes provided by liquibase-core.

Supported Changeset Formats

This liquibase extension supports the following changeset formats:

XML
YAML
Formatted SQL (since liquibase-percona 4.19.1)

Liquibase version(s) tested against

Liquibase 3.2.0 (liquibase-percona 1.0.0)
Liquibase 3.3.0 (liquibase-percona 1.1.1)
Liquibase 3.3.5 and 3.4.2 (liquibase-percona 1.2.1)
Liquibase 3.3.5, 3.4.2, and 3.5.1 (liquibase-percona 1.2.2)
Liquibase 3.3.5, 3.4.2, and 3.5.3 (liquibase-percona 1.3.1, 1.4.0)
Liquibase 3.3.5, 3.4.2, and 3.5.4 (liquibase-percona 1.4.1)
Liquibase 3.3.5, 3.4.2, 3.5.5, and 3.6.2 (liquibase-percona 1.5.2). Percona Toolkit 3.0.12.
Liquibase 3.3.5, 3.4.2, 3.5.5, and 3.6.3 (liquibase-percona 1.6.0). Percona Toolkit 3.0.13.
Liquibase 3.5.5, 3.6.3, 3.7.0, 3.8.9, 3.9.0, and 3.10.1 (liquibase-percona 1.7.0). Percona Toolkit 3.2.0.
Liquibase 3.5.5, 3.6.3, 3.7.0, 3.8.9, 3.9.0, and 3.10.3 (liquibase-percona 1.7.1). Percona Toolkit 3.3.0.
Liquibase 4.0.0, 4.1.1, 4.2.2 (liquibase-percona 2.0.0). Percona Toolkit 3.3.0.
Liquibase 4.0.0, 4.1.1, 4.2.2, 4.3.5, 4.4.3, 4.5.0, 4.6.2, 4.7.1, 4.8.0, 4.9.1, 4.10.0, 4.11.0, 4.12.0 (liquibase-percona 4.12.0). Percona Toolkit 3.3.1.
Liquibase 4.0.0, 4.1.1, 4.2.2, 4.3.5, 4.4.3, 4.5.0, 4.6.2, 4.7.1, 4.8.0, 4.9.1, 4.10.0, 4.11.0, 4.12.0, 4.13.0, 4.14.0, 4.15.0 (liquibase-percona 4.15.0). Percona Toolkit 3.4.0.
Liquibase 4.16.0 (liquibase-percona 4.16.0). Percona Toolkit 3.4.0.
Liquibase 4.17.1 (liquibase-percona 4.17.1). Percona Toolkit 3.4.0.
Liquibase 4.18.0 (liquibase-percona 4.18.0). Percona Toolkit 3.5.0.
Liquibase 4.19.0 (liquibase-percona 4.19.0). Percona Toolkit 3.5.0.
Liquibase 4.19.1 (liquibase-percona 4.19.1). Percona Toolkit 3.5.1.
Liquibase 4.20.0 (liquibase-percona 4.20.0). Percona Toolkit 3.5.1.

Supported Changes and examples

The following changes are supported:

AddColumn

Since: liquibase-percona 1.0.0

Automatic rollback supported? yes

Example:

<changeSet id="2" author="Alice">
    <addColumn tableName="person">
        <column name="address" type="varchar(255)"/>
    </addColumn>
</changeSet>

Corresponding command:

pt-online-schema-change --alter="ADD COLUMN address VARCHAR(255)" ...

AddForeignKeyConstraint

Since: liquibase-percona 1.3.0

Automatic rollback supported? yes

Example:

<changeSet id="3" author="Alice">
    <addForeignKeyConstraint constraintName="fk_person_address"
        referencedTableName="person" referencedColumnNames="id"
        baseTableName="address" baseColumnNames="person_id"/>
</changeSet>

Corresponding command:

pt-online-schema-change --alter="ADD CONSTRAINT fk_person_address FOREIGN KEY (person_id) REFERENCES person (id)" ...

AddPrimaryKey

Since: liquibase-percona 1.7.0

Automatic rollback supported? no

Example:

<changeSet id="2" author="Alice">
    <addPrimaryKey tableName="person" columnNames="id, name"/>
</changeSet>

Corresponding command:

pt-online-schema-change --alter="DROP PRIMARY KEY, ADD PRIMARY KEY (id, name)" ...

Note: When the table has already a primary key, a "DROP PRIMARY KEY" statement is added to the
alter command first. By default, the pt-online-schema-change will not execute this change,
you have to set the additional option --no-check-alter first (see check-alter).
Make sure to read this section completely.

In order to figure out, whether a primary key exists already (and therefore the DROP PRIMARY KEY statement is needed),
a database connection is required. This means, the generated migration SQL will be wrong (it only contains the
ADD PRIMARY KEY statement).

Automatic rollback is not supported by this percona change (as opposed to the plain liquibase addPrimaryKey change).
pt-osc usually needs a primary key or a unique key in order to operate properly. If the table has no such keys,
it most likey will refuse to operate.

AddUniqueConstraint

Since: liquibase-percona 1.3.0

Automatic rollback supported? yes

Example:

<changeSet id="2" author="Alice">
    <addUniqueConstraint columnNames="id, name" tableName="person" constraintName="uq_id_name"/>
</changeSet>

Corresponding command:

pt-online-schema-change --alter="ADD CONSTRAINT uq_id_name UNIQUE (id, name)" ...

CreateIndex

Since: liquibase-percona 1.2.0

Automatic rollback supported? yes

Example:

<changeSet id="2" author="Alice">
    <createIndex indexName="emailIdx" tableName="person" unique="true">
        <column name="email"/>
    </createIndex>
</changeSet>

Corresponding command:

pt-online-schema-change --alter="ADD UNIQUE INDEX emailIdx (email)" ...

DropColumn

Since: liquibase-percona 1.0.0

Automatic rollback supported? no

Example:

<changeSet id="2" author="Alice">
    <dropColumn tableName="person" columnName="age"/>
</changeSet>

Corresponding command:

pt-online-schema-change --alter="DROP COLUMN age" ...

DropForeignKeyConstraint

Since: liquibase-percona 1.3.0

Automatic rollback supported? no

Example:

<changeSet id="4" author="Alice">
    <dropForeignKeyConstraint baseTableName="address" constraintName="fk_person_address" />
</changeSet>

Corresponding command:

pt-online-schema-change --alter="DROP FOREIGN KEY _fk_person_address" ...

DropUniqueConstraint

Since: liquibase-percona 1.3.0

Automatic rollback supported? no

Example:

<changeSet id="3" author="Alice">
    <dropUniqueConstraint tableName="person" constraintName="uq_id_name"/>
</changeSet>

Corresponding command:

pt-online-schema-change --alter="DROP KEY uq_id_name" ...

DropIndex

Since: liquibase-percona 1.2.0

Automatic rollback supported? no

Example:

<changeSet id="3" author="Alice">
    <dropIndex indexName="emailIdx" tableName="person"/>
</changeSet>

Corresponding command:

pt-online-schema-change --alter="DROP INDEX emailIdx" ...

ModifyDataType

Since: liquibase-percona 1.2.0

Automatic rollback supported? no

Example:

<changeSet id="2" author="Alice">
    <modifyDataType tableName="person" columnName="email" newDataType="VARCHAR(400)"/>
</changeSet>

Corresponding command:

pt-online-schema-change --alter="MODIFY email VARCHAR(400)" ...

Sql

Since: liquibase-percona 4.19.1

Automatic rollback supported? no

Example:

<changeSet id="2" author="Alice">
    <sql>ALTER TABLE person ADD COLUMN address VARCHAR(255) NULL</sql>
</changeSet>

Corresponding command:

pt-online-schema-change --alter="ADD COLUMN address VARCHAR(255) NULL" ...

Note that there are several limitations:

Percona toolkit won't be used, when the sql statements consists of multiple statements (e.g. separated by ;). In that case a warning will be logged and the sql change will be executed as usual without the percona toolkit.
If the sql change is not an alter table statement, then a warning will be logged and the sql change will be executed as usual without the percona toolkit.
Liquibase-percona tries to determine the table name. If that doesn't work, then a warning will be logged and the sql change will be executed as usual without the percona toolkit.
This change type is active by default and percona toolkit will be used when possible. It can be disabled as usual via system property liquibase.percona.skipChanges.
Be sure to test the changelog thoroughly.

Configuration

UsePercona flag

Each change allows to enable or disable the usage of percona toolkit via the property usePercona. By default, the percona toolkit is used, see also the system property liquibase.percona.defaultOn.

Example:

- changeSet:
    id: 2
    author: Alice
    changes:
      - addColumn:
          tableName: person
          usePercona: false
          columns:
            - column:
                name: address
                type: varchar(255)

This flag exists since liquibase-percona 1.3.0

It is supported by using the YAML format and since liquibase 3.6.0, you can use it in XML changesets, too:

<addColumn tableName="person"
       xmlns:liquibasePercona="http://www.liquibase.org/xml/ns/dbchangelog-ext/liquibase-percona"
       liquibasePercona:usePercona="false">
    <column name="address" type="varchar(255)"/>
</addColumn>

Since liquibase-percona 4.19.1, you can use it in SQL changeset as follows:

--changeset Alice:2
--liquibasePercona:usePercona="false"
ALTER TABLE person ADD address VARCHAR(255) NULL;

PerconaOptions flag

Each change allows to specify options that are used when executing pt-osc. If specified, this option overrides the system property liquibase.percona.options. If not specified, then the system property will be used.

Example:

- changeSet:
    id: 2
    author: Alice
    changes:
      - addColumn:
          tableName: person
          perconaOptions: "--alter-foreign-keys-method=auto"
          columns:
            - column:
                name: address
                type: varchar(255)

This flag exists since liquibase-percona 2.0.0.

It is supported by using the YAML format and in XML changesets:

<addColumn tableName="person"
        xmlns:liquibasePercona="http://www.liquibase.org/xml/ns/dbchangelog-ext/liquibase-percona"
        liquibasePercona:perconaOptions="--alter-foreign-keys-method=auto">
    <column name="address" type="varchar(255)"/>
</addColumn>

Since liquibase-percona 4.19.1 this is also supported in SQL changesets:

--changeset Alice:2
--liquibasePercona:perconaOptions="--alter-foreign-keys-method=auto"
ALTER TABLE person ADD email VARCHAR(255) NULL;

Liquibase Percona extension XSD

According to the Liquibase Documentation for XML Changelogs an extra XSD for the extension is not mandatory as there an "allow all" default schema (dbchangelog-ext.xsd). But having an explicit schema helps in IDE support (e.g. autocomplete, validation). Therefore, this extension provides an official XSD for the attributes it supports on the changes (usePercona and perconaFlags).

Example usage:

<?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:liquibasePercona="http://www.liquibase.org/xml/ns/dbchangelog-ext/liquibase-percona"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
        http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd
        http://www.liquibase.org/xml/ns/dbchangelog-ext/liquibase-percona https://raw.githubusercontent.com/liquibase/liquibase-percona/main/src/main/resources/dbchangelog-ext-liquibase-percona.xsd">

    <changeSet  id="1" author="alice">
        <addColumn tableName="person" liquibasePercona:usePercona="false">
            <column name="address" type="varchar(255)"/>
        </addColumn>
    </changeSet>
</databaseChangeLog>

If you use as the URL exactly https://raw.githubusercontent.com/liquibase/liquibase-percona/main/src/main/resources/dbchangelog-ext-liquibase-percona.xsd, then liquibase doesn't retrieve the XSD file from the internet but uses the locally provided file inside liquibase-percona.jar instead.

Otherwise, you need to set the system property liquibase.secureParsing to false, so that liquibase downloads the extension schema from the internet in order to validate the XML changelog file.

The extension schema is available in the repository: dbchangelog-ext-liquibase-percona.xsd.

System Properties

The extension supports the following java system properties:

liquibase.percona.failIfNoPT: true/false. Default: false. If set to true, the database update will fail, if the command pt-online-schema-change is not found. This can be used, to enforce, that percona toolkit is used.
liquibase.percona.noAlterSqlDryMode: true/false. Default: false. When running updateSQL or rollbackSQL in order to generate a migration SQL file, the command line, that would be executed, will be added as a comment. In addition, the SQL statements (as produced by liquibase-core) will also be generated and output into the migration file. This allows to simply execute the generated migration SQL to perform an update. However, the Percona toolkit won't be used. If this property is set to true, then no such SQL statements will be output into the migration file.
liquibase.percona.skipChanges: comma separated list of changes. Default: <empty>. This option can be used in order to selectively disable one or more changes. If a change is disabled, then the change will be executed by the default liquibase core implementation and percona toolkit won't be used. By default, this property is empty, so that all supported changes are executed using the percona toolkit. Example: Set this to addColumn,dropColumn in order to not use percona for adding/dropping a column.
liquibase.percona.options: String of options. Default: --alter-foreign-keys-method=auto --nocheck-unique-key-change. Since liquibase-percona 1.2.1. Default value changed with liquibase-percona 1.6.0. This option allows the user to pass additional command line options to pt-online-schema-change. This e.g. can be used in complication replication setup to change the way slaves are detected and how their state is used. You can also specify a percona configuration file via --config file.conf, see Configuration Files. Multiple options are separated by space. If argument itself contains a space, it must be quoted with double-quotes, e.g. --config "filename with spaces.conf".
liquibase.percona.defaultOn: true/false. Default: true. Since liquibase-percona 1.3.0 This options allows to change the default behavior for the UsePercona flag. By default, all changes, that do not explicitly specify this flag, use the value from this system property. Setting this property to false allows to control for each single change, whether to use Percona Toolkit or not.
liquibase.password: String with the password needed to connect to the database. Default: <empty>. Since liquibase-percona 1.4.0. With this property, you can shortcut the automatic detection of the password from the underlying java.sql.Connection (if that fails) or from the default liquibase.properties file. If this property is set, then it is used for the password when executing pt-online-schema-change.
liquibase.percona.path: Path to the percona toolkit directory, where the tool pt-online-schema-change is installed. Default: <empty>. Since liquibase-percona 1.4.1. With this property, you can select a specific toolkit installation. If this property is not set, then the toolkit will be searched on the PATH. You need to specify the bin subfolder of the Percona Toolkit distribution.
liquibase.percona.ptdebug: true/false. Default: false. Since liquibase-percona 1.5.0 This option enables the debug output of pt-osc by setting the environment variable PTDEBUG before starting pt-osc.
liquibase.percona.keepAlive: true/false. Default: true Since liquibase-percona 4.4.0 This option allows to disable the keepalive thread if there are any problems with it. The keepalive thread pings the database while pt-online-schema-change is executing. This avoids that the server closes liquibase's connection as it is idle during pt-osc. The server variable "wait_timeout" controls when the connection is considered stale and dropped by the server. This variable is used to determine how often the server will be pinged.

You can set these properties by using the standard java -D option:

java -Dliquibase.percona.skipChanges=createIndex,dropColumn -jar liquibase.jar ...

Note: You'll have to call liquibase via "java -jar" as otherwise the system property cannot be set. You'll also need to make sure, that the liquibase-percona.jar file is on the classpath via the "--classpath" option.

When executing liquibase through maven, you can use the Properties Maven Plugin to set the system property. An example can be found in the "createIndexSkipped" integration test.

Using / Installing the extension

Download

The jar files can be downloaded manually from maven:

https://repo.maven.apache.org/maven2/org/liquibase/ext/liquibase-percona/

Command line liquibase

After extracting the zip file of liquibase, place liquibase-percona-4.20.0.jar file in the sub directory lib. The shell script liquibase / liquibase.bat will automatically pick this up and the extension is available.

Via maven

Add the following dependency to the liquibase plugin:

<dependency>
    <groupId>org.liquibase.ext</groupId>
    <artifactId>liquibase-percona</artifactId>
    <version>4.20.0</version>
</dependency>

Docker

You can also create a docker image which combines liquibase, liquibase-percona and percona toolkit. See Liquibase Percona Docker images.

Using snapshots

Snapshot builds contain the latest features which are not yet available in a release.

Download: https://oss.sonatype.org/content/repositories/snapshots/org/liquibase/ext/liquibase-percona/

Enable the snapshot repository via Maven:

<project>
    <pluginRepositories>
        <pluginRepository>
            <id>sonatype-nexus-snapshots</id>
            <name>Sonatype Nexus Snapshots</name>
            <url>https://oss.sonatype.org/content/repositories/snapshots</url>
            <releases>
                <enabled>false</enabled>
            </releases>
            <snapshots>
                <enabled>true</enabled>
            </snapshots>
        </pluginRepository>
    </pluginRepositories>
</project>

And just use the latest SNAPSHOT version for liquibase-percona dependency, e.g. 4.20.1-SNAPSHOT:

<dependency>
    <groupId>org.liquibase.ext</groupId>
    <artifactId>liquibase-percona</artifactId>
    <version>4.20.1-SNAPSHOT</version>
</dependency>

Notes

The non-locking update is achieved using triggers. First a new temporary table is created, including the added or dropped columns. Then the data is copied in chunks. While the copy is in progress, any newly created or deleted or updated rows are copied, too. This is done by adding triggers to the original table. After the copy is finished, the original table is dropped and the temporary table is renamed.

This means, that pt-online-schema-change cannot be used, if the table already uses triggers.

The command pt-online-schema-change is searched only on the PATH. Depending on the property liquibase.percona.failIfNoPT the update will fail or will just run without using pt-online-schema-change and potentially lock the table for the duration of the update.

Building this extension

Simply run ./mvn clean verify. You'll find the jar-file in the target/ subdirectory.

Integration testing

In order to execute the integration tests, run mvn clean verify -Prun-its.

Please note, that you'll need:

docker. During the pre-integration-test phase the official mysql image will be started. Under debian, execute sudo apt-get install docker.io.
Internet access to download the docker image the first time. And to download percona toolkit. The build system will add the downloaded toolkit automatically to the PATH.
The percona toolkit requires perl with mysql dbi libraries. Under debian, execute sudo apt-get install libdbd-mysql-perl.

See the properties config_... in pom.xml for connection details for the mysql docker instance.

To run a single integration test, execute maven like this: ./mvn verify -Prun-its -Dinvoker.test=addColumn*,dropColumn

Common Problems

NoSuchMethodError: PerconaDropColumnChange.getColumns()Ljava/util/List

The full error message:

Unexpected error running Liquibase: liquibase.exception.UnexpectedLiquibaseException:
java.lang.NoSuchMethodError: liquibase.ext.percona.PerconaDropColumnChange.getColumns()Ljava/util/List;

This means, you are trying to use version 1.1.1 of the extension with liquibase 3.2.x. This is an unsupported combination. For Liquibase 3.2.x, you'll need to use liquibase-percona 1.0.0

References

Old Versions and Release Notes

March 10, 2023	4.20.0	4.20.0 (2023-03-10) Support for Liquibase 4.20.0. Dependency updates: Bump liquibase-core from 4.19.1 to 4.20.0 #306 (@dependabot[bot]) Bump tomcat-jdbc from 10.1.6 to 10.1.7 #305 (@dependabot[bot])
March 3, 2023	4.19.1	4.19.1 (2023-03-03) Support for Liquibase 4.19.1. New Features This release of Liquibase Percona extension ships two new features. Support for Custom SQL changes You can now use Custom SQL changes. The Liquibase Percona extension will automatically detect if it is a `ALTER TABLE` statement and will execute it using Percona Toolkit's `pt-online-schema-change` command. There are some limitations: Only a single statement is supported. When multiple statements (e.g. separated by `;`) are used, then the change is executed as usual. Also, if it is not an `ALTER TABLE` statement, the change is executed as usual without Percona Toolkit. If the statement can't be executed, a warning is logged. Support for Custom SQL changes is enabled by default. The Liquibase Percona extension will automatically try to execute Custom SQL changes via the Percona Toolkit. If this is not what you want, either disable the extension for this change globally (e.g. via the system property `liquibase.percona.skipChanges=sql`) or individually per change via the UsePercona flag. You can also globally disable Percona Toolkit usage with the system property `liquibase.percona.defaultOn` and enable it for specific changes only. See System Properties. Example usage in XML: `<databaseChangeLog> <changeSet id="2" author="Alice"> <sql>ALTER TABLE person ADD COLUMN address VARCHAR(255) NULL</sql> </changeSet> <changeSet id="3" author="Alice"> <sql xmlns:liquibasePercona="http://www.liquibase.org/xml/ns/dbchangelog-ext/liquibase-percona" liquibasePercona:usePercona="false"> ALTER TABLE person ADD COLUMN address VARCHAR(255) NULL </sql> </changeSet> </databaseChangeLog>` Example usage in YAML: `databaseChangeLog: - changeSet: id: 2 author: Alice changes: - sql: splitStatements: true sql: \| ALTER TABLE person ADD COLUMN address VARCHAR(255) NULL; - changeSet: id: 3 author: Alice changes: - sql: usePercona: false splitStatements: true sql: \| ALTER TABLE person ADD COLUMN address VARCHAR(255) NULL;` Support for Formatted SQL Changelogs You can now use Formatted SQL Changelogs. It also supports the `usePercona` flag. The implementation reuses the support for Custom SQL changes. This means, that the same limitations apply to SQL Changelogs: Multiple statements are not supported. Only `ALTER TABLE` statements are executed with Percona Toolkit's `pt-online-schema-change`. Support for SQL Changelogs is enabled by default. If you apply a SQL changelog with Liquibase Percona extension, then it will try to execute all changeset with Percona Toolkit if possible. If this is not what you want, you need to make use of the UsePercona flag. You can also globally disable Percona Toolkit usage with the system property `liquibase.percona.defaultOn` and enable it for specific changes only. See System Properties. Example usage: `--changeset Alice:2 ALTER TABLE person ADD address VARCHAR(255) NULL; --changeset Alice:3 --liquibasePercona:usePercona="false" ALTER TABLE person ADD address VARCHAR(255) NULL;` Implemented enhancements: Support formatted SQL changelogs #287 Support usePercona on SQL change type #80 Include extension schema properly #294 (@adangel) Add support for Formatted SQL changelogs #292 (@adangel) Add support for SQL change type #291 (@adangel) Fixed bugs: Changes with pt-osc are executed multiple times (liquibase 4.19.1) #303 Fix percona toolkit download after Percona homepage change #285 (@adangel) Dependency updates: Bump liquibase-core from 4.19.0 to 4.19.1 #302 (@dependabot[bot]) Bump docker-maven-plugin from 0.41.0 to 0.42.0 #301 (@dependabot[bot]) Bump snakeyaml from 1.33 to 2.0 #300 (@dependabot[bot]) Bump spotbugs-maven-plugin from 4.7.3.0 to 4.7.3.2 #299 (@dependabot[bot]) Bump maven-compiler-plugin from 3.10.1 to 3.11.0 #298 (@dependabot[bot]) Bump tomcat-jdbc from 10.1.5 to 10.1.6 #297 (@dependabot[bot]) Bump maven from 3.8.6 to 3.9.0 #290 (@adangel) Bump maven-javadoc-plugin from 3.4.1 to 3.5.0 #289 (@dependabot[bot]) Bump maven-invoker-plugin from 3.4.0 to 3.5.0 #288 (@dependabot[bot]) Bump percona toolkit from 3.5.0 to 3.5.1 #286 (@adangel) Bump maven-deploy-plugin from 3.0.0 to 3.1.0 #284 (@dependabot[bot]) Bump docker-maven-plugin from 0.40.3 to 0.41.0 #283 (@dependabot[bot]) Bump maven-enforcer-plugin from 3.1.0 to 3.2.1 #282 (@dependabot[bot]) Bump mariadb-java-client from 3.1.0 to 3.1.2 #281 (@dependabot[bot]) Closed issues: Liquibase percona extension (URL) no longer available #275 Merged pull requests: Refactor PTOnlineSchemaChangeStatement to be a ExecutablePreparedStatement #304 (@adangel) Fix deprecation warning about `set-output` #295 (@adangel)
January 20, 2023	4.19.0	4.19.0 (2023-01-20) Support for Liquibase 4.19.0. Dependency updates: Bump activesupport from 7.0.2.2 to 7.0.4.1 #280 (@dependabot[bot]) Bump liquibase-core from 4.18.0 to 4.19.0 #279 (@dependabot[bot]) Bump tomcat-jdbc from 10.1.4 to 10.1.5 #278 (@dependabot[bot]) Bump maven-pmd-plugin from 3.19.0 to 3.20.0 #276 (@dependabot[bot]) Bump junit-jupiter from 5.9.1 to 5.9.2 #274 (@dependabot[bot]) Bump docker-maven-plugin from 0.40.2 to 0.40.3 #273 (@dependabot[bot]) Bump maven-invoker-plugin from 3.3.0 to 3.4.0 #272 (@dependabot[bot]) Bump tomcat-jdbc from 10.1.2 to 10.1.4 #271 (@dependabot[bot]) Closed issues: Liquibase percona extension (URL) no longer available #275
December 9, 2022	4.18.0	4.18.0 (2022-12-09) Support for Liquibase 4.18.0. Fixed bugs: Fix percona toolkit download script #269 (@adangel) Dependency updates: Bump Percona Toolkit from 3.4.0 to 3.5.0 #270 (@adangel) Bump liquibase-core from 4.17.1 to 4.18.0 #268 (@dependabot[bot]) Bump mariadb-java-client from 3.0.9 to 3.1.0 #267 (@dependabot[bot]) Bump tomcat-jdbc from 10.1.1 to 10.1.2 #266 (@dependabot[bot]) Bump mariadb-java-client from 3.0.8 to 3.0.9 #265 (@dependabot[bot]) Bump spotbugs-maven-plugin from 4.7.2.1 to 4.7.3.0 #264 (@dependabot[bot]) Merged pull requests: [ci] Fix deprecated set-output GitHub Action command #262 (@adangel)
October 27, 2022	4.17.1	4.17.1 (2022-10-27) Support for Liquibase 4.17.1. Dependency updates: Bump liquibase-core from 4.17.0 to 4.17.1 #259 (@dependabot[bot]) Bump actions/setup-java from 2 to 3 #257 (@dependabot[bot]) Bump actions/download-artifact from 2 to 3 #256 (@dependabot[bot]) Bump actions/upload-artifact from 2 to 3 #255 (@dependabot[bot]) Bump tomcat-jdbc from 10.1.0 to 10.1.1 #254 (@dependabot[bot]) Merged pull requests: Install libdbd-mysql-perl with apt #258 (@adangel)
October 11, 2022	4.17.0	4.17.0 (2022-10-11) Support for Liquibase 4.17.0. Dependency updates: Bump liquibase-core from 4.16.0 to 4.17.0 #253 (@dependabot[bot]) Bump spotbugs-maven-plugin from 4.7.2.0 to 4.7.2.1 #252 (@dependabot[bot]) Bump tomcat-jdbc from 10.0.23 to 10.1.0 #251 (@dependabot[bot]) Bump snakeyaml from 1.32 to 1.33 #250 (@dependabot[bot]) Bump mariadb-java-client from 3.0.7 to 3.0.8 #249 (@dependabot[bot]) Bump junit-jupiter from 5.9.0 to 5.9.1 #248 (@dependabot[bot]) Bump maven-jar-plugin from 3.2.2 to 3.3.0 #246 (@dependabot[bot])
September 13, 2022	4.16.0	4.16.0 (2022-09-13) Support for Liquibase 4.16.0. Dependency updates: Bump snakeyaml from 1.31 to 1.32 #243 (@dependabot[bot]) Bump liquibase-core from 4.15.0 to 4.16.0 #242 (@dependabot[bot]) Bump spotbugs-maven-plugin from 4.7.1.1 to 4.7.2.0 #241 (@dependabot[bot]) Bump maven-pmd-plugin from 3.18.0 to 3.19.0 #240 (@dependabot[bot]) Bump snakeyaml from 1.30 to 1.31 #239 (@dependabot[bot]) Bump maven-pmd-plugin from 3.17.0 to 3.18.0 #238 (@dependabot[bot]) Merged pull requests: Remove integration tests for older liquibase versions #244 (@adangel)
August 23, 2022	4.15.0	Support for Liquibase 4.15.0. Dependency updates: Bump maven-javadoc-plugin from 3.4.0 to 3.4.1 #237 (@dependabot[bot]) Bump liquibase-core from 4.14.0 to 4.15.0 #236 (@dependabot[bot]) Bump mariadb-java-client from 3.0.6 to 3.0.7 #235 (@dependabot[bot]) Bump docker-maven-plugin from 0.40.1 to 0.40.2 #234 (@dependabot[bot]) Bump junit-jupiter from 5.8.2 to 5.9.0 #233 (@dependabot[bot])
July 26, 2022	4.14.0	Support for Liquibase 4.14.0. Dependency updates: Bump maven-resources-plugin from 3.2.0 to 3.3.0 #232 (@dependabot[bot]) Bump tomcat-jdbc from 10.0.22 to 10.0.23 #231 (@dependabot[bot]) Bump liquibase-core from 4.13.0 to 4.14.0 #230 (@dependabot[bot]) Bump spotbugs-maven-plugin from 4.7.1.0 to 4.7.1.1 #229 (@dependabot[bot]) Bump mysql-connector-java from 8.0.29 to 8.0.30 #228 (@dependabot[bot]) Bump maven-deploy-plugin from 3.0.0-M2 to 3.0.0 #227 (@dependabot[bot])
July 16, 2022	4.13.0	Support for Liquibase 4.13.0. Dependency updates: Bump Percona Toolkit from 3.3.1 to 3.4.0 (`4256c16`) Bump mariadb-java-client from 2.7.5 to 2.7.6 (`aae6892`) Bump exec-maven-plugin from 3.0.0 to 3.1.0 #224 (@dependabot[bot]) Bump liquibase-core from 4.12.0 to 4.13.0 #223 (@dependabot[bot]) Bump spotbugs-maven-plugin from 4.7.0.0 to 4.7.1.0 #222 (@dependabot[bot]) Bump mariadb-java-client from 3.0.5 to 3.0.6 #221 (@dependabot[bot])
June 23, 2022	4.12.0	Support for Liquibase 4.12.0. Implemented enhancements: Add version info to manifest #212 (@adangel) Dependency updates: Bump maven from 3.8.5 to 3.8.6 #220 (@adangel) Bump liquibase-core from 4.11.0 to 4.12.0 #219 (@dependabot[bot]) Bump tomcat-jdbc from 10.0.21 to 10.0.22 #218 (@dependabot[bot]) Bump docker-maven-plugin from 0.40.0 to 0.40.1 #217 (@dependabot[bot]) Bump maven-enforcer-plugin from 3.0.0 to 3.1.0 #216 (@dependabot[bot]) Bump maven-pmd-plugin from 3.16.0 to 3.17.0 #215 (@dependabot[bot]) Bump docker-maven-plugin from 0.39.1 to 0.40.0 #214 (@dependabot[bot]) Bump maven-invoker-plugin from 3.2.2 to 3.3.0 #213 (@dependabot[bot])
May 27, 2022	4.11.0	Support for Liquibase 4.11.0 Dependency updates: Bump tomcat-jdbc from 10.0.20 to 10.0.21 #207 (@dependabot[bot]) Bump spotbugs-maven-plugin from 4.6.0.0 to 4.7.0.0 #208 (@dependabot[bot]) Bump liquibase-core from 4.10.0 to 4.11.0 #209 (@dependabot[bot]) Bump mariadb-java-client from 3.0.4 to 3.0.5 #210 (@dependabot[bot])
May 6, 2022	4.10.0	Support for Liquibase 4.10.0 Implemented enhancements: Use github_changelog_generator #205 (@adangel) Dependency updates: Bump liquibase-core from 4.9.1 to 4.10.0 #204 (@dependabot[bot]) Bump mysql-connector-java from 8.0.28 to 8.0.29 #203 (@dependabot[bot]) Bump nexus-staging-maven-plugin from 1.6.12 to 1.6.13 #202 (@dependabot[bot]) Bump maven-javadoc-plugin from 3.3.2 to 3.4.0 #201 (@dependabot[bot]) Bump tomcat-jdbc from 10.0.18 to 10.0.20 #200 (@dependabot[bot])
March 31, 2022	4.9.1	Support for Liquibase 4.9.1. PR #180: Added support for MariaDB Connector 3.x.
March 18, 2022	4.9.0	Support for Liquibase 4.9.0.
February 24, 2022	4.8.0	Support for Liquibase 4.8.0. PR #182: Added masking for slave password - andreiMambu #183: The parameter --slave-password is not masked in logs
January 27, 2022	4.7.1	Support for Liquibase 4.7.1.
January 13, 2022	4.7.0	Support for Liquibase 4.7.0.
December 02, 2021	4.6.2	Support for Liquibase 4.6.2.
November 19, 2021	4.6.1.1	#148: Support createIndex with specifying index prefix length
November 06, 2021	4.6.1	Support for Liquibase 4.6.1.
October 04, 2021	4.5.0	Support for Liquibase 4.5.0.
August 12, 2021	4.4.3	Support for Liquibase 4.4.3.
July 23, 2021	4.4.2	Support for Liquibase 4.4.2.
July 18, 2021	4.4.1	Support for Liquibase 4.4.1. #122: Add docker image with liquibase, liquibase-percona and percona toolkit
June 20, 2021	4.4.0	Support for Liquibase 4.4.0. PR #112: Fixing typos - Jasper Vandemalle #106: MySQL connection times out after pt-online-schema-change run #118: Use catalogName instead of schemaName
May 24, 2021	4.3.5	Support for Liquibase 4.3.5.
April 28, 2021	4.3.4	Support for Liquibase 4.3.4.
April 23, 2021	4.3.3	Support for Liquibase 4.3.3.
March 26, 2021	4.3.2	#60: Add support for MariaDB JConnector #85: liquibase-percona 4.3.1 is not reproducible anymore #88: Support for Liquibase 4.3.2
February 23, 2021	4.3.1	The maven coordinates have changed. This extension is now available like the other liquibase extensions in the group `org.liquibase.ext`. In order to add this extension, use the following snippet: `<dependency> <groupId>org.liquibase.ext</groupId> <artifactId>liquibase-percona</artifactId> <version>4.3.1</version> </dependency>` #66: Change maven coordinates to be org.liquibase.ext #74: Update Liquibase to 4.3.0 Support for Liquibase 4.3.1 Alignment with existing release process
February 04, 2021	2.0.0	The minimum Java runtime version is now Java 1.8. Liquibase 4+ is supported. Support for older liquibase versions has been dropped. The XML namespace for this extension is now "http://www.liquibase.org/xml/ns/dbchangelog-ext/liquibase-percona". This only is affecting you, if you use the UsePercona flag. There is now also a XSD schema available, if you want to validate your XML changeset: https://raw.githubusercontent.com/liquibase/liquibase-percona/liquibase-percona-2.0.0/src/main/resources/dbchangelog-ext-liquibase-percona.xsd See the file test-changelog.xml for an example. Note: Usage of the schema is optional. In order to use the custom flags provided by this extension, you only need to declare the namespace. The checksum calculation for changes that used UsePercona flag changed. You might need to recreate the changelog entries for these changes with the clearCheckSums command. See #64 for the explanation. Fixed #56: Support liquibase 4.x Fixed #57: Support perconaOptions per change Fixed #64: Different changeset checksums with and without liquibase-percona Fixed #65: Make build reproducible
January 28, 2021	1.7.1	Fixed #58: Update versions (liquibase, percona-toolkit, mysql)
July 04, 2020	1.7.0	Fixed #35: Add support for AddPrimaryKeyChange Fixed #37: Using quotes for liquibase.percona.options doesn't always work Fixed #53: Update to support latest liquibase 3.10.1 Fixed #54: Update mysql-connector-java to 8.0.20 Fixed #55: Update percona toolkit to 3.2.0
April 20, 2019	1.6.0	The minimum Java runtime version is now Java 1.7. The system property `liquibase.percona.options` uses now a default value of `--alter-foreign-keys-method=auto --nocheck-unique-key-change`. These two options are not added by default anymore when pt-osc is executed. They are added now via the additional options system property. In case you have overridden this system property, make sure, to add these options as well, if you need them. Fixed #29: Allow to override --nocheck-unique-key-changes and --alter-foreign-keys-method=auto Fixed #30: Update liquibase
April 14, 2019	1.5.2	Fixed #28: Strange behavior when liquibase.percona.defaultOn is false
November 10, 2018	1.5.1	Fixed #26: Stack Overflow using defaultOn=false System Property PR #27: fix a typo - kennethinsnow
September 30, 2018	1.5.0	`pt-online-schema-change` is executed now with the option `--nocheck-unique-key-change`. This enables to add unique indexes, but can cause data loss, since duplicated rows are ignored. See Percona Toolkit Documentation for more information. The plugin is only compatible with version 3.0.12 or later of Percona Toolkit. Upgraded liquibase to 3.5.5 Verified compatibility to liquibase 3.6.2 Fixed #14: Rollback of foreign key constraint changing constraint names problem Fixed #15: Unique key constraint cannot be added Fixed #20: Support "UsePercona flag" in XML changelogs Fixed #22: Cross database bug
September 27, 2018	1.4.1	Fixed #16: Failing test PerconaAddForeignKeyConstraintChangeTest Fixed #17: Include Percona Toolkit into integration test Fixed #18: Use spotbugs instead of findbugs Fixed #19: Upgrade liquibase to 3.5.4 Fixed #21: Couldn't determine password: JdbcConnection is unsupported: dbcp.PoolingDataSource$PoolGuardConnectionWrapper Fixed #23: Add support for dbcp2 Added new system property `liquibase.percona.path` to specify the path where Percona Toolkit is installed.
July 21, 2017	1.4.0	Fixed #13: Use default liquibase.properties as fallback
July 21, 2017	1.3.1	Fixed #12: Cannot run migrations with the percona extension on a Spring Boot app with embedded Tomcat
December 18, 2016	1.3.0	Upgraded liquibase to 3.5.3 Support for MySQL Connector 6.0.x in addition to 5.1.x. Fixed #7: Foreign key constraints of AddColumn is ignored Fixed #8: Support addForeignKeyConstraintChange, addUniqueConstraintChange Fixed #9: Support for enabling pt-online-schema-changes on a per-change basis Fixed #10: Build fails with java7: UnsupportedClassVersion when running DatabaseConnectionUtilTest.testGetPasswordMySQL_6
September 13, 2016	1.2.1	PR #4: Allow passing additional command line options to pt-online-schema-change PR #5: Support afterColum attribute
April 2, 2016	1.2.0	Fixed #2: Adding indexes via pt-online-schema-change Fixed #3: Altering column data types via pt-online-schema-change Added configuration property "liquibase.percona.skipChanges" Upgraded liquibase to 3.4.2
July 26, 2015	1.1.1	Fixed #1: Tables with foreign keys
November 6, 2014	1.1.0	compatible with liquibase 3.3.0
October 19, 2014	1.0.0	compatible with liquibase 3.2.x

Liquibase Extensions

Percona Online Schema Change

Overview

Readme

Supported Databases

Supported Changeset Formats

Liquibase version(s) tested against

Supported Changes and examples

AddColumn

AddForeignKeyConstraint

AddPrimaryKey

AddUniqueConstraint

CreateIndex

DropColumn

DropForeignKeyConstraint

DropUniqueConstraint

DropIndex

ModifyDataType

Sql

Configuration

UsePercona flag

PerconaOptions flag

Liquibase Percona extension XSD

System Properties

Using / Installing the extension

Download

Command line liquibase

Via maven

Docker

Using snapshots

Notes

Building this extension

Integration testing

Common Problems

NoSuchMethodError: PerconaDropColumnChange.getColumns()Ljava/util/List

References

Old Versions and Release Notes