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

[[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.

Development

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

License

MIT — see LICENSE.