What it is

SQLMesh is an open-source Python data transformation framework released under Apache-2.0. It lives in the data engineering and analytics ecosystem, where teams build, test, and deploy SQL or Python transformations. The project is under the Linux Foundation umbrella and is described as backwards compatible with dbt.

It addresses the cost and risk of changing large pipelines. Data teams need to know how a model change affects downstream tables, whether an incremental load is correct, and whether a change can deploy safely without rebuilding every table. SQLMesh aims to provide visibility and control during planning, testing, and deployment.

Key capabilities

• SQLMesh provides virtual data environments, letting users create isolated development environments without separate warehouse copies.
• It uses a plan and apply workflow, similar to Terraform, so users can inspect potential impact before applying changes.
• It generates and runs unit tests from live queries, with YAML files that define model inputs and expected outputs.
• It tracks modified data and runs only necessary transformations for incremental models, avoiding repeated builds of unchanged tables.
• It transpiles SQL between dialects, supports column-level lineage, table diffs, automated audits, and a GitHub CI/CD bot.

Who uses it and how

• Data teams use it to develop and deploy SQL or Python transformations in dbt-compatible workflows.
• Users employ virtual environments, plan/apply reviews, and table diffs to test changes and compare production with development.
• Teams use the GitHub CI/CD bot to automate review and blue-green deployments, and teams running incremental models rely on modified-data tracking and audits.

Getting started

The README says to install SQLMesh from PyPI, and the documentation shows CLI commands such as sqlmesh create_test and sqlmesh test. It also mentions a VSCode extension and a GitHub CI/CD bot for review and deployment.

When to use it — and when not to

SQLMesh is useful when a team wants dbt-compatible workflows with explicit change planning, isolated environments, incremental correctness, and SQL dialect flexibility. It is less suitable when a project needs only a simple SQL runner and does not want a plan/apply model. The provided facts do not list a hosted service or specific self-hosted infrastructure requirements, and the project lists 304 open issues, so teams should confirm integration needs and current limitations before deployment.

sqlmesh create_test tcloud_demo.stg_payments --query tcloud_demo.seed_raw_payments "select * from tcloud_demo.seed_raw_payments limit 5"

# run the unit test
sqlmesh test

MODEL (
  name tcloud_demo.stg_payments,
  cron '@daily',
  grain payment_id,
  audits (UNIQUE_VALUES(columns = (
      payment_id
  )), NOT_NULL(columns = (
      payment_id
  )))
);

SELECT
    id AS payment_id,
    order_id,
    payment_method,
    amount / 100 AS amount, /* `amount` is currently stored in cents, so we convert it to dollars */
    'new_column' AS new_column, /* non-breaking change example  */
FROM tcloud_demo.seed_raw_payments

test_stg_payments:
model: tcloud_demo.stg_payments
inputs:
    tcloud_demo.seed_raw_payments:
      - id: 66
        order_id: 58
        payment_method: coupon
        amount: 1800
      - id: 27
        order_id: 24
        payment_method: coupon
        amount: 2600
      - id: 30
        order_id: 25
        payment_method: coupon
        amount: 1600
      - id: 109
        order_id: 95
        payment_method: coupon
        amount: 2400
      - id: 3
        order_id: 3
        payment_method: coupon
        amount: 100
outputs:
    query:
      - payment_id: 66
        order_id: 58
        payment_method: coupon
        amount: 18.0
        new_column: new_column
      - payment_id: 27
        order_id: 24
        payment_method: coupon
        amount: 26.0
        new_column: new_column
      - payment_id: 30
        order_id: 25
        payment_method: coupon
        amount: 16.0
        new_column: new_column
      - payment_id: 109
        order_id: 95
        payment_method: coupon
        amount: 24.0
        new_column: new_column
      - payment_id: 3
        order_id: 3
        payment_method: coupon
        amount: 1.0
        new_column: new_column

mkdir sqlmesh-example
cd sqlmesh-example
python -m venv .venv
source .venv/bin/activate
pip install 'sqlmesh[lsp]' # install the sqlmesh package with extensions to work with VSCode
source .venv/bin/activate # reactivate the venv to ensure you're using the right installation
sqlmesh init # follow the prompts to get started (choose DuckDB)

mkdir sqlmesh-example
cd sqlmesh-example
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install 'sqlmesh[lsp]' # install the sqlmesh package with extensions to work with VSCode
.\.venv\Scripts\Activate.ps1 # reactivate the venv to ensure you're using the right installation
sqlmesh init # follow the prompts to get started (choose DuckDB)