Introduction

In Liquibase, DATABASECHANGELOG.FILENAME is not just a display value. It is part of changeset identity, so changing changelog file paths carelessly can make old changesets look new and trigger duplicate execution attempts. In Spring Boot, the safe way to move changelog files is to separate the physical file location from the logical identity Liquibase stores.

What DATABASECHANGELOG.FILENAME Means

Liquibase identifies a changeset using a combination of:

• changeset id
• author
• file path or logical file path

So if a file moves from one path to another and Liquibase sees the path as different, it may treat the changeset as a different one even if the contents are unchanged.

That is why renaming or moving changelog files is more than a cosmetic edit.

Change the Spring Boot Changelog Entry Point

Spring Boot tells Liquibase where the root changelog lives through spring.liquibase.change-log.

spring.liquibase.change-log=classpath:db/changelog/main.yaml

Or in YAML:

spring:
  liquibase:
    change-log: classpath:db/changelog/main.yaml

This changes the physical startup path, but it does not by itself preserve the old filename identity already recorded in DATABASECHANGELOG.

Use logicalFilePath to Preserve Identity

If you want to move or rename a changelog file without changing how Liquibase identifies its changesets, set a stable logical path.

1databaseChangeLog:
2  - logicalFilePath: db/changelog/db.changelog-master.yaml
3  - changeSet:
4      id: 1
5      author: app
6      changes:
7        - createTable:
8            tableName: sample
9            columns:
10              - column:
11                  name: id
12                  type: bigint

With logicalFilePath, you can reorganize the actual file layout while preserving the identity Liquibase uses internally.

Typical Migration Strategy

When changing the changelog location in an existing project, a safe sequence is:

1. decide the stable logical path you want Liquibase to keep
2. move or rename the physical file
3. update spring.liquibase.change-log to the new physical location
4. set logicalFilePath so old changesets still match their historical identity
5. test against a copy of a real database before using the change in production

That approach is much safer than simply renaming files and hoping Liquibase treats them as the same object.

Manual Table Updates Are a Repair Option

If the path has already changed and Liquibase now sees old changesets as new ones, some teams repair the metadata manually:

UPDATE DATABASECHANGELOG
SET FILENAME = 'db/changelog/db.changelog-master.yaml'
WHERE FILENAME = 'db/changelog/old-location.yaml';

This can work, but it is a repair step, not the preferred design. It should be done only with a backup and a clear understanding of the changeset history.

Why Testing Matters So Much Here

Path-related Liquibase mistakes are dangerous because they often do not fail immediately. Instead, they can appear as duplicate changeset execution attempts on an environment with existing history while a brand-new database still looks fine. That is why path changes should always be tested against a database that already contains the historical DATABASECHANGELOG rows you expect in production.

Common Pitfalls

The biggest pitfall is assuming spring.liquibase.change-log alone solves the problem. It only changes where Liquibase starts reading; it does not preserve existing changeset identity automatically.

Another common mistake is moving changelog files in a mature project without defining logicalFilePath. That often causes Liquibase to think unchanged changesets are brand new.

Developers also sometimes patch DATABASECHANGELOG first and only later realize the root cause was an avoidable identity mismatch.

Summary

• 'DATABASECHANGELOG.FILENAME is part of Liquibase changeset identity.'
• Changing the Spring Boot changelog location does not automatically preserve that identity.
• Use logicalFilePath when moving or renaming changelog files.
• Manual updates to DATABASECHANGELOG are a repair tactic, not the best normal workflow.
• Test changelog path changes carefully before applying them to a real database.