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.



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. For more information, see How Liquibase Finds Files: Liquibase 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.

You can set these parameters in four ways:

  • In the Liquibase properties file
  • As command parameters in the CLI
  • As JVM system properties
  • As environment variables (Liquibase Pro)

Liquibase properties file

In Liquibase 4.1+, add the following to the Liquibase properties file:

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

CLI command parameters

In your command line, use a command parameter with a single Liquibase command:

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

Java system property

In your command line, use the JAVA_OPTS Environment Variable to set a JVM 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 JAVA_OPTS, add && liquibase <command> to the end of your input.

Environment variable (Liquibase Pro)

In Liquibase Pro, set an environment variable:

Mac/Linux syntax:


Windows syntax:


Note: These environment variable commands only apply to the current shell. If you need to pass an environment variable to a child process without affecting the parent process, you can use the export command on Mac/Linux or the setx command on Windows.

Related links