> 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/use-db-devops/deployment-pipeline-configuration/step-types/apply-dbschema-step.md).

# Apply DB Schema step

Configure the Apply DB Schema step in a Harness Database DevOps pipeline to apply Liquibase or Flyway migrations to a target database instance.

The **Apply DB Schema** step runs pending database migrations against a target DB instance as part of a Harness pipeline. It applies changesets tracked in your schema changelog, optionally creates a rollback tag, and exposes a `preStartTag` expression so downstream steps can roll back to the exact state before the deployment began.

### Add the Apply DB Schema step

1. In Harness, go to **Database DevOps** and select your project.
2. Open your pipeline and select the stage where you want to apply migrations.
3. Add a **Custom Stage** with a step group.
4. Inside the step group, **Add Step** and choose **Apply DB Schema**.
5. Configure the step parameters described below.
6. Select **Apply Changes**, then save and run the pipeline.

### Step parameters

![DBDevOps Apply DBSchema Step](https://4089095456-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWwqb27iUU3gZvwGNroZp%2Fuploads%2Fgit-blob-d9f71e69d7462a2ea9b200d5caa001803f0d72b1%2Fdbops-apply-schema-step.png?alt=media)

1. **Name** - Display name for the step. The step ID is derived from this name.
2. **Timeout** - Maximum duration before the step times out. Default is `10m`.
3. **Container Registry** - Select the container registry connector that Harness uses to pull the migration container.
4. **Migration Type** - Select **Liquibase** or **Flyway** depending on your schema's migration tool.
5. **Select DB Schema** - Choose the DB Schema that holds your changelog and migration definitions.
6. **Select DB Instance** - Choose the DB Instance (database connection) where migrations will be applied.
7. **Specify tag to create (optional)** - Enter a tag value (for example, `v1.0.0`) to stamp the database after migrations are applied. This tag serves as a rollback anchor for downstream rollback steps. If left blank and no existing tag is found on the last changeset, Harness creates one automatically.
8. You can configure optional parameters passed to the migration tool:

* **Mark Failed Changeset Ran** - When enabled, marks failed changesets as ran in `DATABASECHANGELOG` even if they did not execute successfully. This allows rollback steps to include the failed changeset in their rollback scope. Go to [Mark Failed Changeset Ran](/database-devops/use-db-devops/deployment-pipeline-configuration/rollback-and-failure-strategies/failure-strategies.md#mark-failed-changeset-ran) for details.
* **Tag Database Changeset** - When enabled, writes a synthetic tag-marker row to `DATABASECHANGELOG` on no-op deployments (zero applied changesets). Use this when you need a consistent rollback anchor across multi-service releases. Go to [Tag Database Changeset](/database-devops/use-db-devops/deployment-pipeline-configuration/rollback-and-failure-strategies/tag-database-changeset.md) for details.

### Use the preStartTag expression for rollback

The Apply DB Schema step exposes the tag that was active on the database before the deployment started. Use this in a downstream Rollback DB Schema step to revert to the exact pre-deployment state.

**Within the same stage:**

```
<+execution.steps.{stepGroupIdentifier}.steps.{stepIdentifier}.output.preStartTag>
```

**From a different stage:**

```
<+pipeline.stages.{stageIdentifier}.spec.execution.steps.{stepGroupIdentifier}.steps.{stepIdentifier}.output.preStartTag>
```

Go to [Rollback Tags with Apply Schema](/database-devops/use-db-devops/deployment-pipeline-configuration/rollback-and-failure-strategies/using-rollback-tags.md) for a full walkthrough.

## Troubleshooting

### Step fails with "changelog file not found"

Verify the DB Schema is correctly configured with a valid Git repository or custom script. Check that the changelog path in the schema configuration points to an existing file. Ensure the delegate has access to clone the Git repository.

### Database lock timeout during changeset execution

Check for long-running transactions or locks on the target database. Verify no other deployment is running against the same database. Increase the step timeout value if the changeset operations require more time.

### Changeset already ran error

This occurs when rerunning a pipeline with changesets that were already applied. Verify the changeset IDs are unique and incremental. Check the `DATABASECHANGELOG` table to see which changesets were recorded. To re-apply a changeset, mark it with `runAlways: true` or `runOnChange: true` in the changelog.

### Permission denied during schema apply

Ensure the database user has sufficient privileges to execute DDL operations. For schema changes, the user typically needs CREATE, ALTER, and DROP permissions. Verify IAM roles for cloud databases like AWS RDS or Google Cloud SQL.

### Next steps

The following resources provide information for implementing rollback strategies and failure handling:

* Go to [Rollback DB Schema step](/database-devops/use-db-devops/deployment-pipeline-configuration/step-types/rollback-dbschema-step.md) to configure a rollback step that uses the `preStartTag` from this step.
* Go to [Rollback tags with Apply Schema step](/database-devops/use-db-devops/deployment-pipeline-configuration/rollback-and-failure-strategies/using-rollback-tags.md) to understand how tagging and rollback expressions work together.
* Go to [Failure strategies](/database-devops/use-db-devops/deployment-pipeline-configuration/rollback-and-failure-strategies/failure-strategies.md) to configure automated rollback on step failure.

{% @harness-feedback/feedback %}