Using Liquibase Contexts and Labels to Control Deployment Scope

The Problem: A Seed-Data ChangeSet Reaches Production

A developer adds a changeSet that loads demo users into a lookup table. The file is committed to the main branch, and the deployment pipeline runs liquibase update against production. Because nothing in the changeSet says "run this only in development," the demo data lands in the production database. The fix is not more process; it is scoping the changeSet so Liquibase knows where it belongs.

Thesis: Contexts Answer Where, Labels Answer What

A context is a deployment target, such as dev, test, or prod. A label describes the kind of change, such as seed-data, feature, or hotfix. You pass contexts and labels to the Liquibase command line at runtime. Liquibase applies only changeSets whose context matches, and you can further filter by label. ChangeSets without a context always run unless you restrict the context set.

Worked Example: Seed Data That Stays Out of Production

Mark the changeSet with both attributes:

<changeSet id='load-demo-users-2026' author='platform-team' context='dev' label='seed-data'>
  <comment>Demo accounts for local development only</comment>
  <loadData file='csv/demo-users.csv' tableName='users' />
  <rollback>
    <delete tableName='users'>
      <where>email LIKE '%@demo.example'</where>
    </delete>
  </rollback>
</changeSet>

Run the command from your project root or CI pipeline. Replace the placeholders with your connection details:

liquibase
  --url=jdbc:postgresql://<DATABASE_HOST>:5432/<DATABASE_NAME>
  --username=<DB_USER>
  --password=<DB_PASSWORD>
  --changeLogFile=db/changelog/master.xml
  --contexts=dev
  update

The database user must be able to create and update the DATABASECHANGELOG and DATABASECHANGELOGLOCK tables, in addition to any schema privileges the changeSets require.

Because this operation changes state, verify it afterward. Query the audit table to confirm the context and label were recorded:

SELECT id, author, filename, contexts, labels, dateexecuted
FROM databasechangelog
WHERE id = 'load-demo-users-2026'
ORDER BY dateexecuted DESC;

If no row appears, Liquibase skipped the changeSet because the runtime context did not include dev.

Diagnostic Decision: Contexts, Labels, or Both

Use this table to decide which attribute to set:

Goal	Attribute	Example value	Runtime flag
Run only in one environment	context	dev	--contexts=dev
Run a category of changes selectively	label	seed-data	--labels=seed-data
Combine environment and category	context + label	context='test' label='smoke-test'	--contexts=test --labels=smoke-test

To preview what would run without applying anything, use liquibase update-sql --contexts=dev. To see pending changeSets, run liquibase status --contexts=dev. These commands read the database but do not modify it.

Limitation: Changing Contexts or Labels Invalidates the Checksum

Liquibase computes a checksum for every executed changeSet. If you add or edit a context or label on a changeSet that already appears in DATABASECHANGELOG, the stored checksum no longer matches. Liquibase will block further deployments with a checksum validation error until you address the mismatch.

Practical check: before deploying, run liquibase status against the target database. If it reports a checksum error, confirm the schema already reflects the changeSet, then run liquibase changelog-sync --contexts=dev to mark it as executed without reapplying it. Do not force-sync a changeSet whose actual SQL you intend to change.

Actionable Closing

1. Audit your changeLog for changeSets that should not run in production, such as seed data or test indexes.
2. Add context to environment-specific changeSets and label to categorical ones.
3. Update your CI deployment commands to pass --contexts matching the target environment.
4. Run liquibase update-sql first to review the generated SQL.
5. Check DATABASECHANGELOG after deployment to confirm contexts and labels were recorded.

Start with one changeLog file and one environment. Once the pattern is reliable, extend it across your modules rather than converting every changeSet at once.