> ## Documentation Index
> Fetch the complete documentation index at: https://mehen.ophi.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# SQL metrics roadmap

> Implementation phases for the mehen-sql analyzer.

The SQL analyzer ships in phases. Each phase delivers usable output before the next phase compounds on
it.

## Phase 1 — parser adapter and raw metrics ✅ shipped

Deliverables:

* Dialect selection / configuration (CLI flag, project config, conservative inference).
* Parse diagnostics and parser-confidence metrics.
* Statement count and statement-kind classification.
* LOC / comment / blank / code metrics for `.sql` files.
* Query-block count / depth.
* CTE count and dependency graph.
* Join count / kind metrics.
* Subquery and derived-table metrics.
* CASE, boolean predicate, window, aggregate, set-operation counts.
* SELECT `*`, missing alias, unqualified column ratio.
* Basic DDL/DML risk metrics.
* SQL Halstead counts.

This phase is enough to produce valuable top-offender output.

## Phase 2 — composite scores ✅ shipped

* `sql.structural_complexity`.
* `sql.cognitive_complexity`.
* `sql.review_burden_index`.
* `sql.change_risk_score`.
* `sql.maintainability_index`.
* `sql.modularity_health`.

Composite scores are published alongside the raw metrics and feed `mehen top-offenders` /
`mehen diff` directly — any `sql.*` key is a valid selector and threshold target
(e.g. `mehen top-offenders --metric sql.change_risk_score`). Risk/complexity scores default to
higher-is-worse and maintainability/health scores to higher-is-better; prefix a metric with `+`/`-`
to override. Named profile presets (`sql.analytics_default`, `sql.migration_default`,
`sql.procedural_default`) and diff-aware delta gates remain to be wired through the threshold engine.

## Phase 3 — procedural SQL

* PL/SQL and T-SQL procedural block detection.
* Procedural cyclomatic / cognitive complexity (using Sonar's PL/SQL increments as reference).
* Exception / cursor / loop / dynamic-SQL metrics.
* Embedded query complexity attribution inside routines.

## Phase 4 — optional schema and lineage enrichments

* Optional schema catalog input.
* More accurate object/column reference resolution.
* Foreign-key-aware join graph classification.
* Optional sqruff lineage integration or mehen lineage implementation.
* Schema blast-radius metrics.

## Dialect coverage

`ansi` (default), `postgres`, `tsql`, `snowflake`, `bigquery`, `mysql`, `sqlite`, `oracle`,
`clickhouse`, `redshift`, `sparksql`, `athena`, `db2`. The dialect is inferred from syntax hints with
a reported confidence (`sql.dialect.confidence`), falling back to ANSI.

## Validation strategy

* **Golden fixtures** by dialect and file role (analytics, migration, procedural).
* **Prior-art compatibility tests** against `sqlfluff-complexity` CPX rules.
* **Repository calibration** on migration-heavy, dbt/analytics, app-embedded SQL, and PL/SQL projects.
* **Human validation** ranking sampled SQL files against `structural_complexity`, `cognitive_complexity`,
  `review_burden_index`, Halstead volume, and LOC.

## References

* [SonarQube PL/SQL](https://docs.sonarsource.com/sonarqube-server/analyzing-source-code/languages/pl-sql).
* [SonarQube T-SQL](https://docs.sonarsource.com/sonarqube-server/analyzing-source-code/languages/t-sql).
* [SQLFluff complexity plugin](https://github.com/yu-iskw/sqlfluff-complexity).
* [sqruff](https://playground.quary.dev/docs/).
* Yu et al. (2018). *Spider: A Large-Scale Human-Labeled Dataset for Complex and Cross-Domain
  Semantic Parsing and Text-to-SQL Task.* [arXiv:1809.08887](https://arxiv.org/abs/1809.08887) ·
  [Benchmark site](https://yale-lily.github.io/spider).
* Vashistha, A. & Jain, S. *Measuring Query Complexity in SQLShare Workload.*
  [PDF](https://uwescience.github.io/sqlshare/pdfs/Jain-Vashistha.pdf).
* Piattini, M. & Martínez, A. *Measuring for Database Programs Maintainability.*
  [DOI](https://doi.org/10.1007/3-540-44469-6_7).

## See also

* [SQL metrics overview](/metrics/sql/overview) — namespace inventory.
* [Concepts → Architecture](/concepts/architecture) — where `mehen-sql` will fit.