Skip to content

Add --explain flag for query plan introspection #166

@vmvarela

Description

@vmvarela

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

  • --explain flag is parsed in args.zig
  • Before executing the user query, run EXPLAIN QUERY PLAN <query> and print each row to stderr
  • The actual query still executes normally and results go to stdout
  • --explain is mutually exclusive with --columns, --validate, --sample, --schema, --stats
  • Integration tests cover the new flag
  • Help text updated in args.zig

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    priority:highMust be in the next sprintsize:sSmall — 1 to 4 hoursstatus:readyRefined and ready for sprint selectiontype:featureNew functionality

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions