Crate postgres_types

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>,
}

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,
}