SQLx Integration

Relevant source files

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

• sea-query-sqlx/Cargo.toml
• README.md
• src/lib.rs
• examples/sqlx_postgres/Cargo.toml
• examples/sqlx_mysql/Cargo.toml
• examples/sqlx_sqlite/Cargo.toml
• changelog/1.0.0-rc.34.md

SeaQuery provides a dedicated integration layer for SQLx, enabling developers to use SeaQuery's dynamic AST-based query building alongside SQLx's asynchronous execution and connection pooling. This integration is primarily housed in the sea-query-sqlx crate, which acts as a driver library providing binder support for various database backends including MySQL, PostgreSQL, and SQLite.

The integration focuses on bridge traits and utilities that convert SeaQuery's Values and SQL strings into formats compatible with SQLx's query execution engine. It supports complex type mappings for common Rust types and specialized database types like PostgreSQL vectors and arrays.

Sources: README.md:28-30, sea-query-sqlx/Cargo.toml:13-16

Architecture and Components

The integration architecture relies on feature-gated modules within sea-query-sqlx that align SeaQuery backends with corresponding SQLx drivers. The core functionality involves taking a Statement built by SeaQuery and binding its parameters to an sqlx::Query.

Data Flow Overview

The flow typically starts with a SeaQuery statement builder, which is then passed through a binder to interface with an SQLx connection or pool.

The diagram shows how abstract syntax trees are transformed into executable SQLx queries via the integration layer.
Sources: src/lib.rs:584-594, README.md:248-260

Supported Backends

The integration supports three primary database backends through specific feature flags in the sea-query-sqlx package:

Backend	Feature Flag	Implementation Note
MySQL	sqlx-mysql	Uses SQLx MySQL driver
PostgreSQL	sqlx-postgres	Includes backend-postgres support
SQLite	sqlx-sqlite	Uses SQLx SQLite driver
Any	sqlx-any	Generic SQLx support

Sources: sea-query-sqlx/Cargo.toml:22-25

Type Mapping and Feature Support

The integration provides extensive support for mapping Rust types to SQL types via SQLx. This is managed through optional dependencies and feature flags to keep the crate lightweight.

Common Type Integrations

Key data types are enabled via specific with-* features, ensuring compatibility between SeaQuery's internal Value representation and SQLx's encoding logic.

• Chrono & Time: Support for chrono and time crates for date/time operations.
• Decimal Support: Integration for rust_decimal and bigdecimal.
• JSON: Support for serde_json types.
• Jiff Support: Recent updates added binder support for jiff values (except jiff::Zoned), allowing jiff::civil::Date, Time, and DateTime to be used in queries.

Sources: sea-query-sqlx/Cargo.toml:26-38, changelog/1.0.0-rc.34.md:83-93

Specialized PostgreSQL Support

For PostgreSQL, the integration provides advanced features like array and vector support:

• postgres-array: Enables mapping for native PostgreSQL arrays.
• postgres-vector: Integrates pgvector for vector similarity searches, requiring the pgvector/sqlx feature.

Sources: sea-query-sqlx/Cargo.toml:39-40

Implementation Details

Binder Logic

The integration handles the conversion of SeaQuery Values into SQLx arguments. For PostgreSQL, this includes managing the $n sequencing to prevent "off by one" errors during parameter injection.

This sequence illustrates the process of binding SeaQuery parameters to an SQLx query object.
Sources: README.md:73-88, src/lib.rs:136-156

Runtime Configuration

The sea-query-sqlx crate allows selecting different async runtimes and TLS implementations to match the host application's environment.

Feature Type	Options
Runtime	runtime-tokio, runtime-async-std, runtime-actix
TLS	tls-native-tls, tls-rustls, tls-none

Sources: sea-query-sqlx/Cargo.toml:41-52

Usage in Projects

Examples within the repository demonstrate how to configure Cargo.toml for various environments. A typical SQLite integration with Chrono and UUID support requires the following dependencies:

[dependencies]
sqlx = "0.9"
sea-query = { version = "1.0", features = ["sqlx-utils"] }
sea-query-sqlx = { version = "0.8", features = [
    "sqlx-sqlite",
    "with-chrono",
    "with-uuid",
    "runtime-async-std",
    "tls-native-tls"
] }

Sources: examples/sqlx_sqlite/Cargo.toml:15-26

Summary

The SQLx integration serves as the glue between SeaQuery’s dynamic SQL generation and SQLx’s robust execution layer. By providing automated parameter binding and comprehensive type support (including recent additions like Jiff and PGVector), it allows developers to build complex, type-safe, and asynchronous database applications in Rust while targeting multiple database backends with a single source of query logic.

Sources: README.md:30-32, changelog/1.0.0-rc.34.md:12-16