...
Panel | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
...
October 19, 2014 | 1.0.0 |
|
November 6, 2014 | 1.1.0 |
|
July 26, 2015 | 1.1.1 |
|
April 2, 2016 | 1.2.0 |
Attachments |
---|
Readme
Supported Databases
...
- Liquibase 3.2.0 (liquibase-percona 1.0.0)
- Liquibase 3.3.0 (liquibase-percona 1.1.1)
...
This changeset
...
- Liquibase 3.3.5 and 3.4.2 (liquibase-percona 1.2.0)
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>
will execute the following Corresponding command:
pt-online-schema-change --alter="ADD COLUMN address VARCHAR(255)" ...
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-foreign-keys-method=auto --host=127.0.0.1 --port=3306 --user=root --password=** --execute D=testdb,t=person="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" ...
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)" ...
Configuration
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 totrue
, then no such SQL statements will be output into the migration file.liquibase.percona.skipChanges
: comma separated list of changes. Default: . 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 toaddColumn,dropColumn
in order to not use percona for adding/dropping a column.
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
...
After extracting the zip file of liquibase, place liquibase-percona-1.12.10.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 your project's pom file:
...
the liquibase plugin:
<dependency>
<groupId>com.github.adangel.liquibase.ext</groupId>
<artifactId>liquibase-percona</artifactId>
<version>1.2.0</version>
</dependency>
Using snapshots
Snapshot builds contain the latest features which are not yet available in a release.
Enable the snapshot repository via Maven:
<project>
<repositories>
<repository>
<id>sonatype-nexus-snapshots</id>
<dependencies> <name>Sonatype Nexus <dependency>Snapshots</name>
<groupId>com.github.adangel.liquibase.ext</groupId><url>https://oss.sonatype.org/content/repositories/snapshots</url>
<releases>
<artifactId>liquibase-percona<<enabled>false</artifactId>enabled>
<!-- use 1.0.0 or 1.1.1 -->/releases>
<snapshots>
<version>1.1.1</version><enabled>true</enabled>
<scope>runtime<</scope>snapshots>
</dependency>repository>
</dependencies>repositories>
</project>
And just use the latest SNAPSHOT version for liquibase-percona dependency, e.g. 1.2.1-SNAPSHOT
:
<dependency>
<groupId>com.github.adangel.liquibase.ext</groupId>
<artifactId>liquibase-percona</artifactId>
<version>1.2.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 to 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 installverify
. You'll find the jar-file in the target/
subdirectory.
Integration testing
In order to execute the integration tests, run mvn clean install verify -Prun-its
.
Please note, that a MySQL server/Percona server is needed. you'll need:
- docker. During the pre-integration-test phase the official mysql image will be started.
- percona toolkit. The command line tools need to be available on your
PATH
.
See the properties config_... in pom.xml
for connection details for the mysql docker instance.
Common Problems
NoSuchMethodError: PerconaDropColumnChange.getColumns()Ljava/util/List
...