> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/database-devops/3.0/use-db-devops/reference/glossary/changelog.md).

# What is a Changelog?

\
{\`\
{\
"@context": "<https://schema.org",\\>
"@type": "FAQPage",\
"mainEntity": \[\
{\
"@type": "Question",\
"name": "What is a changelog in Liquibase?",\
"acceptedAnswer": {\
"@type": "Answer",\
"text": "A changelog is a text-based file that sequentially lists database changes in the form of changesets. It acts as a source of truth for versioning and deployment of database schema updates."\
}\
},\
{\
"@type": "Question",\
"name": "What formats can I use for Liquibase changelogs?",\
"acceptedAnswer": {\
"@type": "Answer",\
"text": "Liquibase changelogs can be written in SQL, XML, YAML, or JSON. Liquibase Pro users can also use formatted MongoDB syntax."\
}\
},\
{\
"@type": "Question",\
"name": "Can I include other changelogs inside a main changelog?",\
"acceptedAnswer": {\
"@type": "Answer",\
"text": "Yes, using the include or includeAll tags. This modular approach supports better collaboration, parallel development, and reusability of schema definitions."\
}\
},\
{\
"@type": "Question",\
"name": "What happens when I run the Liquibase update command?",\
"acceptedAnswer": {\
"@type": "Answer",\
"text": "Liquibase parses the changelog, evaluates global preconditions, and then applies new changesets to the target database. Previously applied changesets are skipped."\
}\
},\
{\
"@type": "Question",\
"name": "Where is changelog execution history stored?",\
"acceptedAnswer": {\
"@type": "Answer",\
"text": "Liquibase records applied changesets in the DATABASECHANGELOG table. From version 4.27.0 onwards, it also logs metadata in the DATABASECHANGELOGHISTORY table."\
}\
}\
]\
}\
\`}<br>

### What will you learn <a href="#what-will-you-learn" id="what-will-you-learn"></a>

A **changelog** in Harness Database DevOps, is a version-controlled text file that defines how a database schema should evolve over time. It consists of a sequence of **changesets**, each describing a specific change (e.g., creating tables, modifying indexes, or adding constraints).

Harness uses changelogs to apply schema changes in a controlled, traceable, and CI/CD-friendly manner. By tracking every schema update in a changelog, teams can roll changes forward or backward confidently and align schema versioning with application releases.

### How changelog works <a href="#how-changelog-works" id="how-changelog-works"></a>

When running a harness apply step Harness will download your changelog, and run various commands to apply any pending changes to your database, and confirm which have already been applied. E.g. for a liquibase-based changelog we will execute the liquibase 'update' command using liquibase It checks each changeset to determine whether it has been applied by consulting the `DATABASECHANGELOG` table. If the changeset is new, it is executed. Otherwise, it is skipped unless attributes like `runAlways` or `runOnChange` are set. This mechanism ensures that schema changes are applied only once, preventing duplicate updates and maintaining a consistent database state across environments.

### Changelog structure <a href="#changelog-structure" id="changelog-structure"></a>

Changelogs can include:

* One or more **changesets**
* Global **preconditions** that determine whether deployment should proceed
* **Include** or **includeAll** tags to modularize logic
* Environment-aware logic using **contexts** and **labels**

This flexibility allows teams to scale schema management across teams, microservices, and lifecycle stages.

#### Example YAML changelog <a href="#example-yaml-changelog" id="example-yaml-changelog"></a>

```yaml
databaseChangeLog:
  - preConditions:
      - dbms:
          type: postgresql
  - include:
      file: changesets/user-schema.yaml
  - include:
      file: changesets/order-schema.yaml
```

### Runtime behavior and execution flow <a href="#runtime-behavior-and-execution-flow" id="runtime-behavior-and-execution-flow"></a>

When a changelog is executed:

* Liquibase detects format by file extension and header.
* Global preconditions are validated.
* If passed, Liquibase processes changesets in sequence.
* Each executed changeset is recorded in the DATABASECHANGELOG table.
* Each changesets are tracked using the unique combination of
  * id
  * author
  * changelog file name
  * file path

This ensures no duplicate application of schema changes.

### Best practices <a href="#best-practices" id="best-practices"></a>

Follow these practices to keep your changelogs reliable and maintainable:

* Keep each changeset atomic (one logical change per changeset).
* Use include or includeAll for modularization and team collaboration.
* Use labels to provide additional context to users about a change, for example the ticket number associated with the change.
* Adopt a consistent naming convention for changelog files and directories.
* Review rollback behavior and use rollback blocks where applicable.

### Conclusion <a href="#conclusion" id="conclusion"></a>

A changelog is the backbone of database versioning in Harness Database DevOps. It enables consistent, traceable, and auditable deployment of schema changes across environments. Whether you author changelogs in SQL, YAML, XML, or JSON, the changelog structure is designed to support your team’s collaboration, CI/CD automation, and rollback safety at scale.

### Next steps <a href="#next-steps" id="next-steps"></a>

* Learn about [Changesets](/database-devops/use-db-devops/reference/glossary/changeset.md) to understand how individual database changes are defined and managed.
* Explore [Contexts](/database-devops/use-db-devops/reference/glossary/context.md) to understand how to control changeset execution across environments.

### FAQ <a href="#faq" id="faq"></a>

#### 1. What is a changelog in Harness Database DevOps? <a href="#id-1-what-is-a-changelog-in-harness-database-devops" id="id-1-what-is-a-changelog-in-harness-database-devops"></a>

A changelog is a text-based file that sequentially lists database changes in the form of changesets. It acts as a source of truth for versioning and deployment of database schema updates.

#### 2. Can I include other changelogs inside a main changelog? <a href="#id-2-can-i-include-other-changelogs-inside-a-main-changelog" id="id-2-can-i-include-other-changelogs-inside-a-main-changelog"></a>

Yes, using the [`include` or `includeAll`](https://github.com/iKettles/harness-gitbook/tree/main/docs/database-devops/concepts-and-features/understanding-changelog-directories/organizing-sql-files/README.md#include-and-includeall-tags) tags. This modular approach supports better collaboration, parallel development, and reusability of schema definitions.

#### 3. What Happens when I run the Harness Apply Step? <a href="#id-3-what-happens-when-i-run-the-harness-apply-step" id="id-3-what-happens-when-i-run-the-harness-apply-step"></a>

Liquibase parses the changelog, evaluates global preconditions, and then applies new changesets to the target database. Previously applied changesets are skipped.

#### 4. Where is changelog execution history stored? <a href="#id-4-where-is-changelog-execution-history-stored" id="id-4-where-is-changelog-execution-history-stored"></a>

Harness Database DevOps records applied changesets in the `DATABASECHANGELOG` table. From version 4.27.0 onwards, it also logs metadata in the `DATABASECHANGELOGHISTORY` table.

#### 5. What happens if I am currently using liquibase, how can I convert my Liquibase Changelog to a Harness Changelog? <a href="#id-5-what-happens-if-i-am-currently-using-liquibase-how-can-i-convert-my-liquibase-changelog-to-a-ha" id="id-5-what-happens-if-i-am-currently-using-liquibase-how-can-i-convert-my-liquibase-changelog-to-a-ha"></a>

Harness's changelog is compatible to open source liquibase. Just point Harness at your existing changelog

#### 6. What happens if I am currently using Flyway, how can I convert my Flyway Changelog to a Harness Changelog? <a href="#id-6-what-happens-if-i-am-currently-using-flyway-how-can-i-convert-my-flyway-changelog-to-a-harness" id="id-6-what-happens-if-i-am-currently-using-flyway-how-can-i-convert-my-flyway-changelog-to-a-harness"></a>

Flyway changelogs are typically directories of SQL files to run in alphabetical order. Go to [Build a changelog](/database-devops/3.0/use-db-devops/changelogs-and-schema-changes/liquibase/build-a-changelog.md) to point Harness at this directory. For example, if your Flyway changelog is in a directory called `sql`, you can use the `includeAll` tag, which can do this:

```yaml
databaseChangeLog:
  includeAll:
  path: sql
```