@codacy/tools-sqlfluff-4

Table of Contents

• Overview
• Updating patterns
• Updating the SQLFluff version
• Development
• Notes for maintainers

Overview

Multi-dialect SQL linter using SQLFluff. Uses the CLI execution strategy -- spawns sqlfluff lint --format json from a managed Python venv via spawnTool() and parses its JSON output.

Updating patterns

# Re-fetch pattern metadata from the Codacy API
pnpm prefetch

# Commit the result
git add src/patterns.json

The prefetch script calls packages/tools/scripts/fetch-patterns.mjs with the tool UUID to download pattern metadata from the Codacy API.

Pattern IDs follow the format SQLFluff_AL01_aliasing.table, SQLFluff_LT01_layout.spacing, etc. -- they include both the short code and the rule name.

Updating the SQLFluff version

1. Update preferredVersion in src/adapter.ts
2. Update the PIP_PACKAGES array with the new pinned version
3. Run pnpm prefetch to check for new/removed rules
4. Run pnpm test to verify compatibility
5. If the major version changes, create a new adapter package (sqlfluff-4/)

Development

pnpm build    # Build with tsup
pnpm test     # Run tests (requires sqlfluff in PATH or venv)

To install sqlfluff locally for testing:

pip install sqlfluff==4.3.0

Notes for maintainers

• Multi-dialect support: SQLFluff supports ANSI, PostgreSQL, MySQL, BigQuery, Snowflake, and many more SQL dialects. The generated config defaults to dialect = ansi. Users can override this via a local .sqlfluff config file.
• Python pip dependency: SQLFluff requires Python 3 as a runtime. The adapter uses an isolated venv at ~/.codacy/runtimes/SQLFluff/venv/ (keyed on the stable tool ID, not the package folder name, so a major bump keeps the venv and can upgrade it in place instead of orphaning it).
• Pattern ID mapping: SQLFluff's JSON output reports code (e.g. AL01) but Codacy pattern IDs include both code and name (e.g. SQLFluff_AL01_aliasing.table). The adapter builds a CODE_TO_PATTERN reverse lookup map from patterns.json at module initialization.
• Config generation: When patterns are enabled but no local config exists, the adapter generates a .sqlfluff INI file in .codacy/generated/ with dialect = ansi, templater = raw, and a rules list derived from the enabled pattern codes.
• Exit code 0 = no violations, 1 = violations found (normal), 2 = error.
• start_line_no and start_line_pos in sqlfluff's JSON output are 1-based, matching Codacy's convention.
• Config file detection only checks for .sqlfluff in the repository root.
• Pattern filtering is both config-level (generated config only enables the requested rules) and post-hoc (results are filtered by enabled pattern IDs as a safety net).