Your First Extension
This page will teach you the fundamental concepts for building extensions.
Liquibase extensions are built with Java, so you will likely want a Java-friendly IDE and a build tool like Maven or Gradle
For a starting Maven-based project, you can create a personal repository based on the example extension template.
The example extension defines:
- A new
clearPasswords
change type - A new
prefix
attribute forcreateTable
- A new
hasPasswordColumn
precondition
From the base directory, run mvn package
to build the extension as target/my-example-0.0.1.jar
.
Copy my-example-0.0.1.jar
to your LIQUIBASE_HOME/lib
directory and run the changelog found in the project
directory.
That will create a table called secure_user_table
, check that the password
column exists, and clear out any values in that column.
Let's make a "hello world" change type:
Create src/main/java/com/example/change/HelloWorldChange.java
as
package com.example.change;
import liquibase.change.AbstractChange;
import liquibase.change.ChangeMetaData;
import liquibase.change.DatabaseChange;
import liquibase.database.Database;
import liquibase.statement.SqlStatement;
import liquibase.statement.core.RawSqlStatement;
@DatabaseChange(name = "helloWorld", description = "Says hi", priority = ChangeMetaData.PRIORITY_DEFAULT)
public class HelloWorldChange extends AbstractChange {
@Override
public SqlStatement[] generateStatements(Database database) {
return new SqlStatement[] {
new RawSqlStatement("create table hello(world int)")
};
}
@Override
public String getConfirmationMessage() {
return "Said hello";
}
}
and add com.example.change.HelloWorldChange
to src/main/resources/META-INF/services/liquibase.change.Change
so it looks like:
com.example.change.ClearPasswordsChange
com.example.change.PrefixedCreateTableChange
com.example.change.HelloWorldChange
then rebuild with mvn package
and re-copy target/my-extension-0.0.1.jar
to LIQUIBASE_HOME/lib
.
Finally, add a new changeset to your changelog file like:
<changeSet id="4" author="example">
<ext:helloWorld/>
</changeSet>
and when you run liquibase update
you will now have a table named hello
with a column named world
.
Here are some ideas for things you can try:
- Change the name of the table created by
helloWorld
- Add a "dataType" parameter to
helloWorld
In the next topic, Extension Anatomy, we look closer at the source code of the helloWorld extension and explain key concepts.
Talk to us on the Liquibase Forum, Liquibase Discord, or
clone it at https://github.com/liquibase/liquibase.wiki.git
and create an issue with a patch file.