Getting Started with Liquibase Hub

Liquibase Hub is a secure portal that provides the real-time monitoring, reports, organization, and insights into your team's database release automation. It provides centralized visibility into distributed Liquibase operations performed against the multiple environments.

The Liquibase CLI app sends information to the Liquibase Hub portal when you run the commands that make changes to your database. For example, update, changeLogSync, rollback, or dropAll.

To set up your account, follow these steps:

Step 1: Sign up for an account

  1. Go to the Liquibase Hub portal.
  2. Sign up for an account.
  3. Check your email and follow the link to activate an account.

Step 2: Add a Liquibase Hub API key to the liquibase.properties file

  1. Sign in to your Liquibase Hub account and go to Settings > API Keys by selecting the settings icon on the left side of the page.
  2. Copy the API key, which connects the information generated by your changelogs and other operations to your Liquibase Hub Projects. The API key is a new concept for organizing your Liquibase work, and it is unique for each Liquibase Hub user. Liquibase Hub will only be in sync with your actions if the API key is added.
  3. Add your API key to the liquibase.properties file as follows: liquibase.hub.ApiKey: <addYourHubApiKeyHere>.
# liquibase.properties
changeLogFile: ../path/to/file/dbchangelog.xml
driver: oracle.jdbc.OracleDriver
url: jdbc:oracle:thing:@192.168.0.22:1521/orcl
username: PRO
password: password
referenceDriver: oracle.jdbc.oracleDriver
referenceurl: jdbc:oracle:thin:@192.168.0.22:1521/orcl
referencePassword: password
liquibaseProLicenseKey: <addYourProKeyHere>
classpath: ../path/to/file/ojdbc6-11.2.0.3.0.jar
# Add Your First Liquibase Hub API Key
liquibase.hub.ApiKey: <addYourHubApiKeyHere>

Note: Alternatively, you can pass your API key as a runtime argument and run your commands as usual or you can specify it in your JAVA_OPTS as -Dliquibase.hub.apiKey. To specify JAVA_OPTS on Windows, Linux, or MacOS, run SET JAVA_OPTS=”-Dliquibase.hub.apikey”. It is a best practice to add the API key to the liquibase.properties file or your build files instead of entering it manually every time.

java -jar liquibase.jar \
--driver=oracle.jdbc.Oracleoriver \
--classpath=../path/to/file/ojdbc6-11.2.0.3.0.jar \
--changeLogFile=com/example/db.changelog.xml \
--url="jdbc:oracle:thing:@192.168.0.22:1521/orcl" \
--username=scott \
--password=tiger \
--liquibaseProLicenseKey=aeioufakekey32aeioufakekey786463214\
--liquibaseHubApiKey=8fgvQ3ajW4uDTYKfgMFyJw7WZAUV1XPsjdbrbvP1rA0\
update

You can also set the level of data you want to send to Liquibase Hub but this process is optional:

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

Step 3: Run the registerChangeLog command

  1. Run the registerChangeLog command to connect an XML or formatted SQL changelog to a specific Liquibase Hub Project. Liquibase Hub relies on a new unique identifier in your changelog called changeLogId, which is automatically added by the registerChangeLog command to provide insights, real-time monitoring, and reports.

Note: Register only the master changelog without registering the nested changelogs, if you use this best-practices changelog structure. You can register a changelog to an existing project or create a new one from the CLI as well.

  1. Once the changelogId identifier is added to your changelog, ensure to commit the changelog to source control, so all team members' changes are recorded in Liquibase Hub.

Step 4: Run your regular commands

Now, just use Liquibase Community or Liquibase Pro, and Liquibase Hub will track the following commands:

Each command will automatically synchronize the local DATABASECHANGELOG table with the Liquibase Hub's database, but you can invoke this synchronization manually by using the new syncHub command.

So long as you have a registered changelog, a valid Liquibase Hub API key, and hub.mode=[all|meta], you can use Liquibase Hub to see what changesets passed and what failed in your update, rollback, or changelogsync operations. You can see these Operation reports filtered to a specific Project, database connection, or by dates and users.

See also