Temporal Types

DuckDB’s temporal types map to DuckValue variants whose inner Rust type depends on the chrono feature (on by default). With chrono, you get chrono::NaiveDate / NaiveTime / NaiveDateTime / DateTime<Utc> / Duration. Without it, you get the crate’s native DuckDate / DuckTime / std::time::SystemTime / std::time::Duration.

The variants

DuckDB type	`DuckValue` variant	Inner (chrono)	Inner (no-chrono)
`DATE`	`Date`	`NaiveDate`	`types::date_native::DuckDate`
`TIME`	`Time`	`NaiveTime`	`DuckTime`
`TIME_NS`	`TimeNs`	`NaiveTime`	`DuckTimeNs`
`TIME_TZ`	`TimeTz`	`types::date_chrono::TimeTz`	`date_native::DuckTimeTz`
`TIMESTAMP`	`Timestamp`	`NaiveDateTime`	`SystemTime`
`TIMESTAMP_S`	`TimestampS`	`NaiveDateTime`	`SystemTime`
`TIMESTAMP_MS`	`TimestampMs`	`NaiveDateTime`	`SystemTime`
`TIMESTAMP_NS`	`TimestampNs`	`NaiveDateTime`	`SystemTime`
`TIMESTAMPTZ`	`TimestampTz`	`DateTime<Utc>`	`SystemTime`
`INTERVAL`	`Interval`	`chrono::Duration`	`std::time::Duration`
± infinity	`TemporalInfinity { kind, sign }`	feature-independent	feature-independent

use better_duck_core::types::value::DuckValue;
use chrono::NaiveDate;

let row = conn.execute("SELECT DATE '2026-01-15' AS d")?.next().unwrap()?;
assert_eq!(row.get("d"), Some(&DuckValue::Date(NaiveDate::from_ymd_opt(2026, 1, 15).unwrap())));

The four TIMESTAMP* variants are distinct DuckDB types with different precisions (seconds, milliseconds, microseconds, nanoseconds). They all map to NaiveDateTime under chrono, but they are not interchangeable: a value keeps its originating column type when written back, so a read→write round trip preserves precision.

Timezone-aware values

TIMESTAMPTZ (TimestampTz) is a UTC instant — chrono::DateTime<Utc>. DuckDB stores TIMESTAMP and TIMESTAMPTZ in the same microsecond wire format but treats them as distinct logical types, so the variant you get back tells you which column type it came from. TIME_TZ (TimeTz) is a time-of-day with an offset; it uses the crate’s TimeTz wrapper even under chrono (there is no exact chrono counterpart).

Intervals

INTERVAL (Interval) carries months, days, and microseconds. Under chrono it maps to chrono::Duration; without chrono, to std::time::Duration.

A DuckDB INTERVAL has three independent components (months, days, micros) because months and days are not fixed-length. Converting to a single Duration collapses that structure — round-trip a value through its original column type rather than reconstructing it from a Duration when the month/day split matters.

±infinity — `TemporalInfinity`

DuckDB reserves the extreme sentinels of DATE/TIMESTAMP for +infinity / -infinity, which no finite chrono value can represent. Rather than lose them, such a value reads back as:

use better_duck_core::types::value::DuckValue;
use better_duck_core::types::{Sign, TemporalKind};

match row.get("d") {
    Some(DuckValue::TemporalInfinity { kind, sign }) => {
        // kind: TemporalKind — Date / Timestamp / TimestampS / TimestampMs / TimestampNs / TimestampTz
        // sign: Sign — Positive (+inf) or Negative (-inf)
        let _ = (kind, sign);
    }
    _ => {}
}

This variant is feature-independent (no chrono type involved). It is tagged with the temporal family (TemporalKind) and direction (Sign) so it round-trips losslessly into the same column type. TemporalKind::type_id() gives the DuckDB duckdb_type id it belongs to.

DuckDB uses ±INT64_MAX for timestamp infinity (-infinity == i64::MIN + 1), not i64::MIN. You never deal with the raw sentinel — read the TemporalInfinity variant instead.

Decomposing timestamps

For calendar/clock arithmetic without pulling in chrono, the crate root re-exports DuckDB-backed helpers:

use better_duck_core::{timestamp_micros_to_parts, parts_to_timestamp_micros, TimestampParts};

let parts: TimestampParts = timestamp_micros_to_parts(1_700_000_000_000_000);
// parts: { year, month, day, hour, min, sec, micros }
let micros: i64 = parts_to_timestamp_micros(parts);   // exact inverse

Both use DuckDB’s own normalisation (duckdb_from_timestamp / duckdb_to_timestamp).

Choosing chrono vs native

chrono (default)

Rich date/time arithmetic, formatting, and ecosystem interop. Keep it on unless you must trim dependencies.

no-chrono (native)

DuckDate / DuckTime / SystemTime with zero extra dependencies — for embedded or size-sensitive builds. Disable chrono in Cargo.

Connecting

Querying

Values & Types

Parameters & Statements

Writing Data

Columnar

Concurrency

Interop

Errors & Extensions

User-Defined Functions

Derives & Helpers

The variants

Timezone-aware values

Intervals

±infinity — `TemporalInfinity`

Decomposing timestamps

Choosing chrono vs native

chrono (default)

no-chrono (native)

See also

​The variants

​Timezone-aware values

​Intervals

​±infinity — TemporalInfinity

​Decomposing timestamps

​Choosing chrono vs native

chrono (default)

no-chrono (native)

​See also

The variants

Timezone-aware values

Intervals

±infinity — `TemporalInfinity`

Decomposing timestamps

Choosing chrono vs native

See also