changelog-sync-to-tag
Task
The changelog-sync-to-tag
task marks all undeployed changesets from your changelog up to the specified tag as executed in your database. The task also marks the changeset with that tag as deployed.
Note: If you don't have any tag specified in your changelog file, add it by using the tagDatabase Change Type as follows:
<changeSet id="13.1" author="liquibase">
<tagDatabase tag="version_2.0"/>
</changeSet>
Uses
The changelog-sync-to-tag
task is typically used when you want to baseline a new database environment with specific objects. An example use case for the changelog-sync-to-tag
task is the following:
- You have a DEV environment with a set of objects used only in DEV, and you want to use the same changelog to manage a new TEST environment. The TEST environment does not have those DEV-only objects and needs only some of them.
- To deploy the needed DEV-only objects and avoid deploying the rest, you add a tag and run the
changelog-sync-to-tag
task to mark the changes related to that tag as executed in the DATABASECHANGELOG table. - The task marks all changesets starting with the first changeset at the top of the DEV changelog file and moving down to the changesets up to and including the tag.
- Next, you deploy the changesets that were not marked as deployed in your database. Liquibase treats your DEV and TEST databases as equivalent.
Note: If you want to mark all undeployed changes from the changelog file as executed in your database, use the changelog-sync Task.
You can also use the changelog-sync-to-tag
task to mark the change associated with a specific tag as executed if the object associated with the change was created manually on the database. By marking the changeset as executed, it prevents the next Liquibase update from failing as it tries to create an object that already exists.
Running the changelog-sync-to-tag
task
To execute the changelog-sync-to-tag
task, include the following values in your Ant default file, which can be build.xml
:
<project name="Example" xmlns:liquibase="antlib:liquibase.integration.ant">
<taskdef resource="liquibase/integration/ant/antlib.xml" uri="antlib:liquibase.integration.ant">
<classpath path="path/to/liquibase/libs"/>
</taskdef>
</project>
<property name="db.changelog.file" value="oracle_lbpro_master_changelog.xml" />
<target name="changelog-sync-to-tag" depends="prepare">
<liquibase:database id="my-database" driver="${driver.classname}" url="${jdbc.url}" user="${username}" password="${password}"/>
<liquibase:changelog-sync-to-tag databaseref="my-database" changelog-file="com/example/oracle_lbpro_master_changelog.xml"
labels="mylabels"
toTag="version_1.1"
classpathref="classpath"/>
</target>
This example will sync the referenced database with the changesets found in the changelog file up to and including the tag changeset.
Next, run the following in the CLI to implement the task and update your database:
ant -f build.xml changelog-sync-to-tag
Note: It is important to type the task name in the command prompt exactly like you specify it in the target name of your build.xml
file. Ant uses the task name to determine which Liquibase command it will run.
Attributes
Attribute | Description | Required |
---|---|---|
changelog-file
|
The changelog file to run. | Yes |
toTag
|
The attribute that syncs the changesets up to and including the tag. | Yes |
contexts
|
A comma-separated list of Contexts to execute. If not specified, all contexts are run. | No |
output-file
|
The file where Liquibase will save the update SQL statements rather than executing them in the database. | No |
outputEncoding
|
The character encoding to use when writing SQL statements to output file. | No. Defaults to system encoding. |
promptOnNonLocalDatabase
|
A dialog box that will send you a warn message if set to true and you attempt to run Liquibase against a database that is not on localhost. | No. The default value is set to false. |
classpathref
|
A reference to the classpath used to run the task. | No |
databaseref
|
A reference to the database to which the Liquibase will connect. | Yes, unless a nested <database> element is present. |
driver
|
Deprecated: The name of the database driver with which you connect. | No |
url
|
Deprecated: Use the database url attribute instead. The database URL. |
No |
username
|
Deprecated: The database username with which you connect. | No |
password
|
Deprecated: The password to use when connecting to the database. | No |
defaultSchemaName
|
Deprecated: The schema to use by default for managed database objects and Liquibase control tables. | No |
currentDateTimeFunction
|
Deprecated: Overrides the current date time function used in SQL. Useful for unsupported databases. | No |
databaseChangeLogTableName
|
Deprecated: Overrides the name of the DATABASECHANGELOG table to use. | No |
databaseChangeLogLockTableName
|
Deprecated: Overrides the name of the DATABASECHANGELOGLOCK table to use. | No |
log-level
|
Deprecated: Specifies one of the following logging levels: debug, info, warning, severe, off. The default level is info. | No |
Attributes specified as nested elements
Attribute | Description | Required |
---|---|---|
classpath
|
The classpath used to run the task. | Optional |
database
|
See database data type for more information. | Required unless a databaseref attribute is given. |
changelogparameters
|
See changelog Property Substitution for more information. | Optional |