sqlaudit

Why This Exists

Installation

pip install sqlaudit

git clone https://github.com/JSLEEKR/sqlaudit.git
cd sqlaudit
pip install -e .

Quick Start

CLI Usage

# Audit a SQL file
sqlaudit audit -f queries.sql
# Audit a single query
sqlaudit audit -q "SELECT * FROM users WHERE name = NULL"
# Audit from stdin
cat migration.sql | sqlaudit audit --stdin
# JSON output for CI/CD integration
sqlaudit audit -f queries.sql --format json
# Only check security rules
sqlaudit audit -f queries.sql --category security
# Fail CI pipeline on any error or warning
sqlaudit audit -f queries.sql --fail-on warning
# Show fix suggestions
sqlaudit audit -q "DELETE FROM users" --verbose
# List all available rules
sqlaudit rules

Python API

from sqlaudit import Analyzer
analyzer = Analyzer()
report = analyzer.analyze("""
 SELECT * FROM users WHERE name = NULL;
 DELETE FROM audit_logs;
 INSERT INTO users VALUES (1, 'test');
""")
print(f"Score: {report.score}/100")
print(f"Errors: {report.total_errors}")
print(f"Warnings: {report.total_warnings}")
for query in report.queries:
 for finding in query.findings:
 print(f" [{finding.severity.value}] {finding.rule_id}: {finding.message}")
 print(f" Fix: {finding.suggestion}")

Quick Check

from sqlaudit import Analyzer
analyzer = Analyzer()
findings = analyzer.check_query("DELETE FROM important_table")
for f in findings:
 print(f"{f.rule_id}: {f.message}")
# P002: DELETE without WHERE clause will affect all rows

Rules Reference

Performance (P001-P010)

Security (S001-S007)

Best Practice (B001-B005)

Correctness (C001-C003)

Style (T001-T002)

Advanced Usage

Category Filtering

from sqlaudit import Analyzer
from sqlaudit.rules import Category
# Only security checks
analyzer = Analyzer(enable_categories=[Category.SECURITY])
report = analyzer.analyze("SELECT * FROM users")

Severity Filtering

from sqlaudit import Analyzer
from sqlaudit.rules import Severity
# Only errors and warnings (skip info/hint)
analyzer = Analyzer(min_severity=Severity.WARNING)

Disable Specific Rules

analyzer = Analyzer(disable_rules=["P001", "P007", "T001"])

Custom Rules

from sqlaudit import Analyzer, Rule, Severity, Category
def check_table_prefix(info):
 """All tables should use 'app_' prefix."""
 for table in info.tables:
 if not table.startswith("app_"):
 return f"Table '{table}' missing 'app_' prefix"
 return None
analyzer = Analyzer()
analyzer.register_rule(Rule(
 id="CUSTOM001",
 name="table-prefix",
 description="Tables must use app_ prefix",
 severity=Severity.WARNING,
 category=Category.BEST_PRACTICE,
 check=check_table_prefix,
 suggestion="Rename table to use app_ prefix",
))
report = analyzer.analyze("SELECT * FROM users")
# Finds: Table 'users' missing 'app_' prefix

Output Formats

# Human-readable text (default)
sqlaudit audit -q "SELECT * FROM t" --format text
# JSON for programmatic consumption
sqlaudit audit -q "SELECT * FROM t" --format json
# CSV for spreadsheet import
sqlaudit audit -q "SELECT * FROM t" --format csv
# Summary only (score + counts)
sqlaudit audit -q "SELECT * FROM t" --format summary

CI/CD Integration

# GitHub Actions example
- name: SQL Audit
 run: |
 pip install sqlaudit
 sqlaudit audit -f migrations/*.sql --format json --fail-on warning

# Pre-commit hook
#!/bin/bash
SQL_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.sql$')
if [ -n "$SQL_FILES" ]; then
 sqlaudit audit -f $SQL_FILES --fail-on error --no-color
fi

Scoring

Architecture

sqlaudit/
 parser.py # SQL tokenizer + query parser (zero dependencies)
 rules.py # Rule engine with 27 built-in rules
 analyzer.py # Main analyzer (parser + rules + report)
 report.py # Report data model (Finding, QueryResult, Report)
 formatter.py # Output formatters (text, JSON, CSV, summary)
 cli.py # Command-line interface

License