Skip to content
Star Us On GitHub

Implementing a Custom ChangeExecListener Class with Liquibase

ChangeExecListener is a Java listener interface Liquibase calls when you use a rollback or update command to modify your database.

When Liquibase calls ChangeExecListener with one of these commands, it also runs several corresponding methods the class implements. For example, when you use rollback to revert a change in your database, Liquibase calls the rolledBack method.

You can use the default implementation of ChangeExecListener in Liquibase or write your own Java class to override the default.

Commands

Uses

You can use a custom ChangeExecListener class to:

  • Provide richer logging to external tools you use with Liquibase.
  • Verify what Liquibase runs or rolls back based on your custom business logic.
  • Improve the user interface "status reports" of custom Liquibase integrations.
  • Make audits of your database or notify you when Liquibase makes an important change.
  • Record database statistics like the duration of commands you run, which SQL statements you used, and which rows of a table your change affected.
  • Write Preconditions to an output file as they are executed.

Creating a custom ChangeExecListener class

  1. Create a Java class that extends AbstractChangeExecListener. This is an abstract class that extends ChangeExecListener, so they have the same methods. However, because it's abstract, you only have to override the methods you care about. By contrast, if you extend ChangeExecListener directly, you must write definitions for every method, even if you don't want to change their functionality.

  2. After you write your class, compile it into a JAR file in your command line:

    jar cf CustomChangeExecListener.jar CustomChangeExecListener.class

  3. Move your JAR file to the liquibase/lib directory, or add it to the classpath.

  4. Call on your CustomChangeExecListener class in Liquibase by using the change-exec-listener-class parameter.

Setting the --change-exec-listener-class and --change-exec-listener-properties-file parameters

You can configure your ChangeExecListener by using the following command parameters of rollback and update commands:

  • --change-exec-listener-class is a string that determines what class Liquibase uses for ChangeExecListener.
  • --change-exec-listener-properties-file is a string that determines the path to the properties file Liquibase uses for ChangeExecListener.

For more information, see ChangeExecListenerCommandStep.

Liquibase properties file

liquibase.command.changeExecListenerClass: YOUR_CLASS
liquibase.command.changeExecListenerPropertiesFile: YOUR_FILE

CLI command parameters

liquibase update --change-exec-listener-class=YOUR_CLASS --change-exec-listener-properties-file=YOUR_FILE --changelog-file=dbchangelog.xml

Java system property

Mac/Linux syntax:

JAVA_OPTS=-Dliquibase.command.changeExecListenerClass=YOUR_CLASS -Dliquibase.command.changeExecListenerPropertiesFile=YOUR_FILE && liquibase update --changelog-file=dbchangelog.xml

Windows syntax:

set JAVA_OPTS=-Dliquibase.command.changeExecListenerClass=YOUR_CLASS -Dliquibase.command>changeExecListenerPropertiesFile=YOUR_FILE && liquibase update --changelog-file=dbchangelog.xml

Note

To use a Liquibase command alongside the JAVA_OPTS Environment Variable, add && liquibase <command> to the end of your input.

Environment variable

Mac/Linux syntax:

LIQUIBASE_COMMAND_CHANGE_EXEC_LISTENER_CLASS=YOUR_CLASS
LIQUIBASE_COMMAND_CHANGE_EXEC_LISTENER_PROPERTIES_FILE=YOUR_FILE

Windows syntax:

set LIQUIBASE_COMMAND_CHANGE_EXEC_LISTENER_CLASS=YOUR_CLASS
set LIQUIBASE_COMMAND_CHANGE_EXEC_LISTENER_PROPERTIES_FILE=YOUR_FILE

Note

These commands only apply to the current shell. To set permanent environment variables, see Liquibase Environment Variables.