SQLMesh

Create, open, browse, plan, run, test, render, and trace SQLMesh models directly from Arris without leaving the editor.

Creating a project

Start a new SQLMesh project from the welcome screen. Under NEW PROJECT, click the SQLMesh card (Sample SQLMesh project). Arris asks for a Project name and a Location (use the folder button to browse), then Create scaffolds the project in a new folder under that location.

The scaffold creates a models/ folder and a config.yaml wired to a local DuckDB gateway, so the project is usable with no external database. Arris opens the project as soon as it is created, and you can bind a real database later from the Connection picker.

The Arris welcome screen NEW PROJECT row with three cards: Empty project, dbt, and SQLMesh (Sample SQLMesh project) — The welcome screen's NEW PROJECT cards — pick SQLMesh to scaffold a sample SQLMesh project.

Opening a project

To open an existing project, use OPEN EXISTING on the welcome screen and pick the folder that contains your SQLMesh config.yaml (or config.yml). Arris recognizes that marker, scans the project, and reads your models. Once detected, a SQLMesh view becomes available in the left sidebar.

SQLMesh calls its own CLI under the hood for plan, run, test, and render. The detected CLI version is shown on the config card; if sqlmesh is not on your PATH, point the sqlmesh binary field at your install.

The SQLMesh config pane

The SQLMesh view opens with a collapsible status card at the top: the sqlmesh badge shows the detected CLI version and the selected gateway, with a reload button to rescan. Expand it to configure how Arris invokes SQLMesh:

Setting	What it controls
Project	Which SQLMesh root to use, shown only when the folder contains more than one `config.yaml`.
Environment	The virtual environment to target, with its expiry date. A Promote to prod button promotes the current environment to `prod`.
Gateway	The gateway (database connection) to run against, read from `config.yaml` and shown as name (connection type).
sqlmesh binary	Path to the SQLMesh executable. Defaults to `sqlmesh` on your `PATH`; use the folder button to point at a specific install.
Connection	A database connection bound to the project, used to preview model data.

The card also has a one-click shortcut to open config.yaml in the editor. If the SQLMesh CLI check fails, the error is shown inline with a Show full error toggle. Your project, environment, gateway, and binary selections persist across sessions.

The SQLMesh config pane expanded, showing the sqlmesh 0.235.4 badge with the postgres gateway, the Project, Gateway, and sqlmesh binary fields, a config.yaml shortcut, the Connection picker (prod_postgres), and a Plan run button at the bottom — The SQLMesh config pane — CLI version and gateway badge, Project / Gateway / sqlmesh binary fields, the config.yaml shortcut, and the Connection picker, with the Plan run button below.

The SQLMesh view

When Arris detects a SQLMesh project, the left sidebar header shows a segmented control to switch the files pane between Project (the raw file tree) and SQLMesh. Click SQLMesh to open the model tree, which groups models by kind with a count per section:

Section	What it holds
Incremental	Models with an `INCREMENTAL_BY_TIME_RANGE` or `INCREMENTAL_BY_UNIQUE_KEY` kind, which load only new or changed rows on each run.
Full	Models with a `FULL` kind, fully rebuilt from scratch every run. This is also the fallback bucket for any model whose kind Arris does not recognize.
SCD Type 2	Slowly changing dimension models (`SCD_TYPE_2_BY_TIME` / `SCD_TYPE_2_BY_COLUMN`) that track row history over time.
Views	Models with a `VIEW` kind, materialized as a database view rather than a table.
Seeds	Models with a `SEED` kind, loaded from a static CSV file checked into the project.
External	Models with an `EXTERNAL` kind, describing tables managed outside SQLMesh so their columns and lineage are known.
Python	Models defined in Python with the `@model` decorator instead of SQL, grouped together regardless of their underlying kind.
Tests	SQLMesh test files (model unit tests) defined in YAML, listed in a separate section below the models.

Use the filter box to narrow the tree by name. Single-click a model to select it; double-click to open its file in the editor. Right-clicking a model opens its context menu.

Running commands

SQLMesh commands are available in two places. The run bar at the top of the SQLMesh view runs Plan, Run, and Test against the whole project as a split-button.

The second place is the SQLMesh toolbar in the editor: open a model and a sqlmesh section appears in the console toolbar with Plan, Test, Render, Lineage, and Preview. The split-button remembers the action you last picked as its primary button. Only Plan takes a selector field, which accepts the same graph syntax as dbt (+model, model+, wildcards, tag:) and maps to --select-model. Preview renders the model's SQL with a row limit and runs it against the bound connection; it is unavailable for Python models, which have no renderable SQL. For test files, the toolbar instead lets you run the test under the cursor or all tests in the file.

The editor toolbar for a SQLMesh model showing the sqlmesh: split-button set to Plan, with the dropdown open listing Plan, Test, Render, Lineage, and Preview alongside their keyboard shortcuts — The sqlmesh: split-button in the editor toolbar — Plan, Test, Render, Lineage, and Preview, each with a keyboard shortcut.

Environments

SQLMesh environments are virtual namespaces such as dev and prod. When the project has more than the default environment, an Environment dropdown appears in the config pane; switch the active environment there, and each one shows its expiry date. When a development environment is ready, Promote to prod promotes it so its changes become the production state. The active gateway determines which database the plan and run operations target.

Plans

A plan is the core of the SQLMesh workflow: it compares your local model definitions against the target environment and works out the changes and backfills needed. Running Plan in Arris invokes sqlmesh plan for the selected environment (and selector) and streams the full output to the command logs, so you can review the diff and the backfill plan inline.

Command logs

Every command's output streams into the Command logs panel at the bottom of the window, newest run on top. Each entry records the exact command, its status, duration, and timestamp, alongside the raw stdout/stderr with ANSI colors preserved. Filter entries with the search box or the status dropdown, and clear the history with the trash button. See Command logs for the full reference.

Rendering SQL

SQLMesh models use macros, references, and other expressions that make the raw SQL hard to read. Render compiles a model into its final SQL and opens a Compiled SQL preview alongside the editor, fully expanded with macros resolved and references substituted. The preview has buttons to recompile, copy the SQL, and close it, and it flags a Stale chip when you edit the model after rendering. If a render fails, the preview points you to the error in the command logs below.

A SQLMesh model open in the editor with the sqlmesh: toolbar set to Render, and a Compiled SQL panel alongside showing the model's final SQL with macros resolved and columns fully qualified — Render opens a Compiled SQL panel beside the model — macros resolved and references fully qualified, with Recompile, Copy, and Close controls in its header.

Lineage

Lineage opens a directed acyclic graph of the model's dependencies, rendered as a draggable node graph. The model you opened it from is tagged with a CURRENT badge. Click a column name in any node to trace its column-level lineage: Arris highlights that column and every upstream and downstream column it flows through, so you can follow a single field across models.

Depth — choose 1, 2, or 3 hops to control how far up and downstream the graph expands from the current model.
Orientation — flip the layout between Vertical and Horizontal with the orientation toggle.
Pan — drag the canvas background to move the viewport.
Zoom — scroll, or use the bottom-right controls, to zoom in and out.
Rearrange — drag any node to reposition it; layout otherwise arranges nodes automatically.
Open a node — double-click a node to focus that model.

Toggle the lineage view from the Lineage button in the SQLMesh toolbar while a model is open. The graph rebuilds from your current model definitions each time it is opened.

A SQLMesh column-level lineage graph with the Depth 1/2/3 selector and a Vertical orientation toggle, showing source public.customers feeding stg_customers (tagged CURRENT) and then dim_customers, with the first_name column highlighted across all three nodes — Column-level lineage — first_name highlighted from source through stg_customers (CURRENT) to dim_customers, with Depth and orientation controls at the top.