Using logicalFilePath to Restructure Changelogs

Applies to

• Liquibase Secure (Pro)
• Liquibase Community (Open Source)

Summary

When restructuring your Liquibase project by moving changelogs to new directories or renaming files, you need to use the logicalFilePath attribute to maintain changeset tracking continuity. Without this attribute, Liquibase will treat the moved/renamed changesets as new changes and attempt to execute them again, even though they've already run against your database.

The logicalFilePath attribute tells Liquibase to track the changeset using the original file path in the DATABASECHANGELOG table, even though the physical file now exists in a different location. This is essential when reorganizing your changelog structure while preserving your deployment history.

Best Practice: When restructuring changelogs, always use logicalFilePath to reference the original file path. This ensures Liquibase recognizes previously executed changesets and prevents duplicate execution attempts.

Environment Conditions

This process applies to:

• All Liquibase versions that support the logicalFilePath attribute
• All database platforms
• Any changelog format (SQL, XML, YAML, JSON)
• Projects using includeAll or individual include statements in root changelogs

How to Restructure Changelogs Using logicalFilePath

Step 1: Create Your New Directory Structure

Before making any changes to your changelogs, create the new folder structure where you want to organize your files.

Example:

• Old structure: ./pgsql_changelogs/app1/schema.sql
• New structure: ./pgsql_changelogs/app1/release06042025/release01_schema_ddl/schema01.sql

Copy (do not move yet) your existing changelog files to the new locations. You can rename them during this process if desired.

Step 2: Update Your Root Changelog

In your root changelog file, update the includeAll or include paths to point to the new directory structure.

XML Example:

<databaseChangeLog>
    <includeAll path="pgsql_changelogs/app1/release06042025/release01_schema_ddl"/>
    <includeAll path="pgsql_changelogs/app1/release06042025/release02_schema_ddl"/>
</databaseChangeLog>

YAML Example:

databaseChangeLog:
  - includeAll:
      path: pgsql_changelogs/app1/release06042025/release01_schema_ddl
  - includeAll:
      path: pgsql_changelogs/app1/release06042025/release02_schema_ddl

Step 3: Add logicalFilePath to Existing Changesets

In each moved or renamed changelog file, add the logicalFilePath attribute to every changeset that has already been executed. The logicalFilePath value should reference the original file path where the changeset was located when it was first deployed.

SQL Format Example:

--changeset your.name:1 logicalFilePath:pgsql_changelogs/app1/schema.sql
CREATE TABLE example_table (
    id INT PRIMARY KEY,
    name VARCHAR(255)
);

--changeset your.name:2 logicalFilePath:pgsql_changelogs/app1/schema.sql
ALTER TABLE example_table ADD COLUMN description TEXT;

XML Format Example:

<changeSet id="1" author="your.name" logicalFilePath="pgsql_changelogs/app1/schema.sql">
    <createTable tableName="example_table">
        <column name="id" type="int">
            <constraints primaryKey="true"/>
        </column>
        <column name="name" type="varchar(255)"/>
    </createTable>
</changeSet>

YAML Format Example:

databaseChangeLog:
  - changeSet:
      id: 1
      author: your.name
      logicalFilePath: pgsql_changelogs/app1/schema.sql
      changes:
        - createTable:
            tableName: example_table
            columns:
              - column:
                  name: id
                  type: int
                  constraints:
                    primaryKey: true

Step 4: Test Your Changes

Before deploying to production, test your restructured changelogs in a development or test environment:

1. Run liquibase status to verify Liquibase recognizes the changesets correctly
2. Run liquibase update-sql to confirm no changesets will be re-executed
3. You can now safely run liquibase update. No changes should be deployed (assuming no new changesets were added).
4. Check the DATABASECHANGELOG table to verify that the original file paths are maintained

Expected Result: Liquibase should recognize all changesets with logicalFilePath as already executed and show "0 changesets have been applied" (assuming no new changesets were added).

Step 5: Remove Old Changelog Files (Optional)

Once you've confirmed the restructuring works correctly in your test environment, you can safely delete the old changelog files from their original locations. The logicalFilePath attribute maintains the reference to the original path in the database tracking tables, so the physical files are no longer needed.

Important Considerations

Database Tracking Tables Maintain Original Paths

When using logicalFilePath, the DATABASECHANGELOG and DATABASECHANGELOGHISTORY tables will continue to store the original file path specified in the logicalFilePath attribute, not the new physical location of the file.

Example DATABASECHANGELOG entry:

FILENAME: pgsql_changelogs/app1/schema.sql

(Even though the file is now located at pgsql_changelogs/app1/release06042025/release01_schema_ddl/schema01.sql)

Rolling Back Changesets with logicalFilePath

When rolling back changesets that use logicalFilePath, you must reference the original file path (the value in logicalFilePath), not the new physical location.

Command Example:

liquibase rollback-one-changeset \
  --changelog-file=root_changelog.xml \
  --changeset-author=your.name \
  --changeset-id=1 \
  --changeset-path=pgsql_changelogs/app1/schema.sql \
  --force

New Changesets Don't Require logicalFilePath

Only changesets that have already been executed need the logicalFilePath attribute. New changesets added to your moved/renamed files can omit this attribute, and they will be tracked using their current file path.

Common Mistakes to Avoid

1. Not adding logicalFilePath to already-executed changesets: This will cause Liquibase to attempt to re-execute them, resulting in errors or duplicate data.
2. Using the new path in logicalFilePath: The logicalFilePath should always reference the original path, not the new location.
3. Forgetting to update the root changelog: Make sure your include or includeAll statements point to the new directory structure.
4. Using the new path for rollbacks: Always use the original file path (from logicalFilePath) when rolling back changes.

Related Article(s)

• Liquibase Documentation: logicalFilePath 
• Liquibase Documentation: includeAll 
• Liquibase Documentation: include 
• Liquibase Documentation: Organizing Changelogs 
• DATABASECHANGELOG Table 
• Rollback Commands