CircuitSQL

Supervised 9-stage GitLab DevSecOps & DevPerfOps automation for PostgreSQL 17/18 from MR lock/plan gates to live H1–H18 production triage, blameless 6-part RCAs, and GitLab Duo supervised fix MRs.

Comment

Inspiration

Most AI coding tools stop the moment code is written. In production PostgreSQL systems, the real operational danger begins after code is written: migration DDL acquires ACCESS EXCLUSIVE locks that stall checkout queues, subtle query changes trigger sequential scans on 50M-row tables, and production telemetry breaches wake on-call engineers at 2 AM without actionable root-cause analysis.

What it does

CircuitSQL automates the work after code is written across all 9 GitLab DevSecOps & DevPerfOps stages (Plan → Create → Verify → Package → Secure → Release → Configure → Monitor → Govern) under a Supervised Autonomy contract:

  • GitLab Duo Flow, Custom Agent & MCP Server: Exposes 9 deterministic JSON-RPC tools over .gitlab/duo/mcp.json, orchestrated by .gitlab/duo/flows/sec540-supervised-remediation.yaml and .gitlab/agents/circuitsql-agent/config.yaml.
  • Stages 1–3 (Plan, Create, Verify): Evaluates OLTP (<=15ms p95) vs OLAP (<=2,500ms p95) budgets, scans git history for leaked credentials, and runs Tier 1 AST lock checks + Tier 2 isolated PostgreSQL shadow-DB EXPLAIN (ANALYZE, BUFFERS) plan diffs.
  • Stages 4–7 (Package, Secure, Release, Configure): Emits CycloneDX 1.5 SBOM + SLSA v1.0 provenance, runs BDD PostgreSQL security tests (FORCE ROW LEVEL SECURITY, NOSUPERUSER) with OASIS SARIF 2.1.0 output, rehearses up/down/up rollbacks with a 5-minute canary gate, and issues dynamic short-lived OpenBao DB leases.
  • Stage 8 (Monitor) & Stage 9 (Govern): Live Google Cloud Run Triage Console featuring 18 PostgreSQL 17/18 health probes (H1–H18), 5-tab PostgreSQL Metrics That Matter charts, a 4-tab Diagnostic Slide-Over Drawer with 6-Part Blameless RCA, and an RFC 8785 JCS SHA-256 hash-chained ledger + NIST OSCAL 1.1.2 Assessment Results.

How I built it

We built CircuitSQL in Python 3.12 with FastAPI, SQLGlot AST parsing, and PostgreSQL 17/18 catalog telemetry (pg_stat_statements, pg_stat_io, pg_stat_checkpointer, pg_locks, pg_stat_progress_vacuum). We integrated it natively into GitLab using:

  • GitLab Duo Agent Platform & Flows: .gitlab/duo/flows/sec540-supervised-remediation.yaml and .gitlab/agents/circuitsql-agent/config.yaml
  • Model Context Protocol (MCP) Server: .gitlab/duo/mcp.json (python -m circuitsql.mcp_server, exposing 9 deterministic stage tools over JSON-RPC 2.0)
  • 9-Stage GitLab CI/CD Pipeline: .gitlab-ci.yml enforcing lint, test, secure, package, configure, release, and monitor

Challenges I ran into

  • Ensuring zero-downtime PostgreSQL migration safety by combining fast Tier 1 static AST lock detection (ACCESS EXCLUSIVE lock hazards) with Tier 2 isolated shadow-database EXPLAIN (ANALYZE, BUFFERS) execution plan regression checks.
  • Building a high-density, accessible (WCAG 2.2 AA Dark & Light mode) 9-stage console with a 4-tab Diagnostic Slide-Over Drawer and 5-tab PostgreSQL Metrics That Matter workbench
    that runs under a strict Content-Security-Policy (script-src 'none').

Accomplishments that I'm proud of

  • 100% (9 of 9) GitLab DevSecOps & DevPerfOps stages covered (Plan, Create, Verify, Package, Secure, Release, Configure, Monitor, Govern) with a 100% passing test suite (2,181 / 2,181 automated tests passing) and a 100% green GitLab CI/CD pipeline.
  • 100% Open-Source & Open-Standard interoperability: OASIS SARIF 2.1.0, OWASP CycloneDX 1.5, SLSA v1.0, OpenBao HTTP API v1, RFC 8785 JCS SHA-256 hash-chained ledger, and NIST OSCAL 1.1.2.
  • Live Google Cloud Run deployment: Publicly accessible to judges at https://circuitsql-console-nqht4ifi7a-uc.a.run.app/console

What I learned

Pairing deterministic PostgreSQL telemetry and AST/plan-diff verifiers with GitLab Duo Flows and MCP tools eliminates AI hallucination in high-stakes database operations, turning raw production alert noise (H1–H18) into blameless 6-part RCAs and human-supervised GitLab Merge Requests in seconds.

What's next for CircuitSQL

Expanding multi-region logical replication lag probes (pg_stat_subscription), automated index bloat compaction scheduling (pg_repack), and multi-cluster fleet governance across enterprise GitLab environments.

Built With

Share this project:

Updates