feat: add EXPLAIN plan support with dialect-aware SQL generation #298
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Adds a comprehensive EXPLAIN statement builder with fluent API for generating query execution plans across all supported databases. Key features: - ExplainFormat enum and ExplainOptions class (mypyc-compatible) - Explain builder with dialect-specific SQL generation - Support for PostgreSQL, MySQL, SQLite, DuckDB, Oracle, BigQuery, Spanner - Integration via ExplainMixin for Select, Insert, Update, Delete, Merge - sql.explain() factory method and SQL.explain() method - 160 unit tests and integration tests for all 11 adapters Closes #219
Fix fixture names to match the ones defined in conftest.py: - adbc: use adbc_postgres_config - duckdb: use duckdb_basic_config - sqlite: inline config creation - bigquery: use bigquery_config - oracledb: use oracle_sync_config - spanner: use spanner_config - aiosqlite: rename to avoid fixture conflicts Rename test fixtures to avoid conflicts with conftest fixtures.
ADBC uses COPY protocol which wraps queries, making EXPLAIN statements incompatible. BigQuery tests now use table_schema_prefix fixture instead of non-existent bigquery_dataset.
BigQuery emulator returns "Statement not supported: ExplainStatement" for EXPLAIN queries. Tests can still run against real BigQuery.
- Skip Spanner tests (uses query_mode=PLAN, not SQL EXPLAIN) - Add dialect parameter to query builder/SQL object explain() calls - Remove strict len() > 0 assertions (result format varies by driver)
Query builder and SQL object don't support dialect parameter on explain() method. Use Explain directly with dialect for tests requiring specific dialect behavior.
Query builder without explicit dialect produces PostgreSQL-style SQL. Use raw SQL strings for Oracle and MySQL explain tests.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Adds a comprehensive EXPLAIN statement builder with fluent API for generating query execution plans across all supported databases. This provides dialect-aware SQL generation with a type-safe, mypyc-compatible implementation.
The Problem
Users needed the ability to generate EXPLAIN statements for query analysis and optimization, but each database has unique syntax and options for EXPLAIN. There was no unified API for building EXPLAIN statements across different dialects.
The Solution
Implements an
Explainbuilder class with:.analyze(),.verbose(),.buffers(),.format(), etc.ExplainOptionsclass withcopy()patternExplainMixinfor QueryBuilder integrationKey Features
__slots__)Closes #219