Java.DBMigrationTools.What is a logicalFilePath?

✅ Short Answer

The logicalFilePath is an identifier for a changelog file that Liquibase uses internally to track changesets — instead of the physical file path.

It helps ensure consistent tracking of changesets even if the file is moved, renamed, or used in a different environment or CI/CD path.

🔎 Detailed Explanation

By default, Liquibase identifies a changeset using:

ID + AUTHOR + FILENAME

• ID — unique within the file
• AUTHOR — who created it
• FILENAME — path to the changelog file (e.g., src/main/resources/db/changelog.xml)

If the file is renamed or moved, that FILENAME changes — and Liquibase thinks it’s a different changeset, which can cause duplicate execution or checksum errors ❌.

🎯 Enter logicalFilePath

You can override the filename tracking with a stable, logical path:

<databaseChangeLog logicalFilePath="changelog/main.xml"
                   xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
                   ...>

Even if the physical file moves to a different folder, the logicalFilePath stays the same, so Liquibase knows it’s the same changeset.

🧠 Use Cases

Use Case	Benefit of logicalFilePath
CI/CD pipelines with different folder layouts	Prevents duplicate changeset execution
Renaming/moving changelog files	Maintains consistency and checksum integrity
Working across multiple branches or repos	Keeps changeset identity stable

---

✅ With logicalFilePath, changesets are tracked like this:

ID + AUTHOR + LOGICAL_FILE_PATH

Instead of:

ID + AUTHOR + PHYSICAL_FILE_PATH

📌 Key Takeaways

✅ logicalFilePath gives a stable identity to changelogs across environments
✅ Prevents duplicate execution or checksum errors if a file is renamed or moved
✅ Essential for collaborative projects, CI/CD, or multi-repo setups