dataform-sqlx-lint

A convention linter for Dataform .sqlx files. SQL linters (sqlfluff) check the SQL body; dataform compile checks syntax. Neither sees the config-block and project conventions that keep a Dataform repo healthy — this tool does.

Zero dependencies (Python ≥ 3.11 standard library only). Designed for pre-commit.

pip install dataform-sqlx-lint

Rules

Why E010 matters: columns: {} is what Dataform writes to BigQuery column descriptions — the metadata data catalogs, BI tools, and AI/conversational analytics agents read. Partial blocks leave silent gaps.

Usage

dataform-sqlx-lint definitions/output/my_table.sqlx [...]
# exit 0 = clean or warnings only; 1 = errors

Run from the repo root so --definitions-root (default ./definitions) can index ${ref()} targets for E010's star-resolution.

pre-commit

repos:
  - repo: https://github.com/acuantia/dataform-sqlx-lint
    rev: v0.1.0
    hooks:
      - id: dataform-sqlx-lint

Configuration

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

schema_suffixes = ["_prod", "_dev"]        # E003 suffix list ([] disables)
documented_types = ["table", "view", "incremental", "declaration"]  # E002
coverage_paths = ["definitions/output/"]   # E010 scope; empty = everywhere
enable = ["E005", "W008"]                  # switch on opt-in rules
disable = ["E004"]                         # switch off default rules
foreign_key_paths = ["definitions/output/"] # E011 scope; empty = rule off
foreign_key_hint = "includes/keys.js"      # named in E011's message

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

See examples/acuantia.sqlx-lint.toml for a complete real-world config.

Suppressing findings

from `proj.raw_api.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.
• Declarations are exempt from E003/E004 deliberately: raw source datasets legitimately carry environment-suffixed names, and Dataform requires name: on declarations.
• Rule codes are stable; gaps in the numbering are historical.

Agent Skill

skills/dataform-sqlx-lint/ contains an Agent Skill — instructions that teach AI coding agents (Claude Code, Gemini CLI, Cursor, or any tool supporting the open skills format) to run this linter on every .sqlx file they create or modify. Install it by copying the folder into your agent's skills directory — or paste one of the ready-made prompts in skills/dataform-sqlx-lint/INSTALL_PROMPTS.md and let the agent install itself.

Development

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

License

MIT — see LICENSE.