Add sqlfluff

.devcontainer/devcontainer.json

@@ -13,6 +13,7 @@
         "vscode": {
             "extensions": [
                 "charliermarsh.ruff",
+                "dorzey.vscode-sqlfluff",
                 "exiasr.hadolint",
                 "kevinrose.vsc-python-indent",
                 "mosapride.zenkaku",

.dockerignore

@@ -182,6 +182,7 @@ pytest-coverage.txt
 .coveragerc
 .env.local
 .pre-commit-config.yaml
+.sqlfluff
 assets
 LICENSE
 noxfile.py

.github/workflows/format.yml

@@ -7,7 +7,9 @@ on:
       - ".github/actions/setup-python-with-uv/action.yml"
       - ".github/workflows/format.yml"
       - "**.py"
+      - "**.sql"
       - ".python-version"
+      - ".sqlfluff"
       - "pyproject.toml"
       - "ruff.toml"
       - "uv.lock"
@@ -18,7 +20,9 @@ on:
       - ".github/actions/setup-python-with-uv/action.yml"
       - ".github/workflows/format.yml"
       - "**.py"
+      - "**.sql"
       - ".python-version"
+      - ".sqlfluff"
       - "pyproject.toml"
       - "ruff.toml"
       - "uv.lock"
@@ -35,4 +39,17 @@ jobs:
         uses: ./.github/actions/setup-python-with-uv
 
       - name: Format by Ruff
-        run: uv run nox -s fmt
+        run: uv run nox -s fmt -- --ruff
+
+  sqlfluff:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Python with uv
+        uses: ./.github/actions/setup-python-with-uv
+
+      - name: Format by SQLFluff
+        run: uv run nox -s fmt -- --sqlfluff

.github/workflows/lint.yml

@@ -7,7 +7,9 @@ on:
       - ".github/actions/setup-python-with-uv/action.yml"
       - ".github/workflows/lint.yml"
       - "**.py"
+      - "**.sql"
       - ".python-version"
+      - ".sqlfluff"
       - "pyproject.toml"
       - "pyrightconfig.json"
       - "ruff.toml"
@@ -19,7 +21,9 @@ on:
       - ".github/actions/setup-python-with-uv/action.yml"
       - ".github/workflows/lint.yml"
       - "**.py"
+      - "**.sql"
       - ".python-version"
+      - ".sqlfluff"
       - "pyproject.toml"
       - "pyrightconfig.json"
       - "ruff.toml"
@@ -51,3 +55,16 @@ jobs:
 
       - name: Lint by Ruff
         run: uv run nox -s lint -- --ruff
+
+  sqlfluff:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Python with uv
+        uses: ./.github/actions/setup-python-with-uv
+
+      - name: Lint by SQLFluff
+        run: uv run nox -s lint -- --sqlfluff

.pre-commit-config.yaml

@@ -54,5 +54,18 @@ repos:
         types: ["dockerfile"]
         entry: hadolint
 
+  - repo: https://github.com/sqlfluff/sqlfluff
+    rev: 3.5.0
+    hooks:
+      - id: sqlfluff-lint
+        name: SQLFluff Lint
+        description: "Lints sql files with `SQLFluff`"
+        types: [sql]
+
+      - id: sqlfluff-fix
+        name: SQLFluff Fix
+        description: "Fixes sql lint errors with `SQLFluff`"
+        types: [sql]
+
 ci:
   autoupdate_schedule: weekly

.sqlfluff

@@ -0,0 +1,14 @@
+[sqlfluff]
+dialect = bigquery
+max_line_length = 80
+
+exclude_rules =
+
+[sqlfluff:indentation]
+tab_space_size = 2
+
+[sqlfluff:rules:ambiguous.join]
+fully_qualify_join_types = both
+
+[sqlfluff:rules:structure.unused_join]
+forbid_unused_join = True

.vscode/cspell.json

@@ -10,6 +10,7 @@
         "apdisk",
         "autoflake",
         "autolabeler",
+        "beartype",
         "buildkit",
         "buildx",
         "caplog",
@@ -40,6 +41,7 @@
         "ipynb",
         "ipython",
         "isort",
+        "jaxtyping",
         "junitxml",
         "kevinrose",
         "kwargs",
@@ -96,9 +98,11 @@
         "spyderproject",
         "spyproject",
         "sqlalchemy",
+        "sqlfluff",
         "stmts",
         "superfences",
         "tamasfe",
+        "templater",
         "testpaths",
         "timemachine",
         "toolsai",

.vscode/extensions.json

@@ -2,6 +2,7 @@
     "recommendations": [
         "charliermarsh.ruff",
         "codezombiech.gitignore",
+        "dorzey.vscode-sqlfluff",
         "eamodio.gitlens",
         "exiasr.hadolint",
         "kevinrose.vsc-python-indent",

.vscode/settings.json

@@ -13,6 +13,10 @@
         "tests"
     ],
     "python.testing.unittestEnabled": false,
+    "sqlfluff.config": "${workspaceFolder}/.sqlfluff",
+    "sqlfluff.executablePath": "/home/vscode/.venv/bin/sqlfluff",
+    "sqlfluff.format.enabled": true,
+    "sqlfluff.linter.run": "onType",
     "terminal.integrated.defaultProfile.linux": "zsh",
     "terminal.integrated.profiles.linux": {
         "zsh": {
@@ -61,6 +65,11 @@
         "editor.formatOnSave": true,
         "editor.tabSize": 4
     },
+    "[sql]": {
+        "editor.defaultFormatter": "dorzey.vscode-sqlfluff",
+        "editor.formatOnSave": true,
+        "editor.tabSize": 2
+    },
     "[toml]": {
         "editor.defaultFormatter": "tamasfe.even-better-toml",
         "editor.formatOnSave": true,

CLAUDE.md

@@ -42,24 +42,40 @@ uv run pytest
 
 ### Linting & Formatting
 ```bash
-# Format code
-uv run nox -s fmt
+# Format code with Ruff
+uv run nox -s fmt -- --ruff
+
+# Format SQL files with SQLFluff
+uv run nox -s fmt -- --sqlfluff
+
+# Format both Python and SQL
+uv run nox -s fmt -- --ruff --sqlfluff
 
 # Lint with both Pyright and Ruff
 uv run nox -s lint -- --pyright --ruff
 
+# Lint with all tools (Pyright, Ruff, SQLFluff)
+uv run nox -s lint -- --pyright --ruff --sqlfluff
+
 # Lint with Pyright only
 uv run nox -s lint -- --pyright
 
 # Lint with Ruff only
 uv run nox -s lint -- --ruff
 
+# Lint SQL files only
+uv run nox -s lint -- --sqlfluff
+
 # Run Ruff directly
 uv run ruff check . --fix
 uv run ruff format .
 
 # Run Pyright directly
 uv run pyright
+
+# Run SQLFluff directly
+uv run sqlfluff lint .
+uv run sqlfluff fix .
 ```
 
 ### Pre-commit Hooks
@@ -164,6 +180,12 @@ Tests in `tests/tools/` mirror the package structure:
 - Reports: HTML + terminal
 - Import mode: importlib
 
+**SQLFluff (.sqlfluff)**:
+- Dialect: BigQuery
+- Max line length: 80
+- Tab space size: 2
+- Custom rules for join qualification and unused joins
+
 ### Nox Task Automation
 
 The `noxfile.py` uses a custom `CLIArgs` parser (Pydantic-based):
@@ -181,6 +203,8 @@ def lint(session: nox.Session) -> None:
         session.run("uv", "run", "pyright")
     if args.ruff:
         session.run("uv", "run", "ruff", "check", ".", "--fix")
+    if args.sqlfluff:
+        session.run("uv", "run", "sqlfluff", "lint", ".")
 ```
 
 ## Key Patterns for Development

docs/configurations/index.md

@@ -7,7 +7,8 @@ This section provides detailed information about how each tool in this template
 The development environment includes configuration files for:
 
 - **uv** - Package management and Python version
-- **Ruff** - Linting and formatting rules
+- **Ruff** - Linting and formatting rules for Python
+- **SQLFluff** - Linting and formatting rules for SQL
 - **Pyright** - Type checking strictness
 - **pytest** - Testing and coverage
 - **pre-commit** - Automated quality checks
@@ -19,7 +20,8 @@ Each tool is configured through dedicated configuration files in the repository
 | File | Tool | Purpose |
 |------|------|---------|
 | `pyproject.toml` | uv, Project | Dependencies and project metadata |
-| `ruff.toml` | Ruff | Linting and formatting rules |
+| `ruff.toml` | Ruff | Python linting and formatting rules |
+| `.sqlfluff` | SQLFluff | SQL linting and formatting rules |
 | `pyrightconfig.json` | Pyright | Type checking configuration |
 | `pytest.ini` | pytest | Testing and coverage settings |
 | `.pre-commit-config.yaml` | pre-commit | Hook definitions |
@@ -51,6 +53,27 @@ Understand Ruff's linting and formatting rules:
 
 [→ Read full Ruff configuration guide](ruff.md)
 
+### SQLFluff Configuration
+Configure SQL linting and formatting:
+- SQL dialect (BigQuery)
+- Line length (80 characters)
+- Indentation (2 spaces)
+- Custom rules for SQL best practices
+
+**Key file**: `.sqlfluff`
+
+**Quick reference:**
+```bash
+# Lint SQL files
+uv run sqlfluff lint .
+
+# Fix SQL files
+uv run sqlfluff fix .
+
+# Use via nox
+uv run nox -s lint -- --sqlfluff
+```
+
 ### [Pyright Configuration](pyright.md)
 Configure type checking behavior:
 - Type checking mode (standard)

docs/configurations/pre-commit.md

@@ -10,16 +10,30 @@
 - [https://github.com/astral-sh/ruff-pre-commit](https://github.com/astral-sh/ruff-pre-commit)
     - Ruff Lint
     - Ruff Format
+- [https://github.com/sqlfluff/sqlfluff](https://github.com/sqlfluff/sqlfluff)
+    - SQLFluff Lint
+    - SQLFluff Fix
 - [https://github.com/hadolint/hadolint](https://github.com/hadolint/hadolint)
     - Hadolint
 
 ## Overview
-```{.yaml hl_lines=42-57 title=".pre-commit-config.yaml"}
+```{.yaml title=".pre-commit-config.yaml"}
 default_stages: [pre-commit]
 
 repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: check-json
+      - id: check-toml
+      - id: check-xml
+      - id: check-yaml
+      - id: detect-private-key
+      - id: trailing-whitespace
+
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.8.3
+    rev: v0.12.8
     hooks:
       - id: ruff
         name: Ruff check
@@ -40,6 +54,19 @@ repos:
         types: ["dockerfile"]
         entry: hadolint
 
+  - repo: https://github.com/sqlfluff/sqlfluff
+    rev: 3.5.0
+    hooks:
+      - id: sqlfluff-lint
+        name: SQLFluff Lint
+        description: "Lints sql files with `SQLFluff`"
+        types: [sql]
+
+      - id: sqlfluff-fix
+        name: SQLFluff Fix
+        description: "Fixes sql lint errors with `SQLFluff`"
+        types: [sql]
+
 ci:
   autoupdate_schedule: weekly
 ```

docs/guides/index.md

@@ -7,7 +7,8 @@ This section provides comprehensive guides for using the tools and utilities inc
 This template includes several modern Python development tools, each serving a specific purpose:
 
 - **uv** - Ultra-fast package management (10-100x faster than pip)
-- **Ruff** - Lightning-fast linting and formatting
+- **Ruff** - Lightning-fast linting and formatting for Python
+- **SQLFluff** - SQL linting and formatting
 - **Pyright** - Advanced type checking
 - **pytest** - Comprehensive testing framework
 - **nox** - Task automation and workflow management
@@ -21,13 +22,17 @@ This template includes several modern Python development tools, each serving a s
 ### Available Sessions
 
 ```bash
-# Format code with Ruff
-uv run nox -s fmt
+# Format code
+uv run nox -s fmt -- --ruff             # Format Python code
+uv run nox -s fmt -- --sqlfluff         # Format SQL code
+uv run nox -s fmt -- --ruff --sqlfluff  # Format both
 
 # Run linters (you can specify which ones)
-uv run nox -s lint -- --pyright --ruff  # Both
-uv run nox -s lint -- --pyright         # Pyright only
-uv run nox -s lint -- --ruff            # Ruff only
+uv run nox -s lint -- --pyright --ruff --sqlfluff  # All linters
+uv run nox -s lint -- --pyright --ruff             # Python only
+uv run nox -s lint -- --pyright                    # Pyright only
+uv run nox -s lint -- --ruff                       # Ruff only
+uv run nox -s lint -- --sqlfluff                   # SQL only
 
 # Run tests with coverage (75% minimum required)
 uv run nox -s test