/
Liquibase Best Practices (Copy)

Liquibase Best Practices (Copy)

 

Changelog Folder Structure Convention

Use this fixed layout and keep all new change files version-scoped:

changelog/
├── changelog-master.xml
└── changes/
├── changelog-v1.0.xml
└── v1.0/
├── changelog-1.xml
├── changelog-N.xml

Rules:

  • changelog-master.xml includes only version aggregators (changes/changelog-vX.Y.xml)

  • each changelog-vX.Y.xml includes only files from changes/vX.Y/

  • create a new vX.Y/ + changelog-vX.Y.xml for each release

Changeset ID Naming Convention

Format

@@--[-]

Allowed values

  • scope: schema | data | refactor | fix

  • action: create | alter | drop | rename | migrate | backfill | seed | cleanup | enforce

  • target (primary DB object):

  • table-

  • column--

  • index-

  • fk--to-

  • type-

  • detail (optional): specific intent, e.g. add-not-null, add-metadata-fields, rule-to-specification-rule

Style rules

  • Lowercase only

  • Kebab-case only

  • ASCII only

  • No : and no spaces

  • Use imperative verbs (no gerunds/past tense)

  • IDs are immutable after release

  • Prefer clear/specific names over short names

Examples

  • schema-create-type-family-enum

  • schema-create-table-field

  • schema-alter-table-specification-rule-add-metadata-fields

  • data-migrate-rule-to-specification-rule-metadata-fields

  • schema-enforce-column-specification-rule-id-not-null