Support jiff as a date time lib backend

[tisonkun]

As in https://docs.rs/sqlx/0.8.2/sqlx/postgres/types/index.html for chrono and time, being integrated with jiff.

Since the abstractions are similar, it should be viable.

cc @BurntSushi

I may take a closer look later but I can't commit it :P

[abonander]

I have no strong opinions on jiff yet but I think I'd like to give it some time to mature. It's still in its first release cycle.

See also this comment: BurntSushi/jiff#50 (comment)

[tisonkun]

@abonander Thanks for your feedback! That sounds reasonable.

I'm trying to understand how we support chrono and how we make the feature flag. I saw the code below in type_checking.rs:

        #[cfg(all(feature = "chrono", not(feature = "time")))]
        sqlx::types::chrono::NaiveTime,

        #[cfg(all(feature = "chrono", not(feature = "time")))]
        sqlx::types::chrono::NaiveDate,

        #[cfg(all(feature = "chrono", not(feature = "time")))]
        sqlx::types::chrono::NaiveDateTime,

        #[cfg(all(feature = "chrono", not(feature = "time")))]
        sqlx::types::chrono::DateTime<sqlx::types::chrono::Utc> | sqlx::types::chrono::DateTime<_>,

        #[cfg(all(feature = "chrono", not(feature = "time")))]
        sqlx::postgres::types::PgTimeTz<sqlx::types::chrono::NaiveTime, sqlx::types::chrono::FixedOffset>,

        #[cfg(feature = "time")]
        sqlx::types::time::Time,

        #[cfg(feature = "time")]
        sqlx::types::time::Date,

        #[cfg(feature = "time")]
        sqlx::types::time::PrimitiveDateTime,

        #[cfg(feature = "time")]
        sqlx::types::time::OffsetDateTime,

        #[cfg(feature = "time")]
        sqlx::postgres::types::PgTimeTz<sqlx::types::time::Time, sqlx::types::time::UtcOffset>,

Does it mean that when chrono and time both enabled, time takes the priority?

[tisonkun]

@abonander as a workaround, is there something like FromRow on single type?

I may have:

#[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize, FromRow)]
pub struct NodeInfo {
    pub node_group: String,
    pub node_id: String,
    pub node_addr: String,
    pub node_heartbeat: jiff::Timestamp,
}

But jiff::Timestamp cannot be derived.

[tisonkun]

For reference, here is a wrapper that can be used to bridge jiff's Timestamp to Postgres' TIMESTAMPTZ:

use std::str::FromStr;

use jiff::SignedDuration;
use serde::Deserialize;
use serde::Serialize;
use sqlx::encode::IsNull;
use sqlx::error::BoxDynError;
use sqlx::postgres::types::Oid;
use sqlx::postgres::PgArgumentBuffer;
use sqlx::postgres::PgHasArrayType;
use sqlx::postgres::PgTypeInfo;
use sqlx::postgres::PgValueFormat;
use sqlx::Database;
use sqlx::Decode;
use sqlx::Encode;
use sqlx::Postgres;
use sqlx::Type;

/// A module for Jiff support of SQLx.

// TODO(tisonkun): either switch to the upstream [1] or spawn a dedicate open-source crate.
// [1] https://github.com/launchbadge/sqlx/pull/3511
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Timestamp(pub jiff::Timestamp);

impl Type<Postgres> for Timestamp {
    fn type_info() -> PgTypeInfo {
        // 1184 => PgType::Timestamptz
        PgTypeInfo::with_oid(Oid(1184))
    }
}

impl PgHasArrayType for Timestamp {
    fn array_type_info() -> PgTypeInfo {
        // 1185 => PgType::TimestamptzArray
        PgTypeInfo::with_oid(Oid(1185))
    }
}

impl Encode<'_, Postgres> for Timestamp {
    fn encode_by_ref(&self, buf: &mut PgArgumentBuffer) -> Result<IsNull, BoxDynError> {
        // TIMESTAMP is encoded as the microseconds since the epoch
        let micros = self
            .0
            .duration_since(postgres_epoch_timestamp())
            .as_micros();
        let micros = i64::try_from(micros)
            .map_err(|_| format!("Timestamp {} out of range for Postgres: {micros}", self.0))?;
        Encode::<Postgres>::encode(micros, buf)
    }

    fn size_hint(&self) -> usize {
        size_of::<i64>()
    }
}

impl<'r> Decode<'r, Postgres> for Timestamp {
    fn decode(value: <Postgres as Database>::ValueRef<'r>) -> Result<Self, BoxDynError> {
        Ok(match value.format() {
            PgValueFormat::Binary => {
                // TIMESTAMP is encoded as the microseconds since the epoch
                let us = Decode::<Postgres>::decode(value)?;
                let ts = postgres_epoch_timestamp().checked_add(SignedDuration::from_micros(us))?;
                Timestamp(ts)
            }
            PgValueFormat::Text => {
                let s = value.as_str()?;
                let ts = jiff::Timestamp::from_str(s)?;
                Timestamp(ts)
            }
        })
    }
}

fn postgres_epoch_timestamp() -> jiff::Timestamp {
    jiff::Timestamp::from_str("2000-01-01T00:00:00Z")
        .expect("2000-01-01T00:00:00Z is a valid timestamp")
}

For full integration if we are back to here and continue, rust-postgres/rust-postgres#1164 is a good reference for data type mapping and edge cases (error handling).

[bionicles]

bump, it would be truly awesome if jiff zoned datetimes / timestamps could "just work" with postgres using sqlx ... i'm trying the sqlx chrono feature and somehow my 2025 timestamptz teleported all the way back to 1970!

[BurntSushi]

Yeah I'm working on it now. Note that it will require going through wrapper types, but that's the best we can do I think.

[abonander]

I'm tossing around the idea of adding a couple new traits, roughly like so:

pub trait DecodeAs<DB: Database, T> {
    type Error: Error + Send + Sync + 'static;

    fn decode_as(row: DB::Row) -> Result<T, Self::Error>;
}

pub trait EncodeAs<DB: Database, T> {
    type Error: Error + Send + Sync + 'static;

    fn encode_as<'a>(value: &T, args: DB::Arguments<'a>) -> Result<T, Self::Error>
}

impl<DB: Database, T> DecodeAs<DB, T> for T { /* ... */ }

impl<DB: Database, T> EncodeAs<DB, T> for T { /* ... */ }

// jiff-sqlx

pub struct ZonedAsTimestampTz;

impl DecodeAs<Postgres, Zoned> for ZonedAsTimestampTz { /* ... */ }

impl EncodeAs<Postgres, Zoned> for ZonedAsTimestampTz { /* ... */ }

For the macros, the user would specify ZonedAsTimestampTz as the override but they would emit code invoking the EncodeAs/DecodeAs impls.

With #3383, the user could just add global overrides (copy-pastable from jiff-sqlx's README) and this would be almost entirely transparent.

For non-macro usage, the FromRow derive could gain a control attribute, e.g. #[sqlx(as = "ZonedAsTimestampTz")], and the query builders would gain a bind_as() method (although that might be confused with named bind parameters).

---

However, that may not add much over what's currently supported.

query_as! already emits .into() calls when decoding, so as long as the wrapper types implement Into and the user utilizes global overrides from #3383, this would mostly work without any changes to the trait system.

EncodeAs plus global overrides would potentially improve typechecking of bind parameters, however that only applies to Postgres anyway.

And we can add a FromRow attribute regardless.

[BurntSushi]

Yeah the wrapper types will have bi-directional From impls. I don't think I have enough context to say much about DecodeAs or EncodeAs though.

Also, one thing to clarify here is that I'm not sure there will be a Zoned impl for timestamptz. The latter is really just a timestamp. No time zone. For Zoned to work, I think it would need to be for a regular text field encoded as a human readable RFC 9557 timestamp.

[abonander]

timestamptz is a little more complicated than that, because while it may be stored and transmitted in the binary protocol as UTC, in the text encoding it may include a UTC offset, and users occasionally want to preserve that.

[BurntSushi]

@abonander Hmmm. That seems quite fraught! How does the choice between binary and plain text get made? It seems like it would be very easy to shoot yourself in the foot if you just used jiff::Zoned for that.

I'll probably have to add something like this:

struct TimestampWithOffset {
    pub timestamp: jiff::Timestamp,
    pub offset: jiff::tz::Offset,
}

to the jiff-sqlx crate to support that use case in a way that doesn't involve huge footguns.