How to Get Started with SQLMesh

What SQLMesh Is and Why It Matters

SQLMesh is an open-source SQL transformation framework for analysts and data engineers who build data pipelines against a warehouse or database. The project was developed by Tobiko Data, acquired by Fivetran in September 2025, and donated to the Linux Foundation on March 25, 2026. That governance transfer moves project direction to a neutral body, removing any single vendor's control over the roadmap.

The two capabilities that differentiate SQLMesh from dbt, its closest competitor, are virtual data environments and column-level lineage computed at compile time. Virtual environments let development runs reference production data without duplicating it, eliminating the warehouse costs that dbt dev runs generate. Column-level lineage is computed by the SQLGlot parser as part of every plan, with no catalog integration or additional tooling required.

Performance benchmarks show SQLMesh executing approximately 9 times faster and at proportionally lower cost than dbt Core for equivalent workloads. The reason is incremental execution: SQLMesh tracks which models changed and re-runs only those, rather than recompiling the entire DAG on every invocation.

For ops managers and analysts who build reporting pipelines in SQL, SQLMesh offers concrete improvements in speed, cost, and development safety with a migration path from dbt that requires minimal rewriting.

Installing SQLMesh

Python 3.8 or newer is required. A virtual environment is recommended.

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install sqlmesh

Verify the install:

sqlmesh --version

As of April 2026, the current version is in the 0.140.x range. For VS Code users who want inline SQL validation and autocompletion, install the language server variant:

pip install "sqlmesh[lsp]"

After installation, restart VS Code and open a .sql file inside a SQLMesh project directory. The language server activates automatically and provides real-time query validation and suggestions.

Initializing a Project

SQLMesh ships a scaffold generator that creates a working project structure. The fastest way to evaluate it locally is with DuckDB, which requires no external database credentials.

mkdir analytics_project && cd analytics_project
sqlmesh init duckdb

This creates four key directories: models/ for SQL or Python transformation models, audits/ for data quality assertions that run after model execution, macros/ for reusable Jinja or Python macros, and config.yaml for database connection, scheduling, and project settings.

The generated config.yaml for DuckDB looks like:

gateways:
  local:
    connection:
      type: duckdb
      database: db.db
model_defaults:
  dialect: duckdb
  start: 2024-01-01

To connect to a production warehouse, change the type field to snowflake, bigquery, redshift, or postgres and add the relevant credentials. The full connection reference is in the SQLMesh documentation at sqlmesh.readthedocs.io.

Writing Your First Model

A SQLMesh model is a .sql file in the models/ directory. The structural difference from dbt is the MODEL (...) block at the top, which replaces dbt's {{ config(...) }} Jinja macro:

MODEL (
  name analytics.orders_summary,
  kind FULL
);

SELECT
  customer_id,
  COUNT(*) AS order_count,
  SUM(amount) AS total_spend
FROM analytics.raw_orders
GROUP BY 1

kind FULL rebuilds the model completely on every run. For large fact tables, INCREMENTAL_BY_TIME_RANGE is more efficient:

MODEL (
  name analytics.daily_revenue,
  kind INCREMENTAL_BY_TIME_RANGE (
    time_column event_date
  ),
  cron '@daily'
);

SELECT
  event_date,
  SUM(revenue) AS total_revenue
FROM analytics.raw_events
WHERE event_date BETWEEN @start_date AND @end_date
GROUP BY 1

The @start_date and @end_date variables are populated automatically at runtime based on which date ranges have already been processed. SQLMesh tracks historical state and fills only missing intervals, eliminating full-table rewrites for time-series models.

Planning and Applying Changes

SQLMesh separates the plan step from execution, similar to how Terraform works. You preview exactly what will change before anything runs.

sqlmesh plan

The CLI prints a categorized diff: new models, modified models, and unchanged models. For incremental models it shows which date ranges will be backfilled. Apply the plan:

sqlmesh plan --apply

For development work, name the environment explicitly:

sqlmesh plan dev

SQLMesh creates a virtual dev environment that references production data without copying tables. Analysts can test new model logic against real production-scale data at near-zero cost. When ready to promote, run sqlmesh plan prod to push dev changes to production with a full diff review.

Migrating from dbt

If your team has an existing dbt project, SQLMesh can import it with a single command:

sqlmesh init --from-dbt

This reads dbt_project.yml, profiles.yml, and existing .sql model files and converts them to SQLMesh format. Most SQL logic carries over unchanged. The main adjustment is replacing {{ config(...) }} blocks with MODEL (...) syntax.

Jinja templating continues to work in SQLMesh. Macros, variable references, and {{ ref() }} calls are all supported. Teams can migrate incrementally, running both frameworks in parallel and porting models one at a time until output parity is confirmed.

Built-in Data Quality Audits

SQLMesh includes an audit system that runs SQL assertions after each model executes. Create a file in the audits/ folder:

AUDIT (name assert_no_negative_revenue);

SELECT *
FROM analytics.daily_revenue
WHERE total_revenue < 0

If the query returns any rows, the pipeline halts before downstream models run. Audits can also be declared inline in the MODEL (...) block using the AUDITS parameter, keeping data quality checks colocated with the model they test. For teams currently using a separate tool for basic null and range checks, SQLMesh audits cover the same ground with no additional installation.

The Browser UI and Column-Level Lineage

SQLMesh ships a local browser interface:

sqlmesh ui

This starts a web app at http://localhost:8000 with the full DAG visualization, column-level lineage graph, run history, and audit results. The column-level lineage view traces exactly which source columns feed which output columns through every intermediate model. For analysts running financial or operational reports where auditability matters, this removes the need for a separate data catalog or manual SQL tracing.

Scheduling and Orchestration

For local and development use, set the cron field on any model in the MODEL (...) block and run sqlmesh run to trigger the built-in scheduler. Standard cron expressions, @daily, and @hourly are all supported.

For production orchestration, SQLMesh provides official operators for Airflow, Prefect, and Dagster. GitHub Actions integration runs sqlmesh plan --apply automatically on pull request merge, keeping transformations in sync with code changes without manual deployment steps.

Practical Summary

SQLMesh installs in under two minutes, starts with local DuckDB and no infrastructure, and migrates existing dbt projects with a single command. Virtual environments eliminate dev-run compute costs, built-in audits replace a category of tooling, and column-level lineage ships as a default feature. For teams on dbt who have hit execution cost or speed limits, SQLMesh is the most practically grounded migration target available in 2026, now with Linux Foundation governance and active commercial backing from Fivetran.

If you want to skip pipeline configuration entirely and analyze uploaded CSV or connected database data through plain-English prompts, VSLZ handles end-to-end data transformation and statistical analysis from a file upload with no model setup required.