Type Mapping

How Rust types map to DuckDB columns through Diesel: the standard types that work out of the box, the DuckDB-specific sql_types::Duck* markers and how to read/write them, and the values::* newtypes that make foreign Rust types bindable. Verified against crates/better-duck-diesel/src/types/duckdb_types.rs and src/values.rs.

Standard Diesel types

These work with no extra imports — Diesel’s own SQL types with DuckDB backend impls provided here:

Diesel SQL type	DuckDB type	Rust type
`Bool`	`BOOLEAN`	`bool`
`SmallInt`	`SMALLINT`	`i16`
`Integer`	`INTEGER`	`i32`
`BigInt`	`BIGINT`	`i64`
`Float` / `Double`	`FLOAT` / `DOUBLE`	`f32` / `f64`
`Text`	`VARCHAR`	`String`
`Binary`	`BLOB`	`Vec<u8>`
`Date` / `Time` / `Timestamp`	`DATE` / `TIME` / `TIMESTAMP`	`chrono::` (feature `chrono`)*
`Numeric`	`DECIMAL`	`rust_decimal::Decimal` (feature `decimal`, default)

DuckDB-specific SQL types

use better_duck_diesel::sql_types::*; — use these inside table! and in .bind::<T, _> / .into_sql::<T>(). Each is a zero-size type implementing Diesel’s SqlType + QueryId:

`sql_types::*`	DuckDB type	Rust / loads as
`DuckTinyInt`	`TINYINT`/`INT1`	`i8`
`DuckUTinyInt`	`UTINYINT`	`u8`
`DuckUSmallInt`	`USMALLINT`	`u16`
`DuckUInt`	`UINTEGER`	`u32`
`DuckUBigInt`	`UBIGINT`	`u64`
`DuckHugeInt`	`HUGEINT`	`i128`
`DuckUHugeInt`	`UHUGEINT`	`u128`
`DuckTimestamptz`	`TIMESTAMPTZ`	`chrono::DateTime<Utc>` (chrono)
`DuckInterval`	`INTERVAL`	`chrono::Duration` (chrono) / `std::time::Duration`
`DuckTimeTz`	`TIME WITH TIME ZONE`	`TimeTz` (offset preserved) (chrono)
`DuckTimeNs`	`TIME_NS`	`NaiveTime` (nanosecond) (chrono)
`DuckEnum`	`ENUM`	`String` or `#[derive(DuckEnum)]`
`DuckList`	`LIST`	`Vec<DuckValue>`
`DuckArray`	`ARRAY`	fixed-length `Vec<DuckValue>`
`DuckStruct`	`STRUCT`	`HashMap<…>` or `#[derive(DuckStruct)]`
`DuckMap`	`MAP`	key→value collection
`DuckUnion`	`UNION`	active member value
`DuckUuid`	`UUID`	`values::Uuid` (wraps `DuckUuid`)
`DuckBit`	`BIT`	`values::Bit` (wraps `DuckBit`)
`DuckBignum`	`BIGNUM`	`values::Bignum` (wraps `DuckBignum`)

Date/time types map to chrono with the chrono feature, or to better_duck_core::types::date_native plain structs without it. Only one set compiles at a time — see Feature flags.

How `Duck*` columns move through Diesel

These marker types do not all behave the same through the query builder. There are two tiers:

Narrow unsigned widths — load typed, bind via raw SQL or values::*

DuckTinyInt, DuckUTinyInt, DuckUSmallInt, DuckUInt, DuckUBigInt (Rust i8/u8/u16/u32/u64) can be loaded through the typed .select(...) DSL — their Rust types satisfy Diesel’s Queryable blanket, so a .select((t::tiny, t::ubig)) into (i8, u64) works. They have no AsExpression, however, so they cannot be written with .values(...) — insert them with diesel::sql_query(...).bind::<DuckXxx, _>(v) or wrap them in the matching values::* newtype (which adds both bind and load).

// seeded with raw SQL, then loaded through the typed DSL as a tuple
let widths: (i8, u8, u16, u32, u64) = t_widths::table
    .select((t_widths::tiny, t_widths::utiny, t_widths::usmall, t_widths::uint, t_widths::ubig))
    .first(&mut conn)?;

HUGEINT/UHUGEINT and composite/semantic types — raw SQL only

DuckHugeInt/DuckUHugeInt (i128/u128) and DuckUuid, DuckEnum, DuckList, DuckArray, DuckStruct, DuckMap, DuckUnion, DuckBit, DuckBignum, DuckTimestamptz, DuckInterval, DuckTimeTz, DuckTimeNs do not flow through the typed builder at all. Round-trip them via raw SQL: diesel::sql_query(...).bind::<DuckXxx, _>(value) to write, and a #[derive(QueryableByName)] struct whose field carries #[diesel(sql_type = DuckXxx)] to read. Values are ordinary better_duck_core types (DuckValue, DuckUuid, DuckBit, …). The scalar ones (i128/u128/DuckUuid/DuckBit/DuckBignum) also become fully typed-DSL-usable through their values::* newtype.

DECIMAL (Numeric → rust_decimal::Decimal) is similar: Decimal has no AsExpression<Numeric>, so it binds through diesel::sql_query(...).bind::<Numeric, _>(d) rather than .values(...), though its FromSql/ToSql for the DuckDB backend still apply. INTERVAL can be bound either through DuckInterval or Diesel’s own diesel::sql_types::Interval (both map to chrono::Duration).

Reading & writing raw-SQL `Duck*` columns

use better_duck_core::types::value::DuckValue;
use better_duck_diesel::sql_types::DuckList;
use diesel::prelude::*;

#[derive(diesel::QueryableByName, Debug)]
struct Row {
    #[diesel(sql_type = DuckList)]
    val: Vec<DuckValue>,
}

let items = vec![DuckValue::Int(1), DuckValue::Int(2), DuckValue::Int(3)];
diesel::sql_query("INSERT INTO t_list VALUES ($1)")
    .bind::<DuckList, _>(&items)
    .execute(&mut conn)?;

let got: Vec<DuckValue> =
    diesel::sql_query("SELECT val FROM t_list").get_result::<Row>(&mut conn)?.val;
assert_eq!(got, items);

For ENUM/STRUCT columns you can bind/read your own Rust types instead of DuckValue — see Data derives. The concrete Rust types the composite columns read into (verified in tests / example 22-diesel-types): DuckStruct → HashMap<String, DuckValue>, DuckMap → HashMap<DuckValue, DuckValue>, DuckUnion → Box<DuckValue>, DuckEnum → String, DuckUuid/DuckBit/DuckBignum → the core DuckUuid/DuckBit/DuckBignum, and DuckTimestamptz → chrono::DateTime<Utc>.

The `values::*` binding newtypes

Diesel’s blanket impl<T: Expression> AsExpression<T::SqlType> for T means a third-party crate can’t make a foreign value type (i128, u64, DuckUuid, …) usable as an expression at a custom Duck* SQL type — coherence rejects it. The thin local newtypes in better_duck_diesel::values::* fix this: wrap the value and it becomes bindable (.eq(…), .values(…), function arg, .into_sql::<T>()) and loadable (Queryable). The standard widths (i16/i32/i64/f32/f64) already work directly and have no wrapper.

`values::*`	Inner	SQL type
`TinyInt(i8)`	`i8`	`DuckTinyInt`
`UTinyInt(u8)`	`u8`	`DuckUTinyInt`
`USmallInt(u16)`	`u16`	`DuckUSmallInt`
`UInt(u32)`	`u32`	`DuckUInt`
`UBigInt(u64)`	`u64`	`DuckUBigInt`
`HugeInt(i128)`	`i128`	`DuckHugeInt`
`UHugeInt(u128)`	`u128`	`DuckUHugeInt`
`Uuid(DuckUuid)`	`better_duck_core::types::DuckUuid`	`DuckUuid`
`Bit(DuckBit)`	`better_duck_core::types::DuckBit`	`DuckBit`
`Bignum(DuckBignum)`	`better_duck_core::types::DuckBignum`	`DuckBignum`

Each has From<inner> / From<newtype> for inner both ways. Round-trip (verified in tests/values_dsl.rs):

use better_duck_diesel::values::HugeInt;
use better_duck_diesel::sql_types::DuckHugeInt;
use diesel::{prelude::*, IntoSql};

let v = HugeInt(i128::MAX);
let got: HugeInt = diesel::select(v.into_sql::<DuckHugeInt>()).get_result(&mut conn)?;
assert_eq!(got, v);

Schema

Declaring columns with these types.

Data derives

Map your own types to ENUM / STRUCT.

Core values

The DuckValue type the raw path uses.

DSL overview

Binding values::* in expressions.

Getting Started

CRUD

DuckDB SQL DSL

Types & Pooling

Standard Diesel types

DuckDB-specific SQL types

How `Duck*` columns move through Diesel

Reading & writing raw-SQL `Duck*` columns

The `values::*` binding newtypes

See also

Schema

Data derives

Core values

DSL overview

​Standard Diesel types

​DuckDB-specific SQL types

​How Duck* columns move through Diesel

​Reading & writing raw-SQL Duck* columns

​The values::* binding newtypes

​See also

Schema

Data derives

Core values

DSL overview

Standard Diesel types

DuckDB-specific SQL types

How `Duck*` columns move through Diesel

Reading & writing raw-SQL `Duck*` columns

The `values::*` binding newtypes

See also