SQL quality with DBLift: catch issues before production

Not every migration problem appears only at apply time. Teams also need to catch risky SQL, inconsistent naming, and policy violations before a pipeline reaches a shared database.

DBLift separates two validation paths:

In the open-source package (pip install "dblift[cli,analysis]", 4.11.0 or later), validate-sql needs no licence. Commercial 4.6.0 is built on dblift 4.10.0 and still needs a Pro licence for validate-sql. Pro: a custom --rules-file, --rules security, --rules schema. Enterprise: named profiles, the best_practices, performance and naming packs, and individual rule IDs. There is no performance analyser on OSS. Python migration files are not analyzed by validate-sql.

Run validate-sql locally

OSS (pip install "dblift[cli,analysis]" 4.11.0 or later). Without --files, the command reads the V and R scripts in the migration directories. --files takes files, not directories. A positional path needs a licence:

dblift validate-sql --dialect postgresql --format json
dblift validate-sql --files migrations/*.sql --dialect postgresql --format json

Pro. --fail-on is not an OSS flag:

dblift validate-sql --dialect postgresql --fail-on warning

Enterprise. Named profiles and a positional path need a licence. --rules naming and --rules performance are Enterprise packs; --rules security is Pro:

dblift validate-sql migrations/ \
  --profile enterprise \
  --rules naming,performance,security \
  --fail-on warning

Add team-specific rules

Layer your own policy in .dblift_rules.yaml:

rules:
  - name: no_truncate_in_migrations
    type: pattern
    prohibit: TRUNCATE
    message: TRUNCATE statements are not allowed in migrations
    severity: error

  - name: audit_columns_required
    type: presence
    target: table
    must_have_columns: [created_at, updated_at]
    message: Tables should include audit columns
    severity: warning

A pattern rule matches raw SQL text with prohibit or regex. A presence rule parses each CREATE TABLE and checks the column list, so it does not trip on a comment or a string literal.

Pro. Run with the rules file. --rules-file and --fail-on are Pro:

dblift validate-sql migrations/ \
  --dialect postgresql \
  --rules-file .dblift_rules.yaml \
  --fail-on warning

Produce CI-friendly output

Generate SARIF for code scanning workflows:

dblift validate-sql migrations/ \
  --dialect postgresql \
  --profile enterprise \
  --format sarif \
  --output artifacts/validate-sql.sarif

Emit GitHub Actions annotations in a pull-request job:

dblift validate-sql migrations/ \
  --dialect postgresql \
  --profile enterprise \
  --format github-actions \
  --fail-on warning

The GitHub Action runs the same command. In the open-source package (pip install "dblift[cli,analysis]", 4.11.0 or later), validate-sql needs no licence. Commercial 4.6.0 still needs a Pro licence. This example passes --profile enterprise, which needs Enterprise, and a positional path, which needs a licence. The arguments go through args:

- name: Validate SQL offline
  uses: dblift/action@v1
  with:
    packages: 'dblift[cli,analysis,postgresql] dblift-enterprise'
    args: >-
      validate-sql migrations/
      --dialect postgresql
      --profile enterprise
      --format github-actions
      --fail-on warning

No database is needed for this step, so it runs on every pull request before any integration job starts.

How this fits the release path

A practical pipeline often keeps both checks:

1. Pull request — validate-sql for offline policy and SARIF retention
2. Integration job — validate against an ephemeral database for checksum and history integrity
3. Enterprise release — plan and preflight with snapshot models before migrate

That split lets DBLift support fast feedback early in CI without pretending offline lint replaces database-backed validation.

See the SQL validation docs, the CI/CD guide, and report examples for current output formats.