fix(sql-classify): read-only guard accepts EXPLAIN options on a read
Issue for this PR
Closes #
Type of change
- Bug fix
- New feature
- Refactor / code improvement
- Documentation
What does this PR do?
The read-only SQL guard (sql-classify.ts) used by workspace and MCP query tools could not parse Snowflake EXPLAIN USING JSON <select>, so it returned a parse error and classified the query as a write, blocking it, while plain EXPLAIN SELECT 1 was a read. The same happened for Databricks EXPLAIN EXTENDED|CODEGEN|COST|FORMATTED and Postgres EXPLAIN (FORMAT JSON).
Now an EXPLAIN with a dialect option is a read only when the explained statement is a read (SELECT/WITH without INTO or write clauses, or read-only metadata):
- Snowflake:
EXPLAIN [USING {JSON|TEXT|TABULAR}] - Databricks/Spark/Hive:
EXPLAIN [EXTENDED|CODEGEN|COST|FORMATTED] - Postgres/DuckDB
EXPLAIN (option, ...): only for thepostgres,postgresqlandduckdbdialects and only with PostgreSQL's documented options (FORMAT, SERIALIZE, ANALYZE, VERBOSE, COSTS, SETTINGS, GENERIC_PLAN, BUFFERS, WAL, TIMING, SUMMARY, MEMORY)
The options are stripped only for the parser's view; the read decision still runs on the original statement. Writes inside EXPLAIN (INSERT/DELETE/UPDATE/MERGE/CTAS/SELECT INTO/modifying CTE), unknown options, a parenthesized option list in any dialect other than postgres (including redshift), keyword options of another dialect, missing statements, nested optioned EXPLAIN, and any multi-statement text containing an optioned EXPLAIN remain writes. Option matching is linear-time, and the options are blanked in place so the parser/lexer statement-count cross-check still sees the original text. BigQuery has no EXPLAIN statement and plain EXPLAIN is unchanged.
How did you verify your code works?
New test/altimate/sql-classify-explain.test.ts (22 tests, including timing bounds on long option lists and 64K-statement batches, option-list dialect gating, EXPLAIN (ANALYZE) of writes, nested EXPLAIN, and the $$ edge): JSON/TEXT/TABULAR with read and write inner statements, case/whitespace/comment variants, multi-statement, unknown formats, other dialects, Databricks modes, Postgres option lists. the new behaviour tests fail on origin/main and on the previous head. bun typecheck is green. bun test test/altimate/sql-classify* test/altimate/tools/sql-classify test/altimate/tools/sql-read-safety test/altimate/sql-read-syntax test/altimate/sql-validation: 932 pass. postgresql now lexes dollar quotes like postgres; an EXPLAIN whose query holds a COPY is a write.
Cost side effects
None
Screenshots / recordings
Not a UI change.
Checklist
- I have tested my changes locally
- I have not included unrelated changes in this PR
- I checked for cost side effects (model calls, queries or cloud resources that grow with user data) and described them, or wrote "none"
Summary by CodeRabbit
- Bug Fixes
- Improved SQL read/write classification for
EXPLAINstatements with dialect-specific options in Snowflake, Databricks, Spark, Hive, PostgreSQL, and DuckDB. - Unsupported options and option syntax used with the wrong dialect no longer incorrectly establish read-only status.
- Multi-statement queries are classified with statement boundaries taken into account.
- Plain
EXPLAINstatements retain their expected read/write classifications, and dollar-quoted text—including tags with non-ASCII characters—is handled correctly in supported dialects.
- Improved SQL read/write classification for