PostgreSQL Types
Enable the postgres Cargo feature to use the native SQLx PostgreSQL pool. The derive macro
supports the common model types in Models, with the PostgreSQL mappings below.
This is not a promise to support every type SQLx can encode.
Scalar model field mapping
| Rust model type | PostgreSQL column type |
|---|---|
bool | BOOLEAN |
i16, i32, i64 | SMALLINT, INTEGER, BIGINT |
f32, f64 | REAL, DOUBLE PRECISION |
String | TEXT |
Vec<u8> | BYTEA |
serde_json::Value | JSONB |
uuid::Uuid (uuid) | UUID |
| chrono/time date and time types | DATE, TIME, TIMESTAMP, or TIMESTAMPTZ |
rust_decimal::Decimal, bigdecimal::BigDecimal | NUMERIC |
IpAddr, IpNetwork, IpNet | INET |
MacAddress | MACADDR |
BitVec | BIT VARYING |
Optional Rust values use nullable columns. Date/time, UUID, decimal, network, MAC, and bit-vector types require the corresponding Cargo feature from Models.
sqlx::postgres::types::PgInterval is currently supported as a PgArray element, not as a
standalone derived model field. Other SQLx PostgreSQL-specific scalar types are not automatically
accepted by #[derive(Model)].
Arrays
Use PgArray<T> for PostgreSQL array columns. It supports these built-in element types:
- Always available:
bool,i8,i16,i32,i64,f32,f64,String,serde_json::Value, andsqlx::postgres::types::PgInterval. - With
uuid:uuid::Uuid. - With
chrono:NaiveDate,NaiveTime,NaiveDateTime, andDateTime<Utc>/DateTime<FixedOffset>. - With
time:Date,Time,PrimitiveDateTime, andOffsetDateTime. - With
rust_decimal/bigdecimal: the matching decimal type. - With
ipnetwork:std::net::IpAddrandipnetwork::IpNetwork. - With
ipnet:std::net::IpAddrandipnet::IpNet. - With
mac_address:mac_address::MacAddress. - With
bit-vec:bit_vec::BitVec.
PgArray<Option<T>> represents NULL elements inside a non-NULL array. Option<PgArray<T>>
represents a nullable array column. Empty arrays are represented by an empty PgArray.
Arrays are encoded as PostgreSQL array text and bound with an explicit element-type cast. Their
text representation is intended for the built-in element implementations above. Implementing
PgArrayElement alone does not currently make an arbitrary custom PostgreSQL type usable in a
derived model or bypass afastorm’s type-name validation.
Ranges
Use PgRange<T> for PostgreSQL ranges. Supported element/range pairs are:
| Rust element type | PostgreSQL range type |
|---|---|
i32 | INT4RANGE |
i64 | INT8RANGE |
chrono::NaiveDate or time::Date | DATERANGE |
chrono::NaiveDateTime or time::PrimitiveDateTime | TSRANGE |
chrono::DateTime<Utc> / DateTime<FixedOffset> or time::OffsetDateTime | TSTZRANGE |
rust_decimal::Decimal or bigdecimal::BigDecimal | NUMRANGE |
Convert a standard Rust range with PgRange::from(1_i32..10) or specify endpoint inclusivity and
unbounded endpoints with PgRange::new(Bound, Bound). Option<PgRange<T>> represents a NULL
range column. Custom range types are not currently supported.
PostgreSQL-specific behavior and limits
- Auto-increment primary keys use
BIGINT GENERATED BY DEFAULT AS IDENTITY. - JSON parameters and columns use
JSONB; decimal values useNUMERIC. - Network, MAC, and bit-vector fields use PostgreSQL’s native types. SQLite does not provide their PostgreSQL operators or semantics.
postgresmodel metadata carries explicit array/range column types for generated schemas.- The schema migration generator’s column parser currently recognizes only
INTEGER,BIGINT,REAL,DOUBLE PRECISION,TEXT,BOOLEAN, andJSONBfor removal/type-change comparisons. PostgreSQL type-change statements additionally require unchanged constraints and no primary-key or unique constraint. It emits explicit casts; inspect both directions and the data before applying them. Other type changes need manual migrations. - PostgreSQL user-defined enum and composite fields are not supported by the derive macro.
See Models for field attributes and Migrations for schema generation details.