- Task
- Version ยท 6.0.2
- Your first governed database change
Your first governed database change
Last updated: November 17, 2026
In this walkthrough you assign a policy on Liquibase Secure server, run it against the H2 sandbox from the command line, and find the run recorded in the web app.
Nothing you do here reaches a real environment. This workspace uses sample data, and the database is the bundled H2 sandbox, so you can try the whole flow and throw it away afterwards.
Before you begin
You must have the Liquibase Secure license file (
.lic) your Liquibase account team sent you. The server installs from it.Docker must be running, with Docker Engine 24 or later and Docker Compose 2.20 or later. The server runs as a set of containers, and the installer stops if Docker is not running.
The machine must meet the Liquibase Secure server requirements, including Java 17 or later for Liquibase.
If you have not installed Liquibase yet, start with run Liquibase against the H2 sandbox. This walkthrough picks up from the project it leaves you with.
If you are setting the server up for your team rather than trying it out, follow Install Liquibase Secure server instead.
If your company already runs the server and you only want the web app, log in to Liquibase Secure server.
Procedure
Install the server
Download the liquibase-platform CLI archive for your platform, as in step 1 of Install Liquibase Secure server, and change into the folder you extracted. Then install the server on this machine with your license file. install creates the deployment directory and keeps the deployment's settings, secrets, and certificate there.
Be sure to:
Replace
your_license_filewith the path to your license file. For example,~/Downloads/liquibase.licReplace
your_deployment_directorywith an empty directory for the sandbox deployment. For example,~/liquibase-sandbox
./liquibase-platform install --license your_license_file --dir your_deployment_directoryWithout --domain, the installer uses localhost, so the web app is reachable only from this machine, and the certificate it generates is self-signed. When install finishes, it prints the address:
Access URL: https://localhost
TLS: Self-signed certificateTurn on sample data
Sample data gives you a worked example workspace to govern, with a project, its databases, a changelog and several weeks of deployment history. It is turned off by default.
The installer wrote a .env file into the deployment directory you passed to --dir in step 1. Open it and change the LIQUIBASE_PLATFORM_SAMPLE_DATA line to:
LIQUIBASE_PLATFORM_SAMPLE_DATA=trueRestart the server from the folder you extracted, so it reads the change. Be sure to replace your_deployment_directory with the directory from step 1.
./liquibase-platform stop --dir your_deployment_directory
./liquibase-platform start --dir your_deployment_directoryThe server reports what it created as it starts.
This is example data rather than a trial data set. It is safe to turn on for a server that already holds real records, because it only adds its own, and it is provisioned once for a workspace, so restarting does not duplicate it.
Note: sample deployments are counted in the dashboard figures along with your own, so the numbers on a populated sandbox describe the example, not your team. Remove the sample data from Settings before you use the server for real work, which is permanent and leaves anything you created untouched.
Open the web app and set up the server
Open https://localhost. Your browser warns you about the self-signed certificate the first time, which is expected on a local install, so continue past it.
The console opens on a two-step setup:
In Create the administrator account, enter your Full name, Work email, and Password, confirm the password, and select Create account.
In Import your license, drag your license file onto Drop your license file here or select browse, then select Import license.
The first account is the administrator of this workspace, which is what lets you create the policy assignment and the service principal later in this walkthrough.
Look around the sample workspace
Sign in and open Projects. The workspace holds one project, LB Sample Project, with six database connections, three pipelines and one changelog. Open Database Connections to see how they are laid out.
Four connections follow the same logical database along a promotion path, from development through test and staging to production. Two more sit outside that path, a data staging database and a disaster recovery database, which is the part worth noticing: a project is not just a list of environments.
The project, its connections, its changelog and its pipelines each carry a Sample badge, and the badge stays even if you rename the record, so you can always tell the example apart from your own work.

Find the deployment that failed
Open All Operations under Monitor. The sample workspace comes with several weeks of deployment history that ends today, and not every deployment in it succeeded.

Find the failed update against LB Sample PROD and open it. A changeset tried to add a unique index to a column that already held duplicate values, so the deployment stopped part way through. The rollback that recovered it sits just above in the list.

You have now identified a changeset that failed, which database it is connected to, and what actions were taken. The rest of this walkthrough shows you how to catch a problem like that before it reaches a database.
Copy the package into a catalog of your own
Checks live in packages, and packages live in catalogs. The Liquibase Default Catalog is the read-only library Liquibase ships, so you copy what you want out of it into a catalog of your own, where you can change what the checks do.
Under Govern, select Policies to open Manage All Catalogs. Choose Manage on the Liquibase Default Catalog to open a Policy Checks Packages page.
Select + New, choose New Catalog, give it a name, for example Sandbox policies, and select Create catalog.
The new catalog opens with the Copy packages into dialog already open. Leave the Liquibase Default Catalog as the source, select the Data Protection package, which guards against destructive changes, and confirm.
Your catalog now holds its own copy of the package. Copies are independent, so what you change here does not affect the built-in catalog, and the built-in catalog stays intact for everyone else.

Raise the severity so the check can stop a deployment
Every check ships at the lowest severity, which returns exit code 0. A run reports the violation and the pipeline carries on. Raising the severity on your copy is what turns the check into something that can stop a deployment.
Open the Data Protection package in your catalog and find Warn when 'DROP TABLE' detected.
Open its configuration, set Severity to 2, and save.
Note: Severity belongs to the check in the catalog, not to the assignment. An assignment carries which checks are on, so the catalog is the only place to change what a check returns. This is also why the built-in catalog cannot be raised: it is read-only.
Assign the package to the sample project
An assignment is what connects a set of checks to the databases and changelogs they apply to. Build one from the package you just prepared:
On your catalog's Policy Checks Packages page, select the checkbox for the Data Protection package, then select Assign. The button appears only after you select a package.
Select New Assignment, give it a name such as Sandbox data protection, and create it.
Select Manage on the assignment, then tick LB Sample Project in the asset tree. Selecting the project covers everything under it.
Select Save Assignment, review what the change affects, and confirm.
The assignment now shows its ID at the top of its detail page, with a control to copy it. Copy it now. That ID is the whole connection between the policy you just built and the command you are about to run.

Create a service principal
A service principal is the identity a pipeline uses to send operations to the server, instead of a person's own token. It is scoped to one or more projects. It can send operations and fetch policy checks for those projects, and it cannot sign in to the console.
A project groups database connections and changelogs. In your own workspace, you register a database connection and a changelog, then create a project, before you create a service principal for it. The sample workspace already has them in LB Sample Project.
To create the service principal:
Under Administer, select Service Principals, then select Create service principal.
Enter a Name. Name it after the pipeline that will use it, so a revocation is easy to trace. For example, sandbox-pipeline.
Under Project scope, select LB Sample Project, then select Create & generate token.
Select Copy token, and keep the token for step 10.
The token is shown only once. If you lose it, select Rotate on the service principal's row to get a new one.
Point your Liquibase project at the server
In the Liquibase project you built against the H2 sandbox, add these lines to liquibase.properties.
A service principal's token must name a connection or a changelog in its project, so the server can file each operation under that project. liquibase.platform.connectionIdentifier names LB Sample DEV by its identifier, sample-app-dev. You can name a changelog's identifier with liquibase.platform.changelogIdentifier instead.
Be sure to:
Replace
your_service_principal_tokenwith the token you copied in step 9. To keep the token out of the file, set it as theLIQUIBASE_PLATFORM_API_KEYenvironment variable instead and leave out theliquibase.platform.apiKeyline.Replace
localhostinapiUrlif your server is not on this machine. The value is the address of your server with/apion the end, not the address of a particular endpoint. The host name must be one the server's certificate covers. The certificateinstallgenerates coverslocalhost,127.0.0.1, and the--domainyou installed with.
One connection setting serves both jobs. It sends your operations to the server, and it is what the next steps use to fetch the policy.
Note: Without liquibase.platform.enabled=true, the commands still run normally and report nothing at all, which is the easiest thing to get wrong here. Without an identifier, the server refuses each operation with a 403 and This request names neither X-Connection-Identifier nor X-Changelog-Identifier, and Liquibase writes the operation to its recovery file instead.
The server uses the self-signed certificate that install generated, and the Java that runs Liquibase does not trust it yet. Until it does, each Liquibase command still succeeds, but its operation goes to the recovery file instead of the server, and Liquibase prints PKIX path building failed. To fix that, copy the Java trust store, add the server's certificate to the copy, and point Liquibase at the copy. Run Liquibase in the same shell afterwards, so it picks up JAVA_OPTS, and keep the copy at a path without spaces, because the launcher passes JAVA_OPTS to Java unquoted.
Be sure to:
Replace
your_java_homewith the home of the Java that runs Liquibase. Theliquibaselauncher usesJAVA_HOMEif it is set, then thejredirectory inside the Liquibase installation, then thejavaon yourPATH. For the last case,java -XshowSettings:properties -version 2>&1 | grep java.homeprints it.Replace
your_deployment_directorywith the directory from step 1.
changeit is the default password of Java's trust store. The copy keeps every public certificate authority, so Liquibase still reaches other HTTPS services. If you can write to that Java's own trust store, you can import the certificate into it instead and skip JAVA_OPTS.
Add a change the policy should catch
Add a changeset that drops a table to the end of your changelog. Dropping a table is exactly the kind of change the Data Protection package is there to notice.
Run the policy checks from the assignment
Run the checks against the assignment rather than a local file:
Be sure to:
Replace your_assignment_id with the ID you copied in step 8.
liquibase checks run --assignment-id=your_assignment_idLiquibase fetches the checks the assignment maps, runs them, and names the changeset that tripped one:
Nothing in that command names a check, a severity or a file. It names an assignment and the server decides the rest, so changing the assignment changes what the next run enforces, with no edit to your pipeline.
The command exited with code 2, which is the exit code for MAJOR, so a pipeline step running this would stop here. That is the severity you set in step 7, travelling from your catalog through the assignment to the run.
Note: By default, only changelog checks run. Add --checks-scope=changelog,database to include the checks that inspect the database itself. Run checks with a policy assignment covers the command in full.
See the run in the web app
Open Policy Checks under Monitor. The run you just did is listed there, and the tiles above the list count the violation it found.
The policy was decided in one place, applied by a command that names nothing but an assignment, and recorded where the rest of your team can see it.
