Conversions to and from Postgres types.

This crate is used by thetokio-postgres andpostgres crates. You normally don’t need to depend directly on itunless you want to define your ownToSql orFromSql definitions.

§Derive

If thederive cargo feature is enabled, you can deriveToSql andFromSql implementations for custom Postgrestypes. Explicitly, modify yourCargo.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');

usepostgres_types::{ToSql, FromSql};#[derive(Debug, ToSql, FromSql)]enumMood {    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);

usepostgres_types::{ToSql, FromSql};#[derive(Debug, ToSql, FromSql)]structSessionId(Vec<u8>);

§Newtypes

The#[postgres(transparent)] attribute can be used on a single-field tuple struct to create aRust-only wrapper type that will use theToSql &FromSql implementation of the innervalue :

usepostgres_types::{ToSql, FromSql};#[derive(Debug, ToSql, FromSql)]#[postgres(transparent)]structUserId(i32);

§Composites

Postgres composite types correspond to structs in Rust:

CREATE TYPE "InventoryItem" AS (    name TEXT,    supplier_id INT,    price DOUBLE PRECISION);

usepostgres_types::{ToSql, FromSql};#[derive(Debug, ToSql, FromSql)]structInventoryItem {    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 andPostgres types. The#[postgres(name = "...")] attribute can be used to adjust the name on a type, variant, orfield:

CREATE TYPE mood AS ENUM (    'sad',    'ok',    'happy');

usepostgres_types::{ToSql, FromSql};#[derive(Debug, ToSql, FromSql)]#[postgres(name ="mood")]enumMood {#[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 variantswith 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 = "...")]:

usepostgres_types::{ToSql, FromSql};#[derive(Debug, ToSql, FromSql)]#[postgres(name ="mood", rename_all ="snake_case")]enumMood {#[postgres(name ="ok")]Ok,// okVeryHappy,// 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 ofToSql &FromSql for enums will require an exact match of the enumvariants 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');

usepostgres_types::{ToSql, FromSql};#[derive(Debug, ToSql, FromSql)]#[postgres(allow_mismatch)]enumMood {   Happy,   Meh,}