Use native executors with Teradata

Last updated: June 9, 2026

The Teradata BTEQ native executor runs your SQL through the Teradata BTEQ client instead of the standard JDBC connection. This captures row counts, elapsed time, query results, and macro output that JDBC cannot return.

Before you begin

BTEQ client — Install the Teradata Tools and Utilities (TTU) package from the Teradata downloads page. Ensure bteq is available on your system PATH.

Procedure

Verify BTEQ is installed

Check that BTEQ is available on your system PATH.

which bteq

If BTEQ is not found, install the Teradata Tools and Utilities (TTU) package from the Teradata downloads page.

Configure your liquibase.properties

Your connection settings should already be in liquibase.properties from the connect guide. If BTEQ is not on your PATH, add the path explicitly:

liquibase.bteq.path=/opt/teradata/client/bin/bteq

If you haven't set up a connection yet, see Connect to Teradata with Liquibase Using TD2 Authentication or Connect to Teradata with Liquibase Using LDAP Authentication before continuing.

Add runWith:bteq to a changeset

Add runWith:bteq to the changeset header in your changelog file.

Be sure to:

Replace your_table with your actual Teradata table name

--liquibase formatted sql

--changeset dba:validate-counts runWith:bteq
SELECT 'your_table' AS table_name, COUNT(*) AS row_count FROM your_table;

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
    xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
        http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd">
    <changeSet id="validate-counts" author="dba" runWith="bteq">
        <sql>SELECT 'your_table' AS table_name, COUNT(*) AS row_count FROM your_table;</sql>
    </changeSet>
</databaseChangeLog>

databaseChangeLog:
  - changeSet:
      id: validate-counts
      author: dba
      runWith: bteq
      changes:
        - sql:
            sql: SELECT 'your_table' AS table_name, COUNT(*) AS row_count FROM your_table;

{
  "databaseChangeLog": [
    {
      "changeSet": {
        "id": "validate-counts",
        "author": "dba",
        "runWith": "bteq",
        "changes": [
          {
            "sql": {
              "sql": "SELECT 'your_table' AS table_name, COUNT(*) AS row_count FROM your_table;"
            }
          }
        ]
      }
    }
  ]
}

--liquibase formatted sql

--changeset dba:validate-counts runWith:bteq
SELECT 'your_table' AS table_name, COUNT(*) AS row_count FROM your_table;

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
    xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
        http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd">
    <changeSet id="validate-counts" author="dba" runWith="bteq">
        <sql>SELECT 'your_table' AS table_name, COUNT(*) AS row_count FROM your_table;</sql>
    </changeSet>
</databaseChangeLog>

databaseChangeLog:
  - changeSet:
      id: validate-counts
      author: dba
      runWith: bteq
      changes:
        - sql:
            sql: SELECT 'your_table' AS table_name, COUNT(*) AS row_count FROM your_table;

{
  "databaseChangeLog": [
    {
      "changeSet": {
        "id": "validate-counts",
        "author": "dba",
        "runWith": "bteq",
        "changes": [
          {
            "sql": {
              "sql": "SELECT 'your_table' AS table_name, COUNT(*) AS row_count FROM your_table;"
            }
          }
        ]
      }
    }
  ]
}

Run liquibase update

Be sure to:

Replace validate-deployment.sql with your changelog filename

liquibase update --changelog-file=validate-deployment.sql

The output includes row counts and query results:

Running Changeset: validate-deployment.sql::validate-counts::dba
[INFO] Executing with the 'bteq' executor

[INFO] *** Query completed. 2 rows found. 2 columns returned.
[INFO] *** Total elapsed time was 1 second.

Changeset validate-deployment.sql::validate-counts::dba ran successfully

Troubleshooting

BTEQ not found

Error:

ERROR: BTEQ executable not found in PATH

Cause: The BTEQ client is not installed or not on your system PATH.

Solution:

1. Verify BTEQ is installed: which bteq

2. If BTEQ is installed in a non-standard location, configure the path explicitly: liquibase.bteq.path=/opt/teradata/client/bin/bteq