makroumi/slowql repository overview

⁠SlowQL

SlowQL is a production-focused offline SQL static analyzer designed to catch security vulnerabilities, performance regressions, reliability issues, compliance risks, cost inefficiencies, and code quality problems before they reach production.

It performs safe static analysis of your SQL source code, requiring no database connection. SlowQL is built for modern engineering teams, supporting CI/CD pipelines, pre-commit hooks, GitHub Actions, SARIF output, and automated fixes.

⁠Why SlowQL

• Offline-First Analysis: Catch bugs without ever connecting to a live database.
• Deep Visibility: 171 built-in rules covering performance, security, and reliability.
• Schema-Aware: Optionally validate against your DDL files to catch missing tables and columns.
• Safe Autofix: Automatically remediate common anti-patterns with one command.
• Native Context: Native workflow integrations including pre-commit, GitHub Actions, SARIF, and foundational LSP/VS Code support.
• Actionable Reporting: Results through console output, GitHub annotations, SARIF, and exported JSON/HTML reports.

⁠Installation

⁠pipx (recommended)

pipx install slowql

⁠pip

pip install slowql

Requirements: Python 3.11+, Linux / macOS / Windows.

⁠Quick Start

Analyze a SQL file:

slowql queries.sql

Analyze with schema validation:

slowql queries.sql --schema schema.sql

Run in CI mode with failure thresholds:

slowql --non-interactive --input-file sql/ --fail-on high --format github-actions

Preview and apply safe fixes:

slowql queries.sql --diff
slowql queries.sql --fix --fix-report fix-report.json

⁠Schema-Aware Validation

SlowQL can perform optional schema-aware validation by inspecting your DDL files. This allows the analyzer to catch structural issues that generic static analysis might miss.

• Tables/Columns: Detect references to non-existent tables or columns.
• Index Suggestions: Identify filtered columns that lack corresponding indexes.

# Pass a single DDL file
slowql queries.sql --schema database/schema.sql

# Fail CI if schema issues are found
slowql migrations/ --schema schema.sql --fail-on critical

⁠Example Schema Findings

• SCHEMA-TBL-001: Table referenced but not defined in schema.
• SCHEMA-COL-001: Column referenced but not present in table definition.
• SCHEMA-IDX-001: Missing index suggested for highly-filtered column.

⁠Rule Coverage

SlowQL ships with 171 rules across six core dimensions:

⁠CLI Usage

⁠Primary Flags

• --input-file : Path to SQL file or directory.
• --schema: Path to DDL schema file.
• --fail-on: Set exit failure threshold (critical, high, medium, low, info, never).
• --non-interactive: Suppress spinners and interactive prompts.

⁠Output Control

• --format: Controls the primary output stream (console, github-actions, sarif).
• --export: Writes detailed reports to disk (json, html, csv).
• --out /: Directory for exported reports.

⁠Exit Codes

• 0: No issues found or issues below failure threshold.
• 2: Issues found meet or exceed the --fail-on threshold.
• 3: Runtime error or tool failure.

⁠Configuration

SlowQL automatically discovers configuration from slowql.toml, .slowql.toml, slowql.yaml, .slowql.yaml, or pyproject.toml (under [tool.slowql]).

# slowql.yaml example
severity:
  fail_on: high
  warn_on: medium

analysis:
  dialect: postgresql
  enabled_dimensions:
    - security
    - performance
    - reliability
  disabled_rules:
    - PERF-SCAN-001

schema:
  path: db/schema.sql

output:
  format: console
  verbose: false
  show_fixes: true

cost:
  cloud_provider: none

compliance:
  frameworks:
    - gdpr

⁠CI Integration

⁠GitHub Action (Official)

- uses: makroumi/slowql-action@v1
  with:
    path: "./sql/**/*.sql"
    schema: "db/schema.sql"
    fail-on: high
    format: github-actions

⁠Direct CLI Usage

- name: SlowQL Analysis
  run: |
    pip install slowql
    # Direct CLI usage with schema validation
    slowql --non-interactive --input-file sql/ --schema db/schema.sql --fail-on high --format github-actions

⁠Architecture

SlowQL is designed as a modular pipeline for SQL analysis:

• Parser: Leverages sqlglot⁠ for robust SQL AST generation.
• Engine: Orchestrates rule execution and cross-query analysis.
• Analyzers: Domain-specific logic controllers (Security, Perf, etc.).
• Inspector: Handles schema loading and metadata resolution.
• Reporters: Transforms results into actionable formats (SARIF, HTML, etc.).

⁠Development

git clone https://github.com/makroumi/slowql.git
pip install -e ".[dev]"

# Run comprehensive test suite
pytest

# Static analysis
ruff check .
mypy src/slowql

⁠License & Support

• License: Apache License 2.0.
• Issues: GitHub Issues⁠
• Discussions: Community Discussions⁠

Back to top⁠