Description
Add a --explain flag that runs EXPLAIN QUERY PLAN on the user's query and prints the SQLite execution plan to stderr before executing the actual query.
sql-pipe data.csv --explain 'SELECT region, SUM(amount) FROM t GROUP BY region'
# stderr: QUERY PLAN:
# stderr: -> Scan on t (cost=0.00..5.00 rows=100)
# stderr: -> HashAggregate (cost=0.50..1.00 groups=5)
Motivation
Users writing complex JOINs or multi-file queries have no way to understand performance characteristics. --explain is the single most-requested debugging feature in SQL tools and is critical for the multi-file join use case.
Acceptance Criteria
Implementation Notes
- SQLite has
EXPLAIN QUERY PLAN built in — no new dependencies needed
- Add
explain: bool field to ParsedArgs in src/args.zig
- Parse
--explain in the args loop (~line 442 of src/args.zig)
- Gate it in
run() in src/main.zig
- Plan output goes to stderr only — must not affect exit codes or stdout
Description
Add a
--explainflag that runsEXPLAIN QUERY PLANon the user's query and prints the SQLite execution plan to stderr before executing the actual query.Motivation
Users writing complex JOINs or multi-file queries have no way to understand performance characteristics.
--explainis the single most-requested debugging feature in SQL tools and is critical for the multi-file join use case.Acceptance Criteria
--explainflag is parsed inargs.zigEXPLAIN QUERY PLAN <query>and print each row to stderr--explainis mutually exclusive with--columns,--validate,--sample,--schema,--statsargs.zigImplementation Notes
EXPLAIN QUERY PLANbuilt in — no new dependencies neededexplain: boolfield toParsedArgsinsrc/args.zig--explainin the args loop (~line 442 ofsrc/args.zig)run()insrc/main.zig