sqlx-pg-uint

SQLx extension to support working with Rust unsigned integers in PostgreSQL.

---

This crate provides types with sqlx::{Encode, Decode, Type} implemented for them, which allow you to work with fixed-size unsigned integers in PostgreSQL.

use sqlx_pg_uint::PgU64;

fn main() {
    let a_u64_number = 2937854645u64;
    let pg_u_64 = PgU64::from(a_u64_number);
    println!("PgU64: {}", pg_u_64);
    let back_to_u64: u64 = pg_u_64.to_uint();
    println!("Back to u64: {}", back_to_u64);
    println!(
        "Maths work the same way as you'd expect: {}",
        PgU64::from(67) + PgU64::from(2) * PgU64::from(3) / PgU64::from(3)
    );
    println!(
        "Interact with the underlying BigDecimal type directly: {}",
        pg_u_64.as_big_decimal()
    );
    println!("PgUint types can be converted to and from BigDecimals, and are storable in an sqlx::Postgres database.");
    println!("If you load a PgUint from a database successfully, you can be sure that it's a valid fixed-size unsigned integer.");
}

When defining a column for a PostgreSQL table, which should store a fixed-size unsigned integer, you should use the NUMERIC type.

Rust Type	PostgreSQL Type
PgU8	NUMERIC(3, 0)
PgU16	NUMERIC(5, 0)
PgU32	NUMERIC(10, 0)
PgU64	NUMERIC(20, 0)
PgU128	NUMERIC(39, 0)

Additionally, you are advised to use constraints to ensure that the value stored in the column is a valid fixed-size unsigned integer, guaranteed to be in range for the type.

CREATE TABLE my_table (
    -- `id` is an unsigned 64-bit integer in the corresponding Rust struct
    id numeric(20, 0) not null constraint chk_id_range check (id >= 0 AND id <= 18446744073709551615),
);

Constraining columns (or Rust types) to only store valid values is not a recommendation specific to this crate, but a general best practice to avoid faulty states in your application.

serde

This crate also provides serde de-/serialization, if the serde feature is enabled.

With the serde feature enabled, you can use the PgUint types in structs that you want to serialize and deserialize.

Types are serialized as their respective unsigned integer values, and deserialized using the underlying Deserialize trait implemented for BigDecimal.

MSRV

1.74.1