Slowql

<div align="center"> <img src="assets/logo.png" alt="SlowQL Logo" style="width: 600px; height: 200px; object-fit: cover; object-position: center;" /> <br/> <p align="center"> <!-- Support & License --> <a href="https://github.com/slowql/slowql/blob/main/LICENSE"> <img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" /> </a> <a href="https://github.com/sponsors/slowql"> <img src="https://img.shields.io/badge/Sponsor%20SlowQL-%F0%9F%92%B0-brightgreen" /> </a> </p>

Production-focused offline SQL static analyzer.

Catch security vulnerabilities, performance regressions, reliability issues, compliance risks, cost inefficiencies, and code quality problems before they reach production.

<p align="center"> <!-- Release & Version --> <a href="https://github.com/slowql/slowql/releases"> <img src="https://img.shields.io/github/v/release/slowql/slowql?logo=github&label=Release&color=4c1" /> </a> <a href="https://pypi.org/project/slowql/"> <img src="https://img.shields.io/pypi/v/slowql?logo=pypi&logoColor=white&label=PyPI&color=3775A9" /> </a> <a href="https://pypi.org/project/slowql/"> <img src="https://img.shields.io/pypi/pyversions/slowql?logo=python&logoColor=white&label=Python" /> </a> </p> <p align="center"> <!-- Distribution & Runtime --> <a href="https://hub.docker.com/r/makroumi/slowql"> <img src="https://img.shields.io/docker/v/makroumi/slowql?logo=docker&label=Docker&color=2496ED" /> </a> <a href="https://github.com/slowql/slowql/pkgs/container/slowql"> <img src="https://img.shields.io/badge/GHCR-available-181717?logo=github" /> </a> <a href="https://marketplace.visualstudio.com/items?itemName=Makroumi.slowql-vscode"> <img src="https://img.shields.io/visual-studio-marketplace/v/Makroumi.slowql-vscode?logo=visualstudiocode&label=VS%20Code&color=007ACC" /> </a> </p> <p align="center"> <!-- Usage & Adoption --> <a href="https://pypistats.org/packages/slowql"> <img src="https://img.shields.io/pypi/dm/slowql?logo=pypi&logoColor=white&label=Downloads" /> </a> <a href="https://hub.docker.com/r/makroumi/slowql"> <img src="https://img.shields.io/docker/pulls/makroumi/slowql?logo=docker&label=Pulls" /> </a> <a href="https://github.com/slowql/slowql/stargazers"> <img src="https://img.shields.io/github/stars/slowql/slowql?logo=github&label=Stars" /> </a> </p> <p align="center"> <!-- Quality & CI --> <a href="https://github.com/slowql/slowql/actions/workflows/ci.yml"> <img src="https://img.shields.io/github/actions/workflow/status/slowql/slowql/ci.yml?label=CI&logo=githubactions" /> </a> <a href="https://codecov.io/gh/slowql/slowql"> <img src="https://codecov.io/gh/slowql/slowql/graph/badge.svg" /> </a> <a href="https://snyk.io/test/github/slowql/slowql"> <img src="https://snyk.io/test/github/slowql/slowql/badge.svg" /> </a> </p> <p align="center"> <!-- Code Quality --> <a href="https://github.com/astral-sh/ruff"> <img src="https://img.shields.io/badge/lint-ruff-46a758?logo=ruff" /> </a> <a href="http://mypy-lang.org/"> <img src="https://img.shields.io/badge/types-mypy-blue?logo=python" /> </a> </p> <p align="center"> <!-- Community --> <a href="https://github.com/slowql/slowql/issues"> <img src="https://img.shields.io/github/issues/slowql/slowql?logo=github&label=Issues" /> </a> <a href="https://github.com/slowql/slowql/discussions"> <img src="https://img.shields.io/github/discussions/slowql/slowql?logo=github&label=Discussions" /> </a> <a href="https://github.com/slowql/slowql/graphs/contributors"> <img src="https://img.shields.io/github/contributors/slowql/slowql?logo=github&color=success" /> </a> </p> </div>

Why SlowQL

Offline-First Analysis. Catch bugs without ever connecting to a live database. SlowQL works entirely on SQL source files, making it safe to run anywhere.

Custom Rule Engine. Define your own organizational SQL conventions via YAML rules or Python plugins. Custom rules integrate seamlessly with the built-in catalog and support full reporting and suppression.

282 Built-in Rules. Covers security, performance, reliability, compliance, cost, and quality. Each rule includes impact documentation, fix guidance, and severity classification.

Dead SQL Detection. Safely identify unused database objects and redundant code. SlowQL detects unused views, stored procedures, and functions by analyzing definitions and usages across your entire project. It also flags unreachable code paths in procedures (e.g., after RETURN) and near-duplicate queries that should be consolidated.

Cross-File SQL Analysis. Detect breaking changes across multiple files. SlowQL understands relationships between DDL, views, and procedures, flagging when a schema change in one file (e.g., DROP COLUMN) breaks a query in another.

dbt & Jinja Support. Natively parses dbt models and SQL templates containing Jinja tags ({{ ref() }}, {% if %}, {% for %}). Enforces dbt best practices including missing references and hardcoded schema detection.

Migration Framework Support. Natively supports Alembic, Django migrations, Flyway, Liquibase, Prisma Migrate, and Knex. SlowQL understands the ordering, dependencies, and context of migration files to catch destructive changes before they break your existing queries.

14 SQL Dialects. Dialect-aware analysis for PostgreSQL, MySQL, SQL Server (T-SQL), Oracle, SQLite, Snowflake, BigQuery, Redshift, ClickHouse, DuckDB, Presto, Trino, Spark, and Databricks. Universal rules fire on all dialects; dialect-specific rules only fire when relevant.

Schema-Aware Validation. Optionally validate against your DDL files to catch missing tables, columns, and suggest indexes.

Safe Autofix. Conservative, exact-text-replacement fixes with FixConfidence.SAFE. No guessing, no heuristic rewrites. Preview with --diff, apply with --fix.

CI/CD Native. GitHub Actions, SARIF, pre-commit hooks, JSON/HTML/CSV exports. Exit codes based on severity thresholds.

Editor Integration. VS Code extension via slowql-vscode and foundational LSP server for other editors.

Application Code SQL Extraction. Automatically extract and analyze SQL strings embedded in Python, TypeScript/JavaScript, Java, Go, Ruby, and MyBatis XML mapper files. SlowQL uses language‑specific heuristics (AST for Python, regex for others) and a dedicated MyBatis XML parser to find SQL, flagging potential injection risks in dynamic constructions. It distinguishes safe #{param} parameterization from unsafe ${param} interpolation and marks queries using dynamic MyBatis tags (<if>, <where>, <set>, etc.) as dynamic.

---

Installation

pipx (recommended)

pipx install slowql

pip

pip install slowql

Docker

docker run --rm -v $(pwd):/src makroumi/slowql /src/queries.sql

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

---

Quick Start

slowql queries.sql

Analyze application code (extracts SQL strings automatically):

slowql src/app.py src/services/

Analyze with schema validation:

slowql queries.sql --schema schema.sql

Run in CI mode with failure thresholds:

slowql init --dialect postgresql --fail-on high
slowql src/ --fail-on high

Analyze MyBatis mapper files:

slowql src/main/resources/mapper/UserMapper.xml
slowql src/main/resources/mapper/ --schema db/schema.sql

Preview and apply safe fixes:

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

Explore the Rule Catalog

List all built-in rules dynamically or get detailed documentation for a specific rule:

slowql --list-rules
slowql --explain PERF-SCAN-001

Python API integration

Integrate SlowQL directly into your Python scripts with three lines of code:

import slowql
result = slowql.analyze("SELECT * FROM users")

---

Schema-Aware Validation

SlowQL performs optional schema-aware validation by inspecting your DDL files. This catches structural issues that generic static analysis misses.

Tables and Columns. Detect references to non-existent tables or columns.

Index Suggestions. Identify filtered columns that lack corresponding indexes.

slowql queries.sql --schema database/schema.sql
slowql migrations/ --schema schema.sql --fail-on critical

Schema findings:

| Rule | Description | |------|-------------| | 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 filtered column |

---

SlowQL ships with 282 rules across six dimensions:

| Dimension | Focus | Rules | |-----------|-------|------:| | Security | SQL injection, privilege escalation, credential exposure, SSRF | 61 | | Performance | Full scans, indexing, joins, locking, sorting, pagination | 73 | | Reliability | Data loss prevention, transactions, race conditions, idempotency | 44 | | Quality | Naming, complexity, null handling, style, dbt, dead SQL | 51 | | Cost | Cloud warehouse optimization, storage, compute, network | 33 | | Compliance | GDPR, HIPAA, PCI-DSS, SOX, CCPA | 18 |

MyBatis XML Support

MyBatis is a popular Java/Spring ORM framework that uses XML mapper files to define SQL statements. SlowQL now parses these mapper files and applies all existing SQL rules.

Supported MyBatis Tags

• <select>, <insert>, <update>, <delete>, <sql>
• Dynamic tags: <if>, <where>, <set>, <foreach>, <choose>, <when>, <otherwise>, <trim>

Parameter Syntax

• Safe: #{param} – uses prepared‑statement style parameterization.
• Unsafe: ${param} – direct string interpolation, flagged as pot