Values and Data Types
Relevant source files
The following files were used as context for generating this wiki page:
Values and Data Types in SeaQuery form the foundation for parameter binding and schema definition across multiple database backends, including MySQL, Postgres, and SQLite. The system uses an abstract syntax tree (AST) to represent data, allowing developers to inject parameters safely and handle cross-database type mapping automatically.
Sources: README.md:16-25, src/lib.rs:1-15
Core Value Representation
The Value enum is the central data structure used to represent any data that can be passed as a parameter to a SQL query. It encapsulates Rust types and provides a unified interface for the query builders to generate appropriate SQL placeholders and bound values.
The Value Enum and Parameter Binding
SeaQuery uses the Values struct (a wrapper around Vec<Value>) to manage collections of parameters. This approach prevents "off-by-one" errors common in manual parameter binding by handling sequence generation (like $1, $2 in Postgres or ? in MySQL) automatically.
The diagram above illustrates the flow from native Rust types to finalized SQL parameters.
Sources: README.md:94-105, src/lib.rs:885-895, src/value/mod.rs
Supported Data Types
SeaQuery supports a wide array of standard and extended data types through feature flags.
| Category | Supported Types / Feature Flags | Source |
|---|---|---|
| Primitives | Integers (Small, Big, Unsigned), Floats, Strings, Booleans, Bytes | src/value/mod.rs |
| Temporal | with-chrono, with-time, with-jiff (Date, Time, DateTime, Timestamp) | README.md:47, changelog/1.0.0-rc.34.md:58 |
| Numeric | with-rust_decimal, with-bigdecimal | README.md:47 |
| Network | with-ipnetwork, with-mac_address | src/lib.rs:60-65 |
| Special | with-uuid, with-json (JsonValue) | README.md:47 |
| Postgres Specific | postgres-array, postgres-interval, postgres-vector, postgres-range | changelog/1.0.0-rc.33.md:20 |
Backend-Specific Type Mapping
Data types are often mapped differently depending on the target database backend. This is particularly evident in how SeaQuery handles types that do not have a direct 1:1 match in certain databases.
Unsigned Integer Mapping in Postgres
Since PostgreSQL lacks native unsigned integer types, SeaQuery maps them to wider signed types to prevent overflow.
| SeaQuery ColumnType | Postgres Target Type |
|---|---|
TinyUnsigned | smallint |
SmallUnsigned | integer |
Unsigned | bigint |
BigUnsigned | bigint |
Sources: changelog/1.0.0-rc.34.md:13-20
Jiff Integration
The with-jiff feature provides specialized mappings for the Jiff datetime library. Note that jiff::Zoned was removed in recent versions due to lack of lossless support in underlying drivers.
| Rust Type | SeaQuery Value | Column Type |
|---|---|---|
jiff::civil::Date | Value::JiffDate | Date |
jiff::civil::DateTime | Value::JiffDateTime | Timestamp |
jiff::Timestamp | Value::JiffTimestamp | TimestampWithTimeZone |
Sources: changelog/1.0.0-rc.34.md:58-85
Typed Enums and Custom Types
SeaQuery allows the definition of custom enums and types, which are handled through the Iden trait and specific Value variants.
The Enum Value
Value::Enum represents a typed enum value. In the Postgres backend, this generates a literal cast to ensure the database recognizes the custom type correctly.
// Example of an Enum Value rendering in Postgres
let value = sea_query::Enum {
type_name: "FontSizeEnum".into(),
value: "large".into(),
};
// Renders as: 'large'::"FontSizeEnum"
Sources: changelog/1.0.0-rc.33.md:8-18
Database Identifiers (Iden)
The Iden trait is used for all identifiers (table names, column names). It can be derived automatically for enums and structs.
This diagram shows the relationship between identifiers and definition structures.
Sources: README.md:197-220, src/table/create.rs:65-80
Schema Definition Types
When creating tables using TableCreateStatement, SeaQuery provides a fluent API to define column types and constraints.
Column Definition Methods
The ColumnDef structure supports various methods to set the data type:
.integer()/.big_integer().string()/.string_len(len).text().boolean().date()/.date_time()/.timestamp().decimal(precision, scale).binary()/.blob()
Sources: src/table/create.rs:13-50, src/table/create.rs:365-385
Table Partitioning (Postgres/MySQL)
Recent updates added support for partitioning types in CREATE TABLE statements.
| Partition Type | Postgres | MySQL |
|---|---|---|
RANGE | Supported | Supported |
LIST | Supported | Supported |
HASH | Supported | Supported |
KEY | Not Applicable | Supported |
Sources: changelog/1.0.0-rc.34.md:88-105, src/table/create.rs:240-300
Summary
SeaQuery's value and type system provides a robust abstraction over SQL data types. By utilizing the Value enum for DML operations and ColumnDef for DDL operations, it ensures type safety and backend compatibility. The system's extensibility via feature flags allows for seamless integration with external crates like chrono, uuid, and serde_json, while backend-specific drivers handle the nuances of SQL type conversion.