Understand complicated SQL without tracing every branch by hand.

SQL Cartographer turns SQL into diagrams for control flow, query structure, object dependencies, column lineage, report dependencies, and entity relationship diagrams from schema DDL. It runs locally in the browser: no backend, database connection, sign-in, or installation is required.

Accuracy warning: SQL Cartographer is a deterministic heuristic analyser, not a database compiler. Treat diagrams as investigation aids and verify important findings against the source SQL and target database.

Trust model: The v3.2.1 release asserts semantic relationships only where static evidence supports them. Dynamic and ambiguous regions stay explicit. See Accuracy and the v2 accuracy contract.

Breaking change (rename): The project was renamed from ProcFlow to SQL Cartographer. Browser-stored queries, ERD layouts, and workspace exports created before the rename are not read by this version — see the CHANGELOG for the full identifier mapping and what to export before upgrading.

Use cases

• DBAs: review procedures, functions, triggers, views, transactions, exception paths, reads, writes, and calls.
• SQL/report engineers: import SSRS/RDL definitions, connect datasets to their queries, and trace report → dataset → object → column dependencies.
• Application teams: inspect multi-object scripts, temporary-table flow, catalogue-backed object resolution, and conservative column lineage.
• Schema reviewers: open erd.html, paste or import CREATE TABLE / ALTER TABLE DDL, and see declared tables, views, keys, and foreign keys as an entity relationship diagram.
• Reviewers: export deterministic Mermaid, SVG, or editable draw.io diagrams with source provenance.

Quick start

1. Download the v3.2.1 runtime ZIP from the GitHub release, or clone this repository.
2. Open index.html in a current Chromium, Firefox, or Edge browser.
3. Paste SQL or import local files, select a dialect or Auto, and choose Refresh.
4. Choose an object and scope, then inspect the source spans and diagnostics before relying on a relationship.

For schema DDL, open erd.html, paste or import CREATE TABLE / ALTER TABLE statements (T-SQL, PostgreSQL, DB2, or SQLite), and review the declared entities and foreign keys. Highlights:

• Explore: drag the canvas to pan, drag cards to declutter relationship lines, and select a table to highlight and list its declared foreign keys with column mappings and cardinality (Clear or Escape deselects). Find highlights tables and columns and jumps between matches with Enter.

• Arrange: a freshly parsed schema auto-arranges; edges anchor at the referenced column row and route orthogonally through card-free gutters. Layout offers Auto arrange, declaration order, LR/TB/Auto direction, Compact/Normal/Roomy spacing, position pinning, opt-in save/restore in this browser, and versioned layout files keyed by a schema fingerprint.

• Navigate large estates: zoom controls or Fit frame the whole schema; with a table selected, Fit frames it and its declared neighbours. Auto-draw pauses above the shared large-input threshold until Refresh, and large estates switch to compact boxes automatically.

• Query: toggle Query builder to tick columns on the table cards. A floating window (draggable, resizable, collapsible) shows the generated SELECT, a join plan with INNER/LEFT controls and plain-language row notes, and any tables the declared graph cannot reach — each with an explicit resolution: teach the join by hand, add a CROSS JOIN, or leave the table out. Teach join defines a join by clicking two columns, including self joins with a second table alias. Aggregate any picked column (COUNT, COUNT DISTINCT, SUM, AVG, MIN, MAX) and the remaining picks become the GROUP BY list. The Query menu saves one query in this browser (explicit Save/Restore/Forget), exports and imports a versioned query file, and downloads the .sql. Joins are highlighted on the diagram, and the dialect-quoted SQL is ready to paste into a client such as DBeaver.

  

• Honesty: the ERD asserts declared constraints only. It never infers a relationship from query text, and unresolved references stay explicit.

For development, see Development. For a simple served run, use python -m http.server 8000 from the runtime directory and open http://127.0.0.1:8000/.

Demo

Open the app and choose Load sample to explore a representative procedure, query, report-shaped dependency, or SQLite trigger without preparing any input. The logo above is the bundled project mark; all sample and user analysis stays in the browser.

What it shows

• IF/ELSE/CASE, loops, exits, labels, GOTO, cursors, transactions, savepoints, returns, and exception handling;
• statement and result-set structure, CTEs, joins, unions, subqueries, table reads/writes, MERGE, APPLY, derived tables, and query references;
• procedure/function calls and object dependencies;
• temporary-table producer → consumer data flow;
• conservative column lineage with explicit ambiguity;
• report and dataset dependency chains;
• declared entity relationships from DDL: tables, views, columns, primary, unique, and foreign keys (composite keys grouped), exported as Mermaid erDiagram;
• a query builder that turns declared DDL evidence into dialect-quoted SQL, with explicit resolutions for tables the declared keys cannot reach;
• dynamic SQL as an explicit opaque step rather than an invented dependency.

Supported dialects

SQL Cartographer v3.2.1 supports Microsoft T-SQL, IBM DB2 SQL PL, PostgreSQL PL/pgSQL, and SQLite. Detection is automatic but can be overridden. Vendor extensions outside these tested constructs may produce diagnostics or reduced coverage; see Accuracy.

Privacy and security

Runtime analysis is local-only. Nothing is submitted to SQL Cartographer. Browser storage is opt-in through Save to this browser; workspace export and clipboard actions are explicit. Mermaid uses strict rendering in the security suite, and hostile labels are escaped for diagram/XML output. Read the full Security and privacy policy before using sensitive data.

Documentation

Start at docs/README.md — the documentation map, with a learning path for users, contributors, and reviewers.

• User guide — first run, reading a diagram, workflows, imports, filters, workspaces, large inputs, and exports.
• Query builder — declared-evidence joins, bridge tables, taught and self joins, SQL options, and limits.
• Glossary — the vocabulary the docs and the UI share.
• Accuracy — confidence, coverage, diagnostics, and limits.
• Architecture — pipeline, modules, and invariants.
• Security — data handling and hostile-input boundaries.
• Development — build, browser suites, benchmarks, and packaging.
• Benchmarks — scale fixtures and indicative observations.
• Release history — versioning and release notes.
• Changelog — concise release history and current qualification status.
• v2 accuracy contract — stable guarantees, semantics, compatibility, and qualification evidence.
• ADR-001 — why the query builder only uses declared keys.
• ADR-002 — why saved queries are explicit, versioned, and fingerprint-pruned.
• ADR-003 — why aggregates derive their GROUP BY from the remaining picks.
• v3.2.1 release note — current release details.
• v3.2.0 release note and browser review — the minor release baseline.
• v3.2.0 specification and implementation checklist — scope and delivery record.
• Release roadmap — realistic v3.3.0–v5.0.0 scope, effort, release gates, and conditional major-version decisions.
• Historical roadmap — the v1.x / v2.0 accuracy workstreams, all shipped.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md — the non-negotiables, how to write a fixture before a fix, and the checklist a change must pass — then Development for the commands. Use the issue forms for anonymised parser reports, bugs, and feature requests; never include confidential SQL.

License

SQL Cartographer is released under the MIT License. Mermaid is vendored under its own MIT license in vendor/mermaid/LICENSE.