fix(sql-classify): read-only guard accepts EXPLAIN options on a read

HK
10h ago
+305-6

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 the postgres, postgresql and duckdb dialects 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 EXPLAIN statements 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 EXPLAIN statements retain their expected read/write classifications, and dollar-quoted text—including tags with non-ASCII characters—is handled correctly in supported dialects.