sqlanvil-sqlx-lint

A convention linter for SQLAnvil .sqlx files. SQL linters (sqlfluff) check the SQL body; sqlanvil compile checks syntax and sqlanvil validate checks against the warehouse. None of them see the config-block and project conventions that keep a sqlanvil repo healthy, and several Dataform habits that sqlanvil silently ignores or fails on at run time. This tool does, in milliseconds, with no warehouse connection.

Zero dependencies (Python ≥ 3.11 standard library only). Designed for pre-commit. Warehouse-aware: PostgreSQL, Supabase, MySQL/MariaDB, and BigQuery-target projects.

pip install sqlanvil-sqlx-lint

Forked from acuantia/dataform-sqlx-lint (MIT), which was extracted from a production Dataform repository.

Rules

Conventions

Why E002/E010 matter: sqlanvil writes description: and columns: {} into the warehouse catalog (COMMENT ON TABLE / COMMENT ON COLUMN on Postgres, table and column descriptions on BigQuery). That is the metadata data catalogs, BI tools, and AI analytics agents read. Partial blocks leave silent gaps.

sqlanvil deltas

The places where a Dataform/BigQuery habit produces a sqlanvil project that compiles but does the wrong thing. The first three are failures no compiler catches.

Usage

sqlanvil-sqlx-lint definitions/outputs/my_table.sqlx [...]
# exit 0 = clean or warnings only; 1 = errors; 2 = bad config

Run from the project root. The target warehouse is read from workflow_settings.yaml there (warehouse: postgres|supabase|mysql|bigquery), and --definitions-root (default ./definitions) is indexed so ${ref()} targets resolve for E010's star-resolution. Override with --warehouse or the warehouse config key; the default with nothing configured is postgres.

pre-commit

repos:
  - repo: https://github.com/SQLAnvil/sqlanvil-sqlx-lint
    rev: v0.2.0
    hooks:
      - id: sqlanvil-sqlx-lint

Configuration

.sqlx-lint.toml in the project root, or a [tool.sqlx-lint] table in pyproject.toml (the standalone file wins). All keys optional:

warehouse = "postgres"                     # else workflow_settings.yaml, else postgres
schema_suffixes = ["_prod", "_dev", "_test"]  # E003 suffix list ([] disables)
documented_types = ["table", "view", "incremental", "declaration"]  # E002
coverage_paths = ["definitions/outputs/"]  # E010 scope; empty = everywhere
allowed_schemas = ["extensions"]           # E006 may reference these directly
enable = ["E005", "W008"]                  # switch on opt-in rules
disable = ["E004"]                         # switch off default rules

[[dir_policies]]                           # E007 (repeatable)
path_contains = "definitions/outputs/"
require_prefix = "rpt_"
require_types = ["table", "incremental"]
severity = "error"                         # or "warning"

See examples/sqlx-lint.toml for a complete sources → intermediate → outputs layout. System catalogs (pg_catalog, information_schema, mysql, sys, …) are always allowed.

Adopting on an existing project

A migrated repository will be loud on the first run: E002 on every undocumented model and E010 wherever documentation is partial. Adopt in layers rather than suppressing:

1. Start with disable = ["E002", "E010"] so the S-series and E006 findings, which are actual defects, land first.
2. Re-enable E002 and scope E010 with coverage_paths to the BI-facing layer.
3. Widen coverage_paths as documentation catches up.

Suppressing findings

from public.legacy_events -- sqlx-lint: disable=E006 (declaration repoints at cutover)

or file-wide, anywhere in the file:

-- sqlx-lint: disable-file=E006

Suppress with a reason, sparingly — the convention is usually the fix.

Design notes

• Conservative by construction: the SQL projection parser only claims column names it can determine (aliases, simple identifiers, resolvable select *); anything ambiguous is skipped, so E010 never false-flags.
• E006 looks only at table positions (FROM, JOIN, INTO, UPDATE), ignores FROM used as function syntax (extract(dow from d.date)), function calls (public.my_func(1)), and anything inside ${…}.
• S102 understands sqlanvil's text: ; inside string literals, $$ dollar-quoted PL/pgSQL bodies, and ${…} JavaScript regions never count; a single trailing ; is fine.
• Declarations are exempt from E003/E004 deliberately: raw source schemas legitimately carry environment-suffixed names, and name: is required.
• Rule codes are stable; gaps in the numbering are historical.

Agent Skill

The sqlanvil-sqlx-lint Agent Skill teaches AI coding agents (Claude Code, Codex CLI, Cursor, or any tool supporting the open Agent Skills format) to run this linter on every .sqlx file they create or modify. It lives with the other SQLAnvil skills:

npx skills add SQLAnvil/agent-skills

Source: https://github.com/SQLAnvil/agent-skills

Development

python3 -m venv .venv && .venv/bin/pip install -e . pytest
.venv/bin/pytest        # 103 tests

License

MIT — see LICENSE.