liquibase.change.Change implementations define what logic can be called from
changeSet blocks in changelog files.
Think of them as higher-level functions that shield users from needing to know the details of what it takes to perform a change.
Liquibase ships with a large number of standard changes such as:
but extensions can provide any functionality desired.
Each Change generates a series of SqlStatements from the given input arguments.
sequenceDiagram Calling Code->>ChangelogParser: Parse changelog file ChangelogParser-->>Calling Code: Returns DatabaseChangeLog including Change instances Calling Code->>Change: generateStatement Change-->>Calling Code: Returns SqlStatement Calling Code->>SqlGeneratorFactory: Get actual SQL for SqlStatements Calling Code->>Database: Execute generated SQL
Change instances define what "change functions" are available to the end-user and the arguments they take.
They should only deal with database-agnostic
SqlStatement and not directly interact with the database.
See the SqlGenerator API for more information on SqlStatements and SqlGenerators.
Change has a "name", and the ChangeLogParser selects the correct implementation by matching the name in the changelog file with the names defined by Change implementations.
To determine which
Change to use, Liquibase will find all the implementations that use the given name and choose the one with the highest priority.
This allows extensions to either define a new Change OR override an existing Change with a given name.
Changes are dynamically discovered, so must have a no-arg constructor and be registered in
Returns an array of liquibase.statement.SqlStatement
which describes the steps to perform against the database when this change is run during an
Returns the message to output when this change executes successfully.
The AbstractChange base class's
createChangeMetaData() method will configure the Change's metadata based on a liquibase.change.DatabaseChange annotation
on the Change class.
This annotation is required, and requires the following attributes to be set:
nameis the name used in the changelog file. Example:
priorityis used as other priority values to control which Change implementation for a given name should be used. If unsure, use
descriptiongives a human-readable description of what the change does
Define Configuration Attributes
If a Change requires custom attributes to be set (tableName, etc.), create get/set methods for them.
The AbstractChange base class's
createChangeMetaData() method will find all get/set method pairs and expose them as attributes on the change.
To control the metadata, methods can be given the liquibase.change.DatabaseChangeProperty annotation. This annotation can be used to control the name, mark a get/set method as not actually a property, and more.
Define Rollback Logic
Change implementations can override
generateRollbackStatements() to provide auto-rollback support.
createInverse method specifies rollback by defining it as another Change instance, while
generateRollbackStatements returns SqlStatement objects to rollback. Only one or the other method needs to be implemented.
If this method is not overridden, users must specify the rollback logic themselves in their changelog file.
The complete javadocs for
liquibase.change.Change is available at https://javadocs.liquibase.com
The following guides provide relevant examples:
Created: March 14, 2023