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.
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)
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.
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.
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:
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
The jar files can be downloaded manually from maven:
After extracting the zip file of liquibase, place liquibase-percona-4.7.0.jar file in the sub directory lib. The shell script liquibase / liquibase.bat will automatically pick this up and the extension is available.
Add the following dependency to the liquibase plugin:
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-changecannot 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.
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
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
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