Metadata-Version: 2.4
Name: sql-query-tagger
Version: 0.1.1
Summary: Static SQL query classifier and injection-risk analyzer for all Amazon RDS database engines
Project-URL: Source, https://github.com/chintagunta/sql-query-tagger
Project-URL: Issues, https://github.com/chintagunta/sql-query-tagger/issues
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.9
Requires-Dist: sqlglot>=23.0.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# sql-query-tagger

Static SQL query classifier and injection-risk analyzer for all Amazon RDS database engines.

`sql-query-tagger` parses a SQL query string and tells you:
- **Query type**: DDL, DML, DQL, DCL, TCL, UTILITY, PROCEDURAL, ADMIN, or UNKNOWN
- **Security risk**: LOW / MEDIUM / HIGH / CRITICAL, with the specific patterns that triggered it (injection patterns, stacked queries, destructive DDL, engine-specific dangerous functions/catalogs)

No database connection required — this is purely static analysis over the query text.

## Supported engines

| Engine | Versions | sqlglot dialect |
|---|---|---|
| PostgreSQL | 11-17 | `postgres` |
| Aurora PostgreSQL | 11-16 | `postgres` |
| MySQL | 5.7, 8.0 | `mysql` |
| Aurora MySQL | 5.7, 8.0 | `mysql` |
| MariaDB | 10.6, 10.11, 11.4 | `mysql` |
| Oracle | 19c, 21c, 23ai | `oracle` |
| SQL Server | 2017, 2019, 2022 | `tsql` |

Listed versions are the ones with version-specific pattern tuning. Other versions of a supported engine still work — they fall back to the engine's base pattern set with a warning logged.

## Install

```bash
pip install sql-query-tagger
```

## Quickstart

```python
from sql_query_tagger import SQLClassifier

classifier = SQLClassifier(engine="postgresql", version="16")
result = classifier.classify_query("SELECT * FROM users WHERE id = 1 OR 1=1")

print(result.query_type)                       # QueryType.DQL
print(result.security_analysis.risk_level)     # RiskLevel.HIGH
print(result.security_analysis.detected_patterns)
print(result.security_analysis.recommendation)
```

## More examples

### Blocking a destructive statement

```python
from sql_query_tagger import SQLClassifier

classifier = SQLClassifier(engine="mysql", version="8.0")
result = classifier.classify_query("SELECT 1; DROP TABLE users;")

print(result.security_analysis.risk_level)         # RiskLevel.CRITICAL
print(result.security_analysis.is_suspicious)      # True
print(result.security_analysis.detected_patterns)
# ['stacked_queries_multiple_statements', 'stacked_queries_dangerous_followup', ...]
```

### Engine-specific dangerous function

```python
classifier = SQLClassifier(engine="sqlserver", version="2022")
result = classifier.classify_query("EXEC xp_cmdshell 'dir'")

print(result.security_analysis.engine_specific_risks)
# ['dangerous_function_xp_cmdshell']
```

### Classifying query type only (DDL/DML/DQL/...)

```python
classifier = SQLClassifier(engine="postgresql", version="16")

for sql in ["CREATE TABLE t (id INT)", "INSERT INTO t VALUES (1)", "SELECT * FROM t"]:
    result = classifier.classify_query(sql)
    print(sql, "->", result.query_type)
# CREATE TABLE t (id INT) -> QueryType.DDL
# INSERT INTO t VALUES (1) -> QueryType.DML
# SELECT * FROM t -> QueryType.DQL
```

### Handling invalid input and unknown engines

```python
from sql_query_tagger import SQLClassifier, UnsupportedEngineError

try:
    classifier = SQLClassifier(engine="db2", version="11.5")
except UnsupportedEngineError as e:
    print(f"Unsupported engine: {e}")

classifier = SQLClassifier(engine="postgresql", version="16")
try:
    classifier.classify_query("")
except ValueError as e:
    print(f"Invalid query: {e}")
```

## Performance

`classify_query` memoizes its security analysis and query-type classification
per `SQLClassifier` instance, keyed by the cleaned query text (this is the
part that calls into `sqlglot` and runs the regex scans). Real traffic tends
to repeat the same templated query shapes (an ORM or app issuing the same
statement with different parameter values folded out), so this cache turns
repeats into a dict lookup instead of a re-parse. Tune or disable it with
`SQLClassifier(..., analysis_cache_size=N)` (`0` disables caching).

Run the benchmark yourself:

```bash
python benchmarks/bench_classify.py
```

Measured on a single thread, 10,000 queries per scenario:

| Scenario | Throughput | Latency |
|---|---|---|
| Repeated templated queries (cache hits) | ~55,500 q/s | ~0.018 ms/query |
| All-unique queries (cache misses, sqlglot parses every query) | ~4,000 q/s | ~0.25 ms/query |

The unique-query case is the floor — it's bound by `sqlglot`'s parser, which
accounts for roughly 75% of per-call time (confirmed via `cProfile`). Since
correct query-type classification depends on that parse, this floor isn't
something `sql-query-tagger` can optimize away without giving up accuracy;
the cache is what makes high-repeat production traffic fast.

## Testing

```bash
pip install -e ".[dev]"
pytest --cov=sql_query_tagger --cov-report=term-missing
```

### Test report

The suite has 114 tests across the classifier pipeline, every engine profile, the
registry, and the public package API, with 99% statement coverage:

```
Name                                      Stmts   Miss  Cover   Missing
-----------------------------------------------------------------------
sql_query_tagger\__init__.py                        4      0   100%
sql_query_tagger\classifier.py                    132      1    99%   188
sql_query_tagger\engines\__init__.py                0      0   100%
sql_query_tagger\engines\aurora_mysql.py            6      0   100%
sql_query_tagger\engines\aurora_postgresql.py       6      0   100%
sql_query_tagger\engines\base.py                   32      0   100%
sql_query_tagger\engines\mariadb.py                 8      0   100%
sql_query_tagger\engines\mysql.py                  19      0   100%
sql_query_tagger\engines\oracle.py                 15      0   100%
sql_query_tagger\engines\postgresql.py             15      0   100%
sql_query_tagger\engines\registry.py               25      0   100%
sql_query_tagger\engines\sqlserver.py              15      0   100%
sql_query_tagger\exceptions.py                      1      0   100%
sql_query_tagger\types.py                          30      0   100%
-----------------------------------------------------------------------
TOTAL                                       308      1    99%
114 passed in 0.54s
```

The one uncovered line is a defensive fallback for a CTE-only top-level parse
shape that sqlglot does not currently produce in practice.

## Limitations

- Static analysis only — it inspects query *text*, not a live schema, so it cannot tell you whether referenced tables/columns exist.
- The stacked-query check splits on `;` without parsing string literals, so a benign query containing a semicolon inside a string (e.g. `'a; b'`) may be flagged as multiple statements. Treat the risk score as a signal, not a verdict.

## License

Apache License 2.0
