Query Builder Traits
Relevant source files
The following files were used as context for generating this wiki page:
The sea-query library relies on a set of core traits to define the behavior of SQL generation across different database backends. These traits provide a common interface for constructing data manipulation (DML) and data definition (DDL) statements while allowing backend-specific implementations for MySQL, Postgres, and SQLite.
The primary abstraction is the QueryBuilder trait, which handles the serialization of statements like SELECT, INSERT, UPDATE, and DELETE. Accompanying this is the TableBuilder trait, which focuses on schema-related operations such as creating or altering tables. Together, these traits ensure that the internal Abstract Syntax Tree (AST) of a query can be translated into valid, dialect-specific SQL strings and parameter bindings.
Sources: src/lib.rs:36-41, src/backend/query_builder.rs:9-12
Core Abstractions
QueryBuilder Trait
The QueryBuilder trait is the central component for generating query statements. It inherits from several specialized builders to manage quoting, escaping, and operator precedence.
The diagram shows the inheritance hierarchy of QueryBuilder, indicating its dependence on quoting and precedence logic.
Sources: src/backend/query_builder.rs:9-12
TableBuilder Trait
The TableBuilder trait extends the functionality to DDL statements. It defines how to translate TableCreateStatement, TableAlterStatement, and other schema-modifying structures into SQL.
Sources: src/backend/table_builder.rs:5-7
Data Flow and SQL Generation
The process of generating SQL involves taking a statement object (like SelectStatement) and a specific backend implementation of a builder (like MysqlQueryBuilder). The builder uses an implementation of SqlWriter to collect the resulting string and parameters.
The flow diagram illustrates how statement objects are processed by a QueryBuilder into final SQL and parameters via a SqlWriter.
Sources: src/prepare.rs:8-12, src/backend/query_builder.rs:18-20
Key Methods and Components
| Component | Responsibility | Relevant Methods |
|---|---|---|
| QueryBuilder | DML statement serialization | prepare_select_statement, prepare_insert_statement, prepare_value |
| TableBuilder | DDL statement serialization | prepare_table_create_statement, prepare_column_def, prepare_column_spec |
| SqlWriter | Buffer for SQL string and values | push_param, write_str, write_char |
| ExplainableStatement | Wrapper for query introspection | write_to |
Sources: src/backend/query_builder.rs:9-30, src/backend/table_builder.rs:5-15, src/prepare.rs:8-12, src/query/explain.rs:43-52
Dialect Specifics
Different backends implement these traits to handle their unique syntax. For example, MysqlQueryBuilder implements QueryBuilder to handle MySQL-specific features like ON DUPLICATE KEY UPDATE or index hints.
MySQL Implementation Example
In src/backend/mysql/query.rs, the QueryBuilder implementation defines MySQL-specific keywords and function names:
- Random Function: Returns
"RAND". - Lock Phrase: Maps
LockType::Updateto"FOR UPDATE". - Placeholder: Returns
("?", false)as MySQL uses non-numbered placeholders.
Sources: src/backend/mysql/query.rs:242-260, src/backend/query_builder.rs:14-16
Table and Index Building
The TableBuilder facilitates complex schema operations. For instance, the prepare_column_spec method handles standard attributes like NOT NULL, DEFAULT, and PRIMARY KEY, while delegating specific keyword generation (like auto-increment) to backend-specific hooks.
// src/backend/table_builder.rs:136-146
if *primary_key {
sql.write_str(" PRIMARY KEY").unwrap();
}
if *auto_increment {
sql.write_str(self.column_spec_auto_increment_keyword())
.unwrap();
}
Sources: src/backend/table_builder.rs:136-146
Statement Preparation and Value Injection
The SqlWriterValues structure is used when a query needs to be prepared with placeholders for binary protocol execution. Alternatively, inject_parameters can be used to generate a full SQL string with values escaped and inlined for debugging or simple drivers.
The sequence diagram details the interaction during parameter binding, showing how placeholders are generated relative to a counter.
Sources: src/prepare.rs:25-35, src/prepare.rs:60-68
Summary
Query Builder Traits in sea-query provide a polymorphic layer that decouples the representation of a SQL query from its dialect-specific string serialization. By implementing QueryBuilder and TableBuilder, the library supports diverse database engines while maintaining a unified API for the user. This architecture allows for advanced features like EXPLAIN statements and complex condition chaining to be handled consistently across MySQL, Postgres, and SQLite backends.
Sources: src/lib.rs:16-25, src/backend/query_builder.rs:9-12, src/query/explain.rs:133-145