---
title: "SQL metrics roadmap"
description: "Implementation phases for the mehen-sql analyzer."
keywords: ["mehen-sql roadmap", "sql analyzer", "implementation"]
---

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.
