Explain Statement

Relevant source files

The following files were used as context for generating this wiki page:

• src/query/explain.rs
• src/extension/mysql/explain.rs
• src/backend/query_builder.rs
• tests/mysql/explain.rs
• src/lib.rs
• src/extension/mysql/mod.rs

The ExplainStatement is a specialized feature in SeaQuery used to generate diagnostic information about how a database executes a given query. It provides a programmatic interface to construct EXPLAIN commands, which help developers analyze query performance, execution plans, and resource utilization across different database backends including MySQL, PostgreSQL, and SQLite.

This module acts as a wrapper around existing query statements (Select, Insert, Update, and Delete), allowing users to prepend diagnostic keywords and supply backend-specific options. While it provides a common interface, it leverages extension modules to handle the unique syntax and diagnostic capabilities of each supported database engine.

Sources: src/query/explain.rs:107-117, src/lib.rs:35-39

Core Architecture

The ExplainStatement follows the builder pattern common in SeaQuery. It wraps an ExplainableStatement, which is an enumeration of the standard query types that can be analyzed.

Explainable Statements

The system identifies four primary statement types that can be the target of an EXPLAIN command:

• Select: Standard data retrieval.
• Insert: Data insertion.
• Update: Data modification.
• Delete: Data removal.

Sources: src/query/explain.rs:46-52

Component Relationship Diagram

The following diagram illustrates how ExplainStatement interacts with other query components and backend-specific builders.

The diagram shows the aggregation of backend-specific options and the wrapping of query statements into a unified diagnostic command.
Sources: src/query/explain.rs:46-52, src/query/explain.rs:107-117

Data Structures and Configuration

The ExplainStatement struct maintains state for both universal options and platform-specific flags.

Universal Options

Feature	Type	Description
statement	Option<ExplainableStatement>	The query to be analyzed.
analyze	Option<bool>	Triggers execution of the query to gather actual runtime statistics.
format	Option<ExplainFormat>	Defines the output structure (e.g., JSON, YAML, Text).

Sources: src/query/explain.rs:108-113

Backend-Specific Features

PostgreSQL Support

PostgreSQL supports a wide array of analysis flags. Users can configure the statement to include COSTS, BUFFERS, WAL, and TIMING information. It also supports various serialization formats like TEXT, XML, JSON, and YAML.

Sources: src/query/explain.rs:14-39, src/query/explain.rs:153-205

MySQL Support

MySQL's implementation includes specialized analysis for tables, specific columns, or wildcards. It also allows explaining the state of a specific connection ID or targeting specific schemas/databases.

MySQL Option	Method	Description
table	ExplainStatement::table()	Analyze a specific table.
into_variable	into_variable()	Store the output into a MySQL user variable.
for_connection	for_connection()	Analyze the query currently running on a connection.
for_schema	for_schema()	Target a specific schema for the analysis.

Sources: src/query/explain.rs:209-270, src/extension/mysql/explain.rs:31-38

SQLite Support

SQLite support is focused primarily on generating the query plan through the query_plan() method, which sets the query_plan flag in SqliteExplainOptions.

Sources: src/query/explain.rs:274-279

Execution Flow

The conversion from the ExplainStatement AST to a raw SQL string is handled by the QueryBuilder. The ExplainStatement provides a write_to internal method that delegates the actual query preparation back to the specific QueryBuilder implementation.

The sequence shows how the EXPLAIN keyword is prepended while reusing the existing query preparation logic for the inner statement.
Sources: src/query/explain.rs:281-309, src/backend/query_builder.rs:1062-1068

Implementation Details

Statement Wrapping

The ExplainableStatement uses From implementations to easily convert various query types into an analyzable format.

impl From<SelectStatement> for ExplainableStatement {
    fn from(value: SelectStatement) -> Self {
        Self::Select(value)
    }
}

Sources: src/query/explain.rs:81-85

Output Formats

The ExplainFormat enum defines the cross-backend and backend-specific string representations for output formats.

pub enum ExplainFormat {
    Text,
    Xml,
    Json,
    Yaml,
    Tree,
    Traditional,
}

Sources: src/query/explain.rs:14-30

MySQL Connection Diagnostics

One unique feature of the MySQL extension is the ability to explain based on a connection ID rather than a statement provided in the AST.

// In tests/mysql/explain.rs:43-51
assert_eq!(
    ExplainStatement::new()
        .for_connection(123)
        .to_string(MysqlQueryBuilder),
    "EXPLAIN FOR CONNECTION 123"
);

Sources: tests/mysql/explain.rs:43-51, src/query/explain.rs:260-263

Summary

The Explain Statement module provides a robust, type-safe way to generate database execution plans. By abstracting the syntax differences between MySQL's EXPLAIN FORMAT=JSON and SQLite's EXPLAIN QUERY PLAN, SeaQuery enables developers to write diagnostic logic once and apply it across multiple database environments. The system is designed to be extensible, allowing for complex, backend-specific analysis flags while maintaining a simple interface for the most common use cases.

Sources: src/query/explain.rs, src/lib.rs:35-39