pub struct PgDuration(/* private fields */);jiff and postgres and sqlx only.Expand description
A SignedDuration stored as PostgreSQL’s native INTERVAL — the carrier
a Postgres duration column declares, and the door through a wall the orphan rule builds.
§Why a newtype where sqlx already ships the type
PgInterval binds: it has Type, Encode, Decode and
PgHasArrayType. What it does not have, and cannot be given from here, is a conversion from the
filter’s operand. sqlx 0.9 ships no jiff integration, so TryFrom<SignedDuration> for PgInterval
would be a foreign trait on a foreign type — E0117 from this crate, and neither sqlx nor jiff
depends on the other to write it. The newtype is a type this crate owns, which is the whole of
what the impl needs.
Before it, an undeclared Postgres duration column reached core::time::Duration through jiff’s
own conversion, and that type is UNSIGNED: a negative operand was refused at the crossing on a
dialect whose column holds one perfectly well. This carrier is what closes that gap, and it makes
the three backends answer alike — MongoDB stores a signed integer, MySQL a signed TIME, and
Postgres a signed INTERVAL.
§PURE MICROSECONDS, and the comparison that makes it exact
The interval is built as months: 0, days: 0, microseconds: n. An INTERVAL has three
independent fields and the same span has many spellings, so the question is whether an operand
written in one of them compares correctly against a column written in another.
It does, and it is measured rather than assumed. PostgreSQL compares two intervals by normalising BOTH through one convention — a month counts as 30 days and a day as 24 hours — so the field split never reaches the comparison. On PostgreSQL 17.10:
INTERVAL '1 month' = INTERVAL '30 days' = INTERVAL '720 hours' -- all true
INTERVAL '1 day' = INTERVAL '24 hours' -- true
INTERVAL '719 hours' < INTERVAL '1 month' < INTERVAL '721 hours' -- trueand a pure-microseconds operand of 2592000s selects the rows stored as 1 mon AND as
30 days, with >= also reaching 1 mon 1 day. Negative operands normalise identically.
So a pure-microseconds operand is exactly as correct as any other spelling, and it is the only
one this crate can build honestly: the operand is an elapsed span with no calendar fields in it,
and filling months or days would be inventing a calendar reading the caller never wrote.
What that inherits — rather than introduces — is the CONVENTION. A column holding INTERVAL '1 mon' answers eq for an operand of exactly 30 days, because that is what Postgres means by
equality here, not because anything was lost on the way in. A schema that needs calendar
identity rather than elapsed-span equality wants a different column type, and that is true of
every spelling of the operand.
A column that must hold a mixed-field interval for some other reason still has the escape it
always had: PgInterval keeps its own Carrier row, and
a declared converter reaches it.
§What it refuses
PgDurationError::Nanoseconds for sub-microsecond precision INTERVAL cannot hold — the same
refusal MySqlDuration makes, because both columns are microsecond types and the filter is a
nanosecond one — and PgDurationError::Range when the microsecond count leaves i64, which is
the width of the interval’s own field.
Implementations§
Source§impl PgDuration
impl PgDuration
Sourcepub const fn get(self) -> PgInterval
pub const fn get(self) -> PgInterval
The stored INTERVAL value.
Trait Implementations§
Source§impl<'a, R> Assemble<'a, R> for PgDurationwhere
R: Row,
PgDuration: Decode<'a, R::Database> + Type<R::Database>,
for<'name> &'name str: ColumnIndex<R>,
impl<'a, R> Assemble<'a, R> for PgDurationwhere
R: Row,
PgDuration: Decode<'a, R::Database> + Type<R::Database>,
for<'name> &'name str: ColumnIndex<R>,
Source§impl Carrier<Postgres> for PgDuration
The INTERVAL row, binding the checked newtype’s wrapped value — written out rather than
listed above because the bind names get() and not the value itself, which is
MySqlDuration’s arrangement for the same reason.
impl Carrier<Postgres> for PgDuration
The INTERVAL row, binding the checked newtype’s wrapped value — written out rather than
listed above because the bind names get() and not the value itself, which is
MySqlDuration’s arrangement for the same reason.
It rides jiff with the type it binds: PgDuration exists to carry the
duration filter’s operand, and without that feature there is no operand to convert from.
Source§fn push_bind(&self, qb: &mut QueryBuilder<Postgres>)
fn push_bind(&self, qb: &mut QueryBuilder<Postgres>)
qb. Read moreSource§fn push_value_bind(&self, qb: &mut QueryBuilder<Db>)
fn push_value_bind(&self, qb: &mut QueryBuilder<Db>)
Source§impl Clone for PgDuration
impl Clone for PgDuration
impl CollectionElement for PgDuration
Source§impl ColumnEq for PgDuration
impl ColumnEq for PgDuration
Source§impl ColumnKind for PgDuration
impl ColumnKind for PgDuration
Source§const SEGMENTS: &'static [ColumnShape] = _
const SEGMENTS: &'static [ColumnShape] = _
Source§const ORDER: &'static [OrderLevel] = _
const ORDER: &'static [OrderLevel] = _
impl Copy for PgDuration
Source§impl Debug for PgDuration
impl Debug for PgDuration
impl Eq for PgDuration
Source§impl From<PgDuration> for PgInterval
impl From<PgDuration> for PgInterval
Source§fn from(value: PgDuration) -> Self
fn from(value: PgDuration) -> Self
Source§impl PartialEq for PgDuration
impl PartialEq for PgDuration
Source§impl StoredAs<Postgres> for PgDuration
impl StoredAs<Postgres> for PgDuration
impl StructuralPartialEq for PgDuration
Source§impl TryFrom<SignedDuration> for PgDuration
The CHECKED conversion, and the whole reason the newtype exists.
impl TryFrom<SignedDuration> for PgDuration
The CHECKED conversion, and the whole reason the newtype exists.
§Errors
PgDurationError::Nanoseconds when value carries sub-microsecond precision;
PgDurationError::Range when its microsecond count does not fit the interval’s i64 field.
Source§type Error = PgDurationError
type Error = PgDurationError
Auto Trait Implementations§
impl Freeze for PgDuration
impl RefUnwindSafe for PgDuration
impl Send for PgDuration
impl Sync for PgDuration
impl Unpin for PgDuration
impl UnsafeUnpin for PgDuration
impl UnwindSafe for PgDuration
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
Source§fn into_any(self: Box<T>) -> Box<dyn Any>
fn into_any(self: Box<T>) -> Box<dyn Any>
Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>, which can then be
downcast into Box<dyn ConcreteType> where ConcreteType implements Trait.Source§fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
Rc<Trait> (where Trait: Downcast) to Rc<Any>, which can then be further
downcast into Rc<ConcreteType> where ConcreteType implements Trait.Source§fn as_any(&self) -> &(dyn Any + 'static)
fn as_any(&self) -> &(dyn Any + 'static)
&Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot
generate &Any’s vtable from &Trait’s.Source§fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
&mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot
generate &mut Any’s vtable from &mut Trait’s.Source§impl<T> DowncastSend for T
impl<T> DowncastSend for T
Source§impl<T> DowncastSync for T
impl<T> DowncastSync for T
Source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
Source§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key and return true if they are equal.Source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
Source§impl<T> FmtForward for T
impl<T> FmtForward for T
Source§fn fmt_binary(self) -> FmtBinary<Self>where
Self: Binary,
fn fmt_binary(self) -> FmtBinary<Self>where
Self: Binary,
self to use its Binary implementation when Debug-formatted.Source§fn fmt_display(self) -> FmtDisplay<Self>where
Self: Display,
fn fmt_display(self) -> FmtDisplay<Self>where
Self: Display,
self to use its Display implementation when
Debug-formatted.Source§fn fmt_lower_exp(self) -> FmtLowerExp<Self>where
Self: LowerExp,
fn fmt_lower_exp(self) -> FmtLowerExp<Self>where
Self: LowerExp,
self to use its LowerExp implementation when
Debug-formatted.Source§fn fmt_lower_hex(self) -> FmtLowerHex<Self>where
Self: LowerHex,
fn fmt_lower_hex(self) -> FmtLowerHex<Self>where
Self: LowerHex,
self to use its LowerHex implementation when
Debug-formatted.Source§fn fmt_octal(self) -> FmtOctal<Self>where
Self: Octal,
fn fmt_octal(self) -> FmtOctal<Self>where
Self: Octal,
self to use its Octal implementation when Debug-formatted.Source§fn fmt_pointer(self) -> FmtPointer<Self>where
Self: Pointer,
fn fmt_pointer(self) -> FmtPointer<Self>where
Self: Pointer,
self to use its Pointer implementation when
Debug-formatted.Source§fn fmt_upper_exp(self) -> FmtUpperExp<Self>where
Self: UpperExp,
fn fmt_upper_exp(self) -> FmtUpperExp<Self>where
Self: UpperExp,
self to use its UpperExp implementation when
Debug-formatted.Source§fn fmt_upper_hex(self) -> FmtUpperHex<Self>where
Self: UpperHex,
fn fmt_upper_hex(self) -> FmtUpperHex<Self>where
Self: UpperHex,
self to use its UpperHex implementation when
Debug-formatted.impl<T> Fruit for T
Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
Source§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§impl<T> Pipe for Twhere
T: ?Sized,
impl<T> Pipe for Twhere
T: ?Sized,
Source§fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> Rwhere
Self: Sized,
fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> Rwhere
Self: Sized,
Source§fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> Rwhere
R: 'a,
fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> Rwhere
R: 'a,
self and passes that borrow into the pipe function. Read moreSource§fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> Rwhere
R: 'a,
fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> Rwhere
R: 'a,
self and passes that borrow into the pipe function. Read moreSource§fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R
fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R
Source§fn pipe_borrow_mut<'a, B, R>(
&'a mut self,
func: impl FnOnce(&'a mut B) -> R,
) -> R
fn pipe_borrow_mut<'a, B, R>( &'a mut self, func: impl FnOnce(&'a mut B) -> R, ) -> R
Source§fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R
fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R
self, then passes self.as_ref() into the pipe function.Source§fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R
fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R
self, then passes self.as_mut() into the pipe
function.Source§fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R
fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R
self, then passes self.deref() into the pipe function.Source§impl<T> Pointable for T
impl<T> Pointable for T
impl<T> Read<Exclusive, BecauseExclusive> for Twhere
T: ?Sized,
Source§impl<T> Tap for T
impl<T> Tap for T
Source§fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
Borrow<B> of a value. Read moreSource§fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
BorrowMut<B> of a value. Read moreSource§fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
AsRef<R> view of a value. Read moreSource§fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
AsMut<R> view of a value. Read moreSource§fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
Deref::Target of a value. Read moreSource§fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
Deref::Target of a value. Read moreSource§fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self
fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self
.tap() only in debug builds, and is erased in release builds.Source§fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
.tap_mut() only in debug builds, and is erased in release
builds.Source§fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
.tap_borrow() only in debug builds, and is erased in release
builds.Source§fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self
fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self
.tap_borrow_mut() only in debug builds, and is erased in release
builds.Source§fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
.tap_ref() only in debug builds, and is erased in release
builds.Source§fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self
fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self
.tap_ref_mut() only in debug builds, and is erased in release
builds.Source§fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
.tap_deref() only in debug builds, and is erased in release
builds.