SeaQuery

The sea-query-rbatis library acts as a driver to enable integration between SeaQuery (a dynamic SQL query builder) and Rbatis (a Rust SQL toolkit).

Note: This library is currently in alpha status and may undergo breaking changes.

The Iden trait is used for identifiers (table names, column names, etc.) in any query statement. You can implement it manually or use the #[derive(Iden)] macro on enums or structs to automatically convert variants/fields into string identifiers.

Additionally, the #[enum_def] macro can be used to generate an associated Iden enum for a struct.

#[derive(Iden)]
enum Character {
    Table,
    Id,
    FontId,
    FontSize,
}

assert_eq!(Character::Table.to_string(), "character");
assert_eq!(Character::FontId.to_string(), "font_id");

#[derive(Iden)]
struct Glyph;
assert_eq!(Glyph.to_string(), "glyph");

Statements are categorized into Query and Schema statements.

Query Statements

• build<T: QueryBuilder>(&self, query_builder: T) -> (String, Values): Returns the SQL string and the parameter values. This is the preferred method for production as it uses the database driver's binary protocol, offering better security and performance.
• to_string<T: QueryBuilder>(&self, query_builder: T) -> String: Returns the SQL string with parameters injected. Use this for testing and debugging.

Schema Statements

• build<T: SchemaBuilder>(&self, schema_builder: T) -> String: Serializes schema definitions (like CREATE TABLE) into SQL strings.

SeaQuery handles the sequencing of parameters (e.g., $1, $2 or ?) automatically. When you use expressions or custom values, SeaQuery ensures the correct order of values is maintained in the resulting Values object, preventing "off by one" errors common in raw SQL.

assert_eq!(
    Query::select()
        .expr(Expr::col("size_w").add(1).mul(2))
        .from("glyph")
        .and_where(Expr::col("image").like("A"))
        .and_where(Expr::col("id").is_in([3, 4, 5]))
        .build(PostgresQueryBuilder),
    (
        r#"SELECT ("size_w" + $1) * $2 FROM "glyph" WHERE "image" LIKE $3 AND "id" IN ($4, $5, $6)"#
            .to_owned(),
        Values(vec![
            1.into(),
            2.into(),
            "A".to_owned().into(),
            3.into(),
            4.into(),
            5.into(),
        ])
    )
);

SeaQuery supports table partitioning for both PostgreSQL and MySQL via TableCreateStatement::add_partition.

PostgreSQL supported partitioning:

• PARTITION BY RANGE
• PARTITION BY LIST
• PARTITION BY HASH
• PARTITION OF
• FOR VALUES IN
• FOR VALUES FROM ... TO
• FOR VALUES WITH

MySQL supported partitioning:

• PARTITION BY RANGE
• PARTITION BY LIST
• PARTITION BY HASH
• PARTITION BY KEY
• Partition definitions with VALUES IN and VALUES LESS THAN

MySQL does not support partial indexes. In version 1.0.0-rc.34, if IndexCreateStatement::cond_where is used with MysqlQueryBuilder, SeaQuery will now emit the WHERE clause instead of silently dropping it. This causes the database to reject the statement, which is preferred over creating an index with different semantics.

Recommendation: If your application requires partial indexes, you should branch your logic by backend to ensure you only attempt to create partial indexes on supported databases like PostgreSQL or SQLite.

To run the Diesel Postgres integration example, navigate to the example directory and use cargo run.

This example demonstrates common database operations including:

• Creating tables
• Inserting records
• Selecting single and multiple records
• Updating records
• Counting records
• Upserting records
• Deleting records
• Handling complex types like UUID, JSON (Object), Decimal, BigDecimal, DateTime, Inet, MacAddress, and Boolean arrays.

Add sea-query to your Cargo.toml dependencies. The library is lightweight and all dependencies are optional, so you should enable only the features you need.

# Cargo.toml
[dependencies]
sea-query = "1.0"

You can build queries at runtime using a fluent interface. The apply_if method allows you to conditionally append clauses (like WHERE or AND) based on the presence of an Option value, avoiding manual string concatenation or complex conditional logic.

fn query(a: Option<i32>, b: Option<char>) -> SelectStatement {
    Query::select()
        .column("id")
        .from("character")
        .apply_if(a, |q, v| {
            q.and_where(Expr::col("font_id").eq(v));
        })
        .apply_if(b, |q, v| {
            q.and_where(Expr::col("ascii").like(v));
        })
        .take()
}

If you are using the stable sea-query 1.0.0 release, ensure your companion crates are aligned to the following versions to maintain compatibility:

sea-query = "1.0"
sea-query-derive = "1.0"
sea-query-rusqlite = "0.8"
sea-query-postgres = "0.6"
sea-query-diesel = "0.3"
sea-query-rbatis = "0.2"

When using the SQLx binder, you must match the sea-query-sqlx version to your project's sqlx version.

• For SQLx 0.8: Use sea-query-sqlx = "0.8.1".
• For SQLx 0.9: Use sea-query-sqlx = "0.9".

Note: sea-query-sqlx 0.8.0 has been yanked; always use 0.8.1 for SQLx 0.8 compatibility.

# SQLx 0.8 compatibility line
sea-query-sqlx = "0.8.1"

# SQLx 0.9 line
sea-query-sqlx = "0.9"