SQL metrics roadmap

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.
• SonarQube T-SQL.
• SQLFluff complexity plugin.
• sqruff.
• 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 · Benchmark site.
• Vashistha, A. & Jain, S. Measuring Query Complexity in SQLShare Workload. PDF.
• Piattini, M. & Martínez, A. Measuring for Database Programs Maintainability. DOI.

​

See also

• SQL metrics overview — namespace inventory.
• Concepts → Architecture — where mehen-sql will fit.