> 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/sqlfile.md).

# What is sqlFile?

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

The **`sql`** tag allows you to embed raw SQL statements directly within a changeset, instead of referencing external .sql files. This is particularly useful for small, declarative changes or when working with simple SQL that does not require reuse across environments.

The sql change type supports multi-line SQL statements using delimiters such as `;` or `GO`, and allows inline comments in the following formats:

* Multi-line comments enclosed within `/* ... */`
* Single-line comments prefixed by `--`

It also offers support for statement splitting via the `splitStatements` attribute and database-specific targeting using the dbms attribute. For Example:

```yaml
databaseChangeLog:
  - changeSet:
      id: sql-example
      author: john-deo
      changes:
        - sql:
            dbms: '!h2, oracle, mysql'
            endDelimiter: \nGOs
            splitStatements: true
            sql: |
              insert into person (name) values ('Bob')
```

The **`sqlFile`** tag in Harness Database DevOps (which uses Liquibase under the hood) allows you to execute raw SQL stored in external `.sql` files as part of a [changeset](/database-devops/use-db-devops/reference/glossary/changeset.md). This is especially useful for large SQL scripts, vendor-specific features, or when reusing validated scripts across environments.

Here’s a sample usage within a changeset:

```yaml
databaseChangeLog:
  - changeSet:
      id: run-import-script
      author: db.team
      changes:
        - sqlFile:
            path: scripts/init_data.sql
            splitStatements: true
            stripComments: true
            encoding: UTF-8
```

### Key attributes of `sqlFile` <a href="#key-attributes-of-sqlfile" id="key-attributes-of-sqlfile"></a>

The `sqlFile` tag has the following key attributes:

| Attribute         | Description                                                                     | Required |
| ----------------- | ------------------------------------------------------------------------------- | -------- |
| `path`            | Relative or absolute path to the SQL file to be executed.                       | ✅        |
| `splitStatements` | Whether the file should be split into individual SQL statements. Default: true. | ❌        |
| `stripComments`   | Strips SQL comments before execution. Default: false.                           | ❌        |
| `encoding`        | Character encoding of the file (e.g., `UTF-8`).                                 | ❌        |
| `endDelimiter`    | Defines custom delimiter for statements (if `splitStatements` is true).         | ❌        |

### Why use sqlFile <a href="#why-use-sqlfile" id="why-use-sqlfile"></a>

Use `sqlFile` when you need to:

* Maintain large scripts outside the changelog for better readability and reuse.
* Reuse approved SQL written by DBAs or generated by third-party tools.
* Improve traceability by linking SQL execution to a versioned [changeset](/database-devops/use-db-devops/reference/glossary/changeset.md) with author and context.
* Enforce auditability via Harness pipelines, approvals, and deployment logs.

### Best practices in Harness Database DevOps <a href="#best-practices-in-harness-database-devops" id="best-practices-in-harness-database-devops"></a>

Follow these recommendations when using `sqlFile` in your changelogs:

* Place `.sql` files in version control alongside your changelogs.
* Pair each sqlFile with a rollback block if the operation is reversible.
* Use context, labels, and logicalFilePath for environment-specific execution and clarity.

#### Example with rollback <a href="#example-with-rollback" id="example-with-rollback"></a>

```yml
- changeSet:
    id: seed-customers
    author: alice.dev
    context: dev
    changes:
      - sqlFile:
          path: seed/customers.sql
          splitStatements: true
    rollback:
      sqlFile:
        path: rollback/delete_customers.sql
```

This example shows how to use `sqlFile` to seed data in a development environment, with a corresponding rollback script to remove the seeded data if needed.

### When to use sql vs sqlFile <a href="#when-to-use-sql-vs-sqlfile" id="when-to-use-sql-vs-sqlfile"></a>

| Use Case                        | Use `sql`        | Use `sqlFile`                       |
| ------------------------------- | ---------------- | ----------------------------------- |
| Small or simple SQL             | ✅                | N/A                                 |
| SQL must be embedded            | ✅                | N/A                                 |
| Reusing large or vendor scripts | N/A              | ✅                                   |
| Managing external files         | N/A              | ✅                                   |
| Need full CI/CD preview/audit   | ✅ *(in Harness)* | ✅ *(full preview + rollback logic)* |

Both tags support rollback, split statements, and comment stripping, but sqlFile is generally preferred for large or externalized logic, especially in Harness where preview, approval, and audit workflows are deeply integrated.

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

The sqlFile tag enables teams to execute and manage raw SQL in a structured, controlled, and auditable way through Harness Database DevOps. It bridges manual DBA processes with modern CI/CD pipelines, empowering teams to scale database automation without sacrificing control or compliance.

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

* Learn about [Changelogs](/database-devops/use-db-devops/reference/glossary/changelog.md) to understand how changesets are grouped and executed in sequence.
* Explore [Changesets](/database-devops/use-db-devops/reference/glossary/changeset.md) to understand how individual database changes are defined and managed.

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

#### 1. What is the `sqlFile` tag used for in Harness Database DevOps? <a href="#id-1-what-is-the-sqlfile-tag-used-for-in-harness-database-devops" id="id-1-what-is-the-sqlfile-tag-used-for-in-harness-database-devops"></a>

The `sqlFile` tag lets you execute raw SQL stored in external files as part of a Liquibase changeset. In Harness Database DevOps, it is used to version and run large SQL scripts, such as data imports or vendor-specific DDL, within a CI/CD pipeline, while retaining auditability and rollback options.

#### 2. Can I preview the SQL inside a `sqlFile` before deployment? <a href="#id-2-can-i-preview-the-sql-inside-a-sqlfile-before-deployment" id="id-2-can-i-preview-the-sql-inside-a-sqlfile-before-deployment"></a>

Yes. Harness automatically previews the contents of `sqlFile` executions during pull requests and pipeline runs. This visibility ensures DBAs and reviewers can validate the exact SQL that will be executed, reducing risk and improving governance.

#### 3. How does rollback work with `sqlFile` in Harness? <a href="#id-3-how-does-rollback-work-with-sqlfile-in-harness" id="id-3-how-does-rollback-work-with-sqlfile-in-harness"></a>

To enable rollback, you can define a companion `sqlFile` under the `rollback` section of the changeset. Harness will automatically trigger this rollback SQL if the deployment fails or is manually rolled back, ensuring consistent and safe recovery.

#### 4. Where should I store `.sql` files used by `sqlFile`? <a href="#id-4-where-should-i-store-sql-files-used-by-sqlfile" id="id-4-where-should-i-store-sql-files-used-by-sqlfile"></a>

Store your `.sql` files in version control alongside your changelogs. This ensures traceability, supports GitOps workflows, and allows Harness to track file changes, validate checksums, and enforce pipeline approvals.

#### 5. Is `sqlFile` better than inline SQL in Liquibase changesets? <a href="#id-5-is-sqlfile-better-than-inline-sql-in-liquibase-changesets" id="id-5-is-sqlfile-better-than-inline-sql-in-liquibase-changesets"></a>

Use `sqlFile` when:

* The SQL is too large or complex for inline syntax.
* You’re reusing scripts written or approved by DBAs.
* You need to preserve dialect-specific formatting.

For smaller, portable, or declarative changes, inline YAML or XML is preferred.

#### 6. When should I use the inline `sql` tag instead of `sqlFile`? <a href="#id-6-when-should-i-use-the-inline-sql-tag-instead-of-sqlfile" id="id-6-when-should-i-use-the-inline-sql-tag-instead-of-sqlfile"></a>

Use the inline `sql` tag when your SQL statement is simple, small, and does not require reuse across multiple environments. It’s ideal for one-off DDL or DML operations that are easily readable and maintainable directly within the changelog. Inline SQL is also useful when you want to minimize file dependencies or when working in early-stage development environments. For larger, reusable, or vendor-specific scripts, `sqlFile` is recommended.

#### 7. Does Harness support approvals for `sqlFile` execution? <a href="#id-7-does-harness-support-approvals-for-sqlfile-execution" id="id-7-does-harness-support-approvals-for-sqlfile-execution"></a>

Absolutely. Harness integrates approval gates into your database pipeline. Any changeset using `sqlFile` can be subjected to review and approval workflows, ensuring that all SQL changes are vetted before execution in sensitive environments like staging or production.