Skip to main content
This guide shows you how to connect your dbt Core project to SYNQ to track model runs, test results, and metadata changes.Prerequisites:
  • Admin access to your SYNQ workspace
  • Ability to modify your dbt orchestration tool (Airflow, GitHub Actions, etc.)
⏱️ Estimated time: 15 minutes
Using dbt Cloud? You can integrate directly through Settings → Integrations → Add Integration → dbt Cloud instead of following this guide.

​
Set up dbt Core integration

​
Create integration in SYNQ

  1. Navigate to Settings → Integrations → Add Integration
  2. Select dbt Core from the integration options

​
Configure integration settings

Integration name: Enter a descriptive name (e.g., Production dbt Core) Generate token: Click Create to generate your integration token. You’ll use this token with the synq-dbt tool to send artifacts securely to SYNQ. Git integration: Select your Git provider to link model changes to repository commits. This enables change tracking and lineage visualization. Relative path to dbt: If your dbt project isn’t in the repository root, specify the directory path (e.g., analytics/dbt/).

​
Manage integration tokens

Access token management through Settings → Integrations, then select your dbt Core integration and click Manage tokens.
dbt Core token management interface
From the token management screen, you can:
  • Create new tokens for different environments
  • Invalidate compromised tokens
  • Copy token snippets for easy integration
List of dbt Core integration tokens

​
Install synq-dbt

​
About synq-dbt

synq-dbt is a command-line wrapper that runs your existing dbt Core commands and automatically uploads artifacts to SYNQ. It’s version-agnostic — working with any dbt Core version by passing all arguments directly to your installed dbt — and integrates seamlessly with orchestration tools like Airflow, GitHub Actions, and Dagster. Collected artifacts:
  • manifest.json — Project structure and dependencies
  • run_results.json — Execution status and performance metrics
  • catalog.json — Complete data warehouse schema information
  • sources.json — Source freshness test results
How it works:
  1. Executes your locally installed dbt Core with all provided arguments (version-agnostic, passes arguments directly)
  2. Captures the original dbt exit code
  3. Reads your SYNQ_TOKEN environment variable
  4. Uploads artifacts from the target directory to SYNQ
  5. Returns the original dbt Core exit code, even if upload fails (preserving pipeline behavior and ensuring CI/CD reliability)

​
Installation methods

Choose the installation method that matches your dbt orchestration setup:

​
Airflow with DockerOperator

  1. Set environment variable: In Airflow UI, create a new environment variable SYNQ_TOKEN with your integration token.
  2. Update Dockerfile: 
ENV SYNQ_VERSION=v1.8.0
RUN wget -O /usr/bin/synq-dbt https://github.com/getsynq/synq-dbt/releases/download/${SYNQ_VERSION}/synq-dbt-amd64-linux && \
    chmod +x /usr/bin/synq-dbt
  1. Update your operator:
KubernetesPodOperator(
    env_vars={
        "SYNQ_TOKEN": Variable.get("SYNQ_TOKEN"),
        # For US region: "SYNQ_API_ENDPOINT": "https://api.us.synq.io"
    },
    cmds=["synq-dbt"],
    arguments=["build"],  # Your dbt command here
    # ... other configuration
)
Linking dbt models to Airflow tasks: To automatically link your dbt models with the Airflow tasks that execute them, see the Airflow + dbt Core Linking guide. This enables bidirectional visibility between your orchestration and data layers.

​
Airflow with dbt Plugin

  1. Set environment variable: Create SYNQ_TOKEN in Airflow UI.
  2. Install synq-dbt: 
export SYNQ_VERSION=v1.8.0
wget -O ./synq-dbt https://github.com/getsynq/synq-dbt/releases/download/${SYNQ_VERSION}/synq-dbt-amd64-linux
chmod +x ./synq-dbt && mv synq-dbt /usr/local/bin/synq-dbt
  1. Update DbtOperator:
dbt_run = DbtRunOperator(
    dbt_bin='synq-dbt',
    env={
        "SYNQ_TOKEN": Variable.get("SYNQ_TOKEN"),
        # For US region: "SYNQ_API_ENDPOINT": "https://api.us.synq.io"
    },
    # ... other configuration
)
For linking dbt models to Airflow tasks, see the Airflow + dbt Core Linking guide.

​
Dagster

  1. Configure environment: Add SYNQ_TOKEN=<your-token> to your .env file. For US region workspaces, also add SYNQ_API_ENDPOINT=https://api.us.synq.io.
  2. Update resources in definitions.py: 
resources = {
    "dbt": DbtCliResource(
        dbt_executable='synq-dbt', 
        project_dir=os.fspath(dbt_project_dir)
    ),
}
  1. Update assets in assets.py:
@dbt_assets(manifest=dbt_manifest_path)
def jaffle_shop_dbt_assets(context: AssetExecutionContext, dbt: DbtCliResource):
    dbt_target_path = Path('target')
    yield from dbt.cli(["build"], target_path=dbt_target_path, context=context).stream()

​
Docker

Add to your Dockerfile: 
ENV SYNQ_VERSION=v1.8.0
RUN wget -O /usr/bin/synq-dbt https://github.com/getsynq/synq-dbt/releases/download/${SYNQ_VERSION}/synq-dbt-amd64-linux && \
    chmod +x /usr/bin/synq-dbt

​
Linux/macOS

Download and install: 
# For Linux
export SYNQ_VERSION=v1.8.0
wget -O ./synq-dbt https://github.com/getsynq/synq-dbt/releases/download/${SYNQ_VERSION}/synq-dbt-amd64-linux

# For macOS
wget -O ./synq-dbt https://github.com/getsynq/synq-dbt/releases/download/${SYNQ_VERSION}/synq-dbt-arm64-darwin

# Make executable and move to PATH
chmod +x ./synq-dbt && mv synq-dbt /usr/local/bin/synq-dbt

# Set your token and test
export SYNQ_TOKEN=<your-token>
synq-dbt --version

​
Use synq-dbt

​
Basic usage

Replace your existing dbt Core commands with synq-dbt: 
# Instead of: dbt run --select finance --threads 5
synq-dbt run --select finance --threads 5

# Instead of: dbt test --select reports  
synq-dbt test --select reports

# Instead of: dbt build
synq-dbt build
All dbt Core arguments and options work exactly the same way.

​
Upload existing artifacts

If you have already generated dbt artifacts and want to upload them to SYNQ: 
export SYNQ_TOKEN=<your-token>
synq-dbt synq_upload_artifacts
Include dbt logs: 
dbt build | tee dbt.log
synq-dbt synq_upload_artifacts --dbt-log-file dbt.log

​
Token migration (v2 tokens)

If your SYNQ_TOKEN doesn’t start with st-, you’re using a legacy token that will be deprecated. Migrate to v2 tokens for improved security and performance.
Migration steps:
  1. Upgrade synq-dbt first (backward compatible):
export SYNQ_VERSION=v1.8.0  # or later
wget -O ./synq-dbt https://github.com/getsynq/synq-dbt/releases/download/${SYNQ_VERSION}/synq-dbt-amd64-linux
chmod +x ./synq-dbt && mv synq-dbt /usr/local/bin/synq-dbt
  1. Generate new v2 token through Settings → Integrations → Manage tokens
  2. Replace your SYNQ_TOKEN environment variable with the new token (starts with st-)
  3. Test the integration to ensure artifacts upload successfully
v2 tokens require synq-dbt v1.8.0 or later. Legacy tokens will continue working during the transition period.

​
Configuration options

Environment variables:
  • SYNQ_TOKEN — Your integration token (required)
  • SYNQ_TARGET_DIR — Artifact directory path (default: target/)
  • SYNQ_API_ENDPOINT — API endpoint for your region (required for US region)
Regional configuration:
EU region customers (default) don’t need to set SYNQ_API_ENDPOINT. US region customers must configure it.
For US region workspaces, set the API endpoint: 
export SYNQ_API_ENDPOINT=https://api.us.synq.io
For EU region workspaces (default), no additional configuration needed — the tool automatically uses https://developer.synq.io. Network requirements:
  • Allow outbound HTTPS traffic to dbtapi.synq.io:443 when using legacy token or old uploader.
  • Allow outbound HTTPS traffic to developer.synq.io:443 (EU region) or api.us.synq.io:443 (US region)
Data visibility:
  • Artifacts appear in SYNQ within minutes of upload under normal conditions
  • Failed uploads are logged and can be retried
  • Typical payload sizes range from several megabytes to tens of megabytes depending on project size
For advanced configuration options and troubleshooting, see the synq-dbt GitHub repository.