The registerChangeLog command 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.


The registerChangeLog command is used to connect an XML or formatted SQL changelog to your Liquibase Hub Project. Also, you can use JSON and YAML changelog formats (since 4.2.1).

The command also 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 command to provide real-time monitoring and reports.

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

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

Running the registerChangeLog command

To run the registerChangeLog command, you can specify your driver, classpath, URL, and user authentication information in your file. For more information, see Creating and configuring a file. You can also specify these properties in your command line.

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 file:
    • liquibase.hub.ApiKey: <addYourHubApiKeyHere>
    • 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
  • Add your changelog file to the file or specify it as the --changeLogFile attribute while running the command.

    Next, run the registerChangeLog command:

    liquibase registerChangeLog

Non-interactive registerChangeLog

To run the registerChangeLog in the non-interactive mode, specify the --hubProjectId, which is located in Projects.

If you specify both changelog and hubProjectId, the command will register the changelog to the specified project without showing the interactive prompt:

liquibase --changeLogFile=mychangelog.xml registerChangeLog --hubProjectId=myProjectId

If you want to run the Maven registerChangeLog goal, you must use the non-interactive version of the goal. This means that in addition to the changeLogFile and hubApiKey, you need to specify the hubProjectId of an existing or new Liquibase Hub Project in your Maven pom.xml. Also, as you cannot create a new project in Maven, create a Liquibase Hub Project with the CLI before registering a changelog with Maven.

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