SQL Visualization Library
npm install sqloflow> π Visualize SQL queries as beautiful data flow diagrams
Turn your complex SQL queries into intuitive visualizations that show how data flows through each operation!
Transform this SQL:
``sql`
WITH high_value_customers AS (
SELECT customer_id, SUM(total) as total_spent
FROM orders
WHERE created_at >= '2024-01-01'
GROUP BY customer_id
HAVING SUM(total) > 1000
)
SELECT c.name, c.email, h.total_spent
FROM customers c
JOIN high_value_customers h ON c.id = h.customer_id
ORDER BY h.total_spent DESC
LIMIT 10
Into this beautiful visual flow:
`mermaid
flowchart LR
subgraph cte_high_value_customers [CTE: high_value_customers]
direction TB
node_3["SELECT
---
customer_id, SUM(total) AS total_spent"]
node_2["HAVING
---
SUM(total) > 1000"]
node_1["GROUP BY
---
customer_id"]
node_0["WHERE
---
created_at >= '2024-01-01'"]
node_0 --> node_1
node_1 --> node_2
node_2 --> node_3
end
node_4["FROM
---
customers.id
customers.name
customers.email"]
node_5[WITH high_value_customers]
node_6["INNER JOIN
---
c.id
c.name
c.email
h.customer_id
h.total_spent
---
ON c.id = h.customer_id"]
node_7["SELECT
---
c.name
c.email
h.total_spent"]
node_8["ORDER BY
---
h.total_spent DESC"]
node_9["LIMIT 10"]
node_3 --> node_5
node_4 --> node_6
node_5 --> node_6
node_6 --> node_7
node_7 --> node_8
node_8 --> node_9
`
- π Column-level data flow tracking - See exactly which columns flow through each operation
- π― Multiple output formats - Mermaid diagrams, ASCII art, GraphViz DOT, or raw JSON
- π Intelligent schema inference - Automatically detects columns even without CREATE TABLE
- πΈ Schema snapshots - Track how your data schema transforms at each step
- π Universal compatibility - Works in browsers, Node.js, and as a CLI tool
- ποΈ Complex query support - CTEs, subqueries, joins, aggregations, and more
`bashOutput Mermaid diagram to stdout
npx sqloflow "SELECT * FROM users"
$3
`
-f, --format Output format: mermaid, ascii, dot, json (default: mermaid)
-o, --output Output to file instead of stdout
-d, --dialect SQL dialect: postgresql, mysql, sqlite, mariadb, transactsql
(default: postgresql)
-h, --help Show help message
`$3
`bash
Visualize a complex analytical query
npx sqloflow "
WITH monthly_sales AS (
SELECT
DATE_TRUNC('month', created_at) as month,
SUM(amount) as total
FROM orders
GROUP BY 1
)
SELECT
m.month,
m.total,
LAG(m.total) OVER (ORDER BY m.month) as prev_month,
m.total - LAG(m.total) OVER (ORDER BY m.month) as growth
FROM monthly_sales m
ORDER BY m.month DESC
"Visualize a JOIN query showing table relationships
npx sqloflow "SELECT u.name, o.total FROM users u JOIN orders o ON u.id = o.user_id WHERE o.total > 100"Generate a GraphViz visualization and convert to PNG
npx sqloflow -f dot "SELECT * FROM users u JOIN posts p ON u.id = p.user_id" | dot -Tpng -o query.pngQuick ASCII visualization in terminal
npx sqloflow -f ascii "SELECT name, COUNT(*) FROM users GROUP BY name"
`π Library Usage
$3
`bash
npm install sqloflow
`$3
`typescript
import { parse, convert, render } from 'sqloflow';// Your SQL query
const sql =
;// Parse and convert to intermediate representation
const ast = parse(sql);
const ir = convert(ast);
// Render as Mermaid diagram
const mermaid = render(ir, { format: 'mermaid' });
console.log(mermaid);
`$3
`typescript
import { parse, convert, render } from 'sqloflow';// MySQL-specific syntax
const mysqlAst = parse(sql, 'mysql');
const ir = convert(mysqlAst);
const result = render(ir, { format: 'mermaid' });
`$3
`typescript
// The IR (Intermediate Representation) contains detailed schema information
const ir = convert(ast);// Access schema snapshots showing column flow
ir.snapshots?.forEach(snapshot => {
console.log(
At ${snapshot.nodeId}:);
snapshot.schema.columns.forEach(col => {
console.log( - ${col.source}.${col.name} (${col.type || 'unknown'}));
});
});
`π Output Formats
$3
Perfect for documentation and GitHub READMEs:`mermaid
flowchart LR
node_0["FROM users"]
node_1["WHERE active = true"]
node_2["SELECT id, name"]
node_0 --> node_1
node_1 --> node_2
`$3
Great for terminal output with enhanced details:
`
ββββββββββββββ βββββββββββββββββββββββ βββββββββββββββββ βββββββββββββ βββββββββββββββββββββββββ
β FROM β β INNER JOIN β β WHERE β β SELECT β ββΆβ ORDER BY o.total DESC β
β βββββββββ β β βββββββββ β ββΆβ βββββββββ ββ β β βββββββββ β β βββββββββββββββββββββββββ
β users.id ββ β β u.id β β β o.total > 100 β ββΆβ u.u.name ββ β
β users.name β βββΆβ u.name ββ β βββββββββββββββββ β o.o.total β
ββββββββββββββ β β βββββββββ β βββββββββββββ
β β ON u.id = o.user_id β
β βββββββββββββββββββββββ
βββββββββββββββ β
β orders AS o ββ β
βββββββββββββββ
`The ASCII renderer now shows:
- Column information for FROM and JOIN operations
- Formatted WHERE clauses with AND/OR operators on separate lines
- Flattened subqueries displaying their internal structure inline
$3
For high-quality rendered diagrams:
`dot
digraph {
node_0 [label="FROM users AS u|id\nname", style=filled, fillcolor=lightgreen];
node_1 [label="orders AS o", style=filled, fillcolor=lightgreen];
node_2 [label="INNER JOIN|u.id\nu.name|ON u.id = o.user_id", style=filled, fillcolor=lightyellow];
node_3 [label="SELECT|u.name\no.total", style=filled, fillcolor=lightyellow]; node_0 -> node_2;
node_1 -> node_2;
node_2 -> node_3;
}
`$3
For programmatic access:
`json
{
"nodes": [
{
"id": "node_0",
"kind": "op",
"label": "FROM",
"sql": "users"
}
],
"edges": [...],
"snapshots": [...]
}
`π― Use Cases
- π Documentation - Generate visual documentation for complex queries
- π Debugging - Understand how data flows through your SQL
- π₯ Code Reviews - Make query logic clear for reviewers
- π Learning - Teach SQL concepts with visual representations
- π Optimization - Identify bottlenecks and unnecessary operations
π οΈ API Reference
$3
Parses SQL string into an Abstract Syntax Tree.$3
Converts AST to an Intermediate Representation graph with schema information.$3
Renders the graph in the specified format.π Examples
Check out the
examples/ directory for more complex queries:
- CTEs (Common Table Expressions)
- Subqueries (scalar, IN, EXISTS)
- Complex JOINs
- Aggregations and window functions
- Schema transformationsπ§ͺ Development
`bash
Install dependencies
npm installRun tests
npm testBuild the project
npm run buildRun in development mode
npm run dev
``MIT
rot1024