Architecture Overview

Relevant source files

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

• README.md
• src/lib.rs
• src/query/explain.rs
• Cargo.toml
• sea-query-sqlx/Cargo.toml
• sea-query-postgres/Cargo.toml
• sea-query-rusqlite/Cargo.toml

SeaQuery is a dynamic SQL query builder for Rust that allows developers to construct MySQL, Postgres, and SQLite queries using an ergonomic API. The library represents SQL components as Abstract Syntax Trees (ASTs), which are then serialized into backend-specific SQL strings and parameter bindings. It serves as the foundation for higher-level tools like SeaORM while maintaining a lightweight, dependency-optional core.

Sources: README.md:15-28, src/lib.rs:25-38

Core Components and Modules

The architecture is divided into several specialized modules that handle different aspects of SQL generation, from basic identifiers to complex query and schema statements.

Abstract Syntax Tree (AST) Architecture

SeaQuery functions by building an internal representation of a SQL statement. This AST approach ensures that operator precedence is respected and prevents the generation of superfluous parentheses in the final SQL output.

The diagram shows the hierarchical flow from basic identifiers to the final backend-specific SQL string generation.
Sources: README.md:139-142, src/lib.rs:480-496

Primary Data Structures

Component	Description	Relevant Module
Iden	A trait for database identifiers (tables, columns, etc.).	src/lib.rs:720
Expr	Builder for SQL expressions used in SELECT, JOIN, and WHERE clauses.	src/lib.rs:748
Condition	Builder for logical grouping (AND/OR) of expressions.	src/lib.rs:796
Query	Entry point for constructing Query Statements (Select, Insert, etc.).	src/lib.rs:835
Table	Entry point for constructing Schema Statements (Create, Alter, etc.).	src/lib.rs:855
Values	A wrapper for parameter values to be bound in the binary protocol.	src/lib.rs:875

Sources: src/lib.rs:710-880

Backend Translation Logic

SeaQuery abstracts database differences through specific builder traits. This allows the same logic to target multiple SQL dialects.

Builder Interfaces

The translation process uses two primary interfaces for converting the AST into SQL:

• QueryBuilder: Used for DML (Data Manipulation Language) like SELECT and INSERT. It generates a tuple of (String, Values) for prepared statements.
• SchemaBuilder: Used for DDL (Data Definition Language) like CREATE TABLE. It generally returns a String.

The flow highlights the distinction between generating prepared statements for production and plain strings for debugging.
Sources: README.md:165-175, src/lib.rs:506-522

Support for Explain Statements

SeaQuery provides a dedicated ExplainStatement architecture to handle the varying EXPLAIN syntax across backends. This is implemented via an ExplainableStatement enum that wraps Select, Insert, Update, and Delete statements.

The class diagram represents the composition of the Explain module.
Sources: src/query/explain.rs:60-100

Integration and Ecosystem

SeaQuery is designed to be highly extensible, providing separate crates for integration with popular Rust database drivers.

Driver Integration Layers

The project workspace includes specialized crates that provide binder traits for different drivers:

• sea-query-sqlx: Provides compatibility with the sqlx crate, supporting sqlx-mysql, sqlx-postgres, and sqlx-sqlite.
• sea-query-postgres: Specialized binder for the postgres and native-tls drivers.
• sea-query-rusqlite: Integration for the rusqlite driver.
• sea-query-diesel: Binder traits for connecting with the Diesel ORM.

Sources: sea-query-sqlx/Cargo.toml:35-45, sea-query-postgres/Cargo.toml:25-30, sea-query-rusqlite/Cargo.toml:22-25, sea-query-diesel/Cargo.toml:25-30

Feature Flag System

The library uses extensive feature flags in Cargo.toml to maintain a small footprint.

• Backends: backend-mysql, backend-postgres, backend-sqlite.
• Types: Support for chrono, time, uuid, rust_decimal, serde_json, and pgvector are toggled via with- flags.
• Macros: The derive feature enables the Iden procedural macro.

Sources: Cargo.toml:50-100, README.md:65-75

Summary

SeaQuery's architecture centers on an Abstract Syntax Tree that decouples query logic from backend-specific SQL syntax. By providing a unified API for MySQL, Postgres, and SQLite, and supporting integration with major database drivers through optional workspace crates, it offers a flexible foundation for both low-level query building and high-level ORM development. The system prioritizes security through prepared statement support and developer ergonomics through its fluent builder interface.

Sources: README.md:15-35, src/lib.rs:25-45