Crate postgres_types
source ·Expand description
Conversions to and from Postgres types.
This crate is used by the tokio-postgres
and postgres
crates. You normally don’t need to depend directly on it
unless you want to define your own ToSql
or FromSql
definitions.
§Derive
If the derive
cargo feature is enabled, you can derive ToSql
and FromSql
implementations for custom Postgres
types. Explicitly, modify your Cargo.toml
file to include the following:
[dependencies]
postgres-types = { version = "0.X.X", features = ["derive"] }
§Enums
Postgres enums correspond to C-like enums in Rust:
CREATE TYPE "Mood" AS ENUM (
'Sad',
'Ok',
'Happy'
);
use postgres_types::{ToSql, FromSql};
#[derive(Debug, ToSql, FromSql)]
enum Mood {
Sad,
Ok,
Happy,
}
§Domains
Postgres domains correspond to tuple structs with one member in Rust:
CREATE DOMAIN "SessionId" AS BYTEA CHECK(octet_length(VALUE) = 16);
use postgres_types::{ToSql, FromSql};
#[derive(Debug, ToSql, FromSql)]
struct SessionId(Vec<u8>);
§Newtypes
The #[postgres(transparent)]
attribute can be used on a single-field tuple struct to create a
Rust-only wrapper type that will use the ToSql
& FromSql
implementation of the inner
value :
use postgres_types::{ToSql, FromSql};
#[derive(Debug, ToSql, FromSql)]
#[postgres(transparent)]
struct UserId(i32);
§Composites
Postgres composite types correspond to structs in Rust:
CREATE TYPE "InventoryItem" AS (
name TEXT,
supplier_id INT,
price DOUBLE PRECISION
);
use postgres_types::{ToSql, FromSql};
#[derive(Debug, ToSql, FromSql)]
struct InventoryItem {
name: String,
supplier_id: i32,
price: Option<f64>,
}
§Naming
The derived implementations will enforce exact matches of type, field, and variant names between the Rust and
Postgres types. The #[postgres(name = "...")]
attribute can be used to adjust the name on a type, variant, or
field:
CREATE TYPE mood AS ENUM (
'sad',
'ok',
'happy'
);
use postgres_types::{ToSql, FromSql};
#[derive(Debug, ToSql, FromSql)]
#[postgres(name = "mood")]
enum Mood {
#[postgres(name = "sad")]
Sad,
#[postgres(name = "ok")]
Ok,
#[postgres(name = "happy")]
Happy,
}
Alternatively, the #[postgres(rename_all = "...")]
attribute can be used to rename all fields or variants
with the chosen casing convention. This will not affect the struct or enum’s type name. Note that
#[postgres(name = "...")]
takes precendence when used in conjunction with #[postgres(rename_all = "...")]
:
use postgres_types::{ToSql, FromSql};
#[derive(Debug, ToSql, FromSql)]
#[postgres(name = "mood", rename_all = "snake_case")]
enum Mood {
#[postgres(name = "ok")]
Ok, // ok
VeryHappy, // very_happy
}
The following case conventions are supported:
"lowercase"
"UPPERCASE"
"PascalCase"
"camelCase"
"snake_case"
"SCREAMING_SNAKE_CASE"
"kebab-case"
"SCREAMING-KEBAB-CASE"
"Train-Case"
§Allowing Enum Mismatches
By default the generated implementation of ToSql
& FromSql
for enums will require an exact match of the enum
variants between the Rust and Postgres types.
To allow mismatches, the #[postgres(allow_mismatch)]
attribute can be used on the enum definition:
CREATE TYPE mood AS ENUM (
'Sad',
'Ok',
'Happy'
);
use postgres_types::{ToSql, FromSql};
#[derive(Debug, ToSql, FromSql)]
#[postgres(allow_mismatch)]
enum Mood {
Happy,
Meh,
}
Macros§
- Generates a simple implementation of
ToSql::accepts
which accepts the types passed to it. - Generates an implementation of
ToSql::to_sql_checked
.
Structs§
- Information about a field of a composite type.
- Postgres
PG_LSN
type. - A Postgres type.
- An error indicating that a
NULL
Postgres value was passed to aFromSql
implementation that does not supportNULL
values. - An error indicating that a conversion was attempted between incompatible Rust and Postgres types.
Enums§
- A wrapper that can be used to represent infinity with
Type::Date
types. - Supported Postgres message format types
- An enum representing the nullability of a Postgres value.
- Represents the kind of a Postgres type.
- A wrapper that can be used to represent infinity with
Type::Timestamp
andType::Timestamptz
types.
Traits§
- A trait used by clients to abstract over
&dyn ToSql
andT: ToSql
. - A trait for types that can be created from a Postgres value.
- A trait for types which can be created from a Postgres value without borrowing any data.
- A trait for types that can be converted into Postgres values.
Type Aliases§
- A Postgres OID.