Maven registerChangeLog

registerChangeLog connects your local Liquibase activity to a specific Liquibase Hub Project. By registering your changelog, this activity will be visible only to one Project within one Organization in Liquibase Hub.

Uses

Use the registerChangeLog goal to connect an XML, SQL, JSON, or YAML changelog to your Liquibase Hub Project.

Note: JSON and YAML changelog formats are available in Liquibase 4.2.1 and later versions.

The goal assigns the changeLogId to the changelog file that you register. The changeLogId is a unique identifier in your changelog, which is automatically added by the registerChangeLog goal to provide real-time monitoring and reports.

Tip: Process and synchronize your source and target resources to ensure you use your newly registered changelog to report operations to Liquibase Hub.

You can connect the needed changelog file with your existing project or create a new project.

Note: If you follow a root changelog structure, register only the root changelog without registering the nested changelogs.

Maven configuration

Liquibase Maven can be configured in multiple ways. One way is to define your Liquibase configuration properties in your pom.xml file. To configure your pom.xml file, refer to Configuring Liquibase Attributes in your Maven POM File.

There is also a list of the Liquibase Hub properties you can specify in your pom.xml file under <configuration> in the <project></project> level:

<!-- Hub Mode -->
<!--hub.apiKey>HUB API KEY</hub.apiKey>
<hubMode>all|meta|off</hubMode>
<hubConnectionId>TARGET ID</hubConnectionId>
<hubProjectId>PROJECT ID</hubProjectId-->

Running the registerChangeLog Maven goal

Running the registerChangeLog goal requires a Maven project to be implemented.

Also, the following items are required:

  • The Liquibase Hub API Key

    • There are three ways to specify your API Key:

    • Including liquibase.hub.ApiKey value in the Liquibase properties file, as follows:
      • liquibase.hub.ApiKey: <addYourHubApiKeyHere>
    • Including liquibase.hub.apiKey value in the pom.xml file:
      • <liquibase.hub.apiKey>HUB API KEY</liquibase.hub.apiKey>
    • Passing liquibaseHubApiKey on the command line:
      • --liquibaseHubApiKey=addYourHubApiKeyHere
    • Specifying API key in your JAVA_OPTS Environment Variable as -Dliquibase.hub.apiKey:
      • On Linux or MacOS: JAVA_OPTS="-Dliquibase.hub.apiKey=<myapikey>"
      • On Windows: set JAVA_OPTS="-Dliquibase.hub.apiKey=<myapikey>"

      • Note: To retrieve or manage your API keys, go to Settings > API Keys by selecting the settings icon on the left side of the page.

  • The changelog file

    • Note: Add the changelog file to pom.xml or the Liquibase properties file, or specify it as the -Dliquibase.changeLogFile attribute while running the goal.

  • The hubProjectId of the Project with which you want to associate your changelog:

    • Note: As registerChangeLog is non-interactive, you cannot select the project from the command line for Maven. For this reason, you need to provide the hubProjectId to run the goal. You can find the hubProjectId in Projects > View Details for the required project > Operations or any other tab of the project. Specify the hubProjectId in the Maven pom.xml file or the Liquibase properties file.

    Tip: To create a Project from Liquibase Hub, select Projects > + Create Project.

<!--liquibase.hubProjectId>PROJECT ID</liquibase.hubProjectId->
hubProjectId: <addYourHubProjectId>

Additionally, you can set the level of data to send to Liquibase Hub in JAVA_OPTS as -Dliquibase.hub.apiKey, or in the Liquibase properties file, as follows:

liquibase.hub.mode:[all|meta|off]
  • all sends all data, including the changeset body, generated SQL, and logs (the default value is all).
  • meta does not send the changeset body, generated SQL, or operation-event and change-event logs. This mode sends the changeset name, author, id, timestamps, Liquibase version, and others.
  • off sends no data to Liquibase Hub.

To run the goal, type the following in your command line:

mvn liquibase:registerChangeLog

Output

When successful, the registerChangeLog Maven goal produces the following output:

Starting Liquibase at 11:35:54 (version 4.0.1-DAT-5252-SNAPSHOT #7 built at 2020-09-08 17:40+0000)
[INFO] Executing on Database: jdbc:oracle:thin:@//localhost:1522/BUCKET_01
Sep 11, 2020 11:35:55 AM liquibase.hub
INFO: Connected to Liquibase Hub with an API Key 'cTMOXZ************'
Changelog file 'src/main/resources/com/example/changelog001.h2.sql' has been registered with changelog ID 'da8567ba-f89c-4e13-a046-c06fcec2a333' and connected to project 'erz's Project' with project ID '752a7a64-c337-4438-a4cd-edc30c2c5ff7'
[INFO] ------------------------------------------------------------------------
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  6.445 s
[INFO] Finished at: 2020-09-11T11:35:56-05:00
[INFO] ------------------------------------------------------------------------

registerChangeLog required Maven configuration properties

Property Definition
hubProjectId Specifies the project you want to associate your changelog with.