Maven `syncHub`

syncHub synchronizes the local DATABASECHANGELOG table with Liquibase Hub.

Uses

syncHub is typically used when you want to:

Ensure that Liquibase Hub shows the latest results from your DATABASECHANGELOG table.
Synchronize the DATABASECHANGELOG table of a new project that has pre-existing data in the DATABASECHANGELOG table.
Synchronize your local data if update, rollback, changelogSync, or dropAll were run while Liquibase Hub was offline.

When you run the syncHub goal, you will not see any operations added to the Project associated with your changelog. syncHub cannot associate previous Liquibase operations, so you will not see any operations in Liquibase Hub. You will only see changesets added to the changesets tab in your Liquibase Hub project.

Maven configuration

Liquibase Maven can be configured multiple ways. One way is to define your Liquibase configuration properties in your pom.xml file. You can also indicate the location of your liquibase.properties file using the following syntax:

<liquibase.propertyFile>path/to/properties_file</liquibase.propertyFile>

Note: Replace path/to/properties_file with the location of your default properties file. See the example below.

Example: <liquibase.propertyFile>${project.basedir}/local.liquibase.properties</liquibase.propertyFile>

Note: Multiple profiles can be created in the pom.xml which contain different Liquibase properties. See the example below.

There is also a list of the Liquibase Hub properties you can specify in the pom.xml file:

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

Example of a Maven pom.xml output

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                    
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.1.9.RELEASE</version>
    <relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.example</groupId>
<artifactId>liquibase-project</artifactId>
<version>05XII19</version>
    <profiles>
    <profile>
    <id>DEV</id>
    <properties>
                    
<liquibase.propertyFile>${project.basedir}/DEV.properties</liquibase.propertyFile>
    </properties>
</profile>
<profile>
    <id>QA</id>
    <properties>
                    
<liquibase.propertyFile>${project.basedir}/QA.properties</liquibase.propertyFile>
    </properties>
</profile>
<profile>
    <id>PROD</id>
    <properties>
                    
<liquibase.propertyFile>${project.basedir}/PROD.properties</liquibase.propertyFile>
    </properties>
</profile>
</profiles>
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>com.microsoft.sqlserver</groupId>
        <artifactId>mssql-jdbc</artifactId>
        <version>8.1.0.jre8-preview</version>
    </dependency>
    <!-- https://mvnrepository.com/artifact/com.oracle.jdbc/ojdbc6 -->
    <dependency>
        <groupId>com.oracle.jdbc</groupId>
        <artifactId>ojdbc8</artifactId>
        <version>19.3.0.0</version>
    </dependency>
</dependencies>
<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
            <plugin>
                <groupId>org.liquibase</groupId>
                <artifactId>liquibase-maven-plugin</artifactId>
                <version>3.8.9</version>

        <!--  <executions>
            <execution>
                <goals>
                    <goal>syncHub</goal>
                </goals>
                <phase>process-classes</phase>
            </execution>
        </executions>-->
    <dependencies>

 <!-- Hub Mode -->
 <liquibase.hub.apiKey>AddYourHubApiKey</liquibase.hub.apiKey>
 <!--liquibase.hubMode>all</liquibase.hubMode-->
 <!--liquibase.hubConnectionId>AddYourConnectionId</liquibase.hubConnectionId-->
						        
    <!--Pick ONLY ONE of the following database dependencies.  These are working examples for you to use to start with -->
        <dependency>
            <groupId>com.microsoft.sqlserver</groupId>
            <artifactId>mssql-jdbc</artifactId>
            <version>7.4.1.jre8</version>
        </dependency>
        <dependency>
            <groupId>postgresql</groupId>
            <artifactId>postgresql</artifactId>
            <version>9.1-901-1.jdbc4</version>
        </dependency>
        <dependency>
            <!--  How to add Oracle JDBC driver in your Maven local repository
            https://www.mkyong.com/maven/how-to-add-oracle-jdbc-driver-in-your-maven-local-repository/ -->
            <groupId>com.oracle</groupId>
            <artifactId>ojdbc7</artifactId>
            <version>4.1.3</version>
        </dependency>
    </dependencies>
</plugin>
</plugins>
</pluginManagement>
</build>
</project>

Running the `syncHub` Maven goal

Running the syncHub 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:

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 as -Dliquibase.hub.apiKey. To specify JAVA_OPTS on Windows, Linux, or MacOS, run 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 your changelog file to the pom.xml or liquibase.properties file or specify it as the -Dliquibase.changeLogFile attribute while running the goal.

The hubConnectionId attribute:
- If you enter the -Dliquibase.changeLogFile attribute, there is no need to specify hubConnectionId with the goal.
- If you use hubConnectionId, add it to the pom.xml file, the liquibase.properties file, or to the syncHub goal on the command line. You can find the hubConnectionId in Project > Connections > Connection in the lower-left corner.
- If you specify both the hubConnectionId and the changelog file, the changelog file will be ignored and the connection Id will be used.

<!--liquibase.hubConnectionId>CONNECTION ID</liquibase.hubConnectionId>
<hubConnectionId: <addYourHubConnectionId>
liquibase syncHub --hubConnectionId=myConnectionID

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

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.

Before running the syncHub goal, register your changelog file by using the registerChangeLog goal:

mvn liquibase:registerChangeLog

Note: The registerChangeLog goal connects your local Liquibase activity to a specific Liquibase Hub Project.

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

mvn liquibase:syncHub

Output

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

Starting Liquibase at 12:18:41 (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 12:18:42 PM liquibase.hub
INFO: Connected to Liquibase Hub with an API Key 'cTMOXZ************'
Sep 11, 2020 12:18:42 PM liquibase.changelog
INFO: Reading from DATABASECHANGELOG
[INFO] ------------------------------------------------------------------------
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  6.028 s
[INFO] Finished at: 2020-09-11T12:18:43-05:00
[INFO] ------------------------------------------------------------------------

`syncHub` optional Maven configuration properties

Property	Definition
hubConnectionId	Specifies the connection needed for the `syncHub` goal to synchronize the local DATABASECHANGELOG table with Liquibase Hub.

Maven syncHub