Liquibase Contexts and Labels: A Practical Guide to Environment-Specific Database Migrations

The Problem: Managing Different Database Schemas Across Environments

When working with multiple database environments—development, testing, staging, and production—you often need different schema changes applied to each. Creating and maintaining separate changelog files for each environment leads to duplication, merge conflicts, and configuration drift. Liquibase solves this with contexts and labels, allowing you to manage all environments from a single changelog file.

Understanding Contexts and Labels

Contexts are logical groupings that represent environments or deployment scenarios. You assign them to changesets using the context attribute. When you run Liquibase with --contexts=dev, only changesets tagged with context="dev" will execute.

Labels are attributes that mark changesets with metadata like feature names, ticket numbers, or release versions. They're defined with the label attribute. Unlike contexts, labels can be combined with AND/OR logic for more granular control.

Combining Contexts and Labels for Fine-Grained Control

You can combine both in a single changeset. For example, context="dev,test" label="featureX" means the changeset runs only when the context is dev OR test, AND the label featureX is present. This enables complex deployment strategies like feature flagging at the database level.

Practical Example: Feature-Toggled Migration

Let's say you're developing a new feature that requires a new table, but you only want it in development and test environments until the feature is ready for production:

<changeSet id="add-feature-table" author="dev-team" context="dev,test" label="featureX">
    <createTable tableName="feature_x_data">
        <column name="id" type="BIGINT" autoIncrement="true">
            <constraints primaryKey="true" />
        </column>
        <column name="payload" type="CLOB" />
    </createTable>
</changeSet>

<changeSet id="add-prod-index" author="dev-team" context="prod">
    <createIndex indexName="idx_feature_x_data" tableName="feature_x_data">
        <column name="payload" />
    </createIndex>
</changeSet>

To execute only the development changesets, run:

liquibase --contexts=dev --labels=featureX update

Verification and Testing Your Setup

After running your update, verify the results by checking the DATABASECHANGELOG table:

SELECT ID, AUTHOR, CONTEXT, LABELS, EXECUTED FROM DATABASECHANGELOG;

This shows which changesets executed and their associated context/label. Use liquibase status to see pending changesets in your current configuration.

Trade-offs and Limitations

While contexts and labels provide powerful flexibility, they introduce complexity. Overusing them can make your changelog difficult to understand. Teams should establish clear naming conventions and document what each context and label represents. Remember that if a changeset doesn't match the runtime context or label, Liquibase will skip it silently—potentially leading to missed migrations if misconfigured.

Actionable Steps to Get Started

1. Define your contexts: Create a naming convention (e.g., dev, test, staging, prod)
2. Identify feature labels: Use labels for feature flags, ticket numbers, or release versions
3. Update your CI/CD pipeline: Set the LIQUIBASE_CONTEXT environment variable appropriately for each environment
4. Test locally: Run liquibase --contexts=dev --labels=your-feature update against a test database
5. Verify results: Check the DATABASECHANGELOG table to confirm only expected changesets executed

By leveraging contexts and labels effectively, you can maintain a single source of truth for database migrations while adapting to the specific needs of each environment and feature development cycle.