Skip to main content

PostgresEventStore

Struct PostgresEventStore 

#[non_exhaustive]
pub struct PostgresEventStore { /* private fields */ }
Available on crate feature event-store only.
Expand description

A Postgres-backed event store.

Holds a [PgPool] rather than a connection, which is the shape difference that makes this crate an instrument: readers and writers do not queue behind one another, so nothing about the storage layer supplies ES-10 for free.

§What this store does not promise

It buys ES-10 on the read side, with xid8 + pg_snapshot_xmin, so head reports a visibility frontier rather than the highest position assigned, and read-your-own-writes does not hold. Staleness is bounded by the longest open write transaction anywhere on the cluster. Those are capability limits rather than defects; the crate root states them in full, and append and head each state the half a caller meets there.

Implementations§

§

impl PostgresEventStore

pub const MAX_EVENT_DATA_LEN: usize = 1_048_576

The largest data payload this store accepts, in bytes of Event::data — not of an encoded row, and not of data and metadata together.

A fact about this adapter, not a trade. Postgres’s own ceilings are far above it and are not the binding constraint: a bytea field tops out near 1 GB, and the wire protocol’s Bind message near the same. Either number is unusable as a stated ceiling, because append_reports_exceeded_store_limits allocates the ceiling plus one byte and does it twice per run — a suite that pins a gigabyte per rule is a suite nobody runs.

So this is an adapter policy, enforced in append before anything reaches the wire, and it is deliberately the same number happenstance-sqlite states: sixteen times VT-21’s 65,536-byte floor. Two adapters agreeing on a policy number is worth more than two adapters each deriving a different one from a limit neither is anywhere near.

pub const MAX_TAGS_PER_EVENT: usize = 128

The largest number of tags on one event this store accepts.

Twice VT-22’s floor of 64. Tags live in one text[] column rather than in a join table, so unlike the SQLite adapter a tag costs no extra row and no extra statement inside the write transaction — the cost here is the GIN index’s, which builds one entry per element. Like the other two, a policy rather than a server limit; see MAX_EVENT_DATA_LEN.

pub const MAX_EVENTS_PER_BATCH: usize = 256

The largest number of events this store accepts in one append.

Twice VT-24’s floor of 128, and the one of the three where a real Postgres limit is close enough to be worth writing down. The extended query protocol carries its parameter count in an int16, so one statement binds at most 65,535 parameters; at eight columns per event that is 8,191 events in a single multi-row INSERT … VALUES. An append built out of array parameters instead — UNNEST($1::bigint[], …) — binds eight parameters whatever the batch size and has no such bound at all.

Which of those two shapes append takes is not settled here, so this ceiling is deliberately far below both rather than derived from either: a number that encodes an unchosen SQL strategy is a decision taken by accident. postgres-append-and-frontier-head may raise it against evidence, and append_reports_exceeded_store_limits is what would find the current value wrong.

pub fn new(pool: PgPool) -> Self

Wraps an existing pool.

Takes a pool rather than a connection string because pool sizing, timeouts and TLS are the application’s business, and because a store that builds its own pool cannot share one with the projection store beside it.

§Runtimes

Every operation runs on the tokio runtime it is called on. The runtime current here, at construction, is used only by a call made from a thread with no runtime at all (ADR-0081). Two obligations follow, and both are the application’s, because it builds the pool and the runtimes:

  • Call the store from a runtime with tokio’s drivers enabled: enable_all, as #[tokio::main] and #[tokio::test] do. sqlx acquires every connection under tokio::time::timeout, so a call from a runtime built without enable_time fails as Worker carrying a panicked JoinError, and opening a new connection needs enable_io as well.
  • Open pool on a runtime that lives at least as long as the pool. A pooled connection’s socket belongs to the I/O driver of the runtime that opened it. Once that runtime is dropped, sqlx does not see the connection as broken, and a query handed it ends in PoolTimedOut or does not finish. A pool opens connections lazily, inside the call that needs one, so the runtimes this store is called on should outlive the pool too. A pool in a static initialised inside one #[tokio::test] and used by the next, each on its own runtime, is the usual way to break this.

pub async fn remint_identity(&self) -> Result<StoreId, PostgresEventStoreError>

Replaces the database’s persisted identity with a freshly minted one, and returns it.

§When a deployment invokes this

After a pg_restore, a point-in-time recovery, a promoted replica that lost acknowledged writes, or any other copy of this store’s database. This store mints its identity once, in migration 1, and keeps it. A copy brings that row back together with an older position sequence, and would then re-issue EventIds it has already issued for different events, which a replication peer drops as already seen, with no error anywhere. VT-6 permits mint-once only for an adapter that can detect a restore, or whose deployment is documented to invoke a re-mint. Nothing measured here can detect a restore into the same database, so this operation is the second half of that permission rather than a convenience (ADR-0086). Minting afresh on every open was considered and declined there.

Stop every writer to the copy first, call this, then resume appends. The crate root’s After a restore, re-mint before the first append is the procedure in full.

§Handles

No handle holds a copy of the identity: every append reads the row inside its own transaction. So a handle built or cloned before this call, in this process or another, stamps the new identity on its next append, and nothing has to be restarted.

An append racing this call may stamp the retired identity. Where no restore happened that is harmless: the re-mint does not rewind the sequence, so the row still takes a position the retired identity never stamped. After a restore it is not, because the restore rewound the sequence, and such a row pairs the retired identity with a position the original store has already issued under it. That is why every writer must be stopped before this call, not merely before the next append.

§What it does not change

Events already in the database keep the identity they were stamped with, which is correct: they were written by the incarnation being retired. A re-mint when no restore happened breaks nothing; it only starts a new origin for later events.

It applies no migration. Like every other method here, it acts on whatever schema the pool’s search_path resolves to, and refuses rather than minting into a schema migration 1 never ran on.

§Errors
§Examples
use happenstance_postgres::error::PostgresEventStoreError;
use happenstance_postgres::event_store::PostgresEventStore;
use happenstance_postgres::sqlx::PgPool;

// Every writer to the restored copy is stopped.
let store = PostgresEventStore::new(pool);
let _new_identity = store.remint_identity().await?;
// Appends may resume, through this handle or any other.

pub fn pool(&self) -> &PgPool

The pool this store reads and writes through.

Trait Implementations§

§

impl Clone for PostgresEventStore

§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
§

impl Debug for PostgresEventStore

§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
§

impl SendEventStore for PostgresEventStore

§

async fn append( &self, events: &[Event], condition: Option<&AppendCondition>, ) -> Result<SequencePosition, AppendError<Self::Error>>

Appends a batch and returns the position of its last event.

§What Ok(P) does and does not promise

It promises that the batch is committed, at positions ending at P, and that the append condition held when it was evaluated.

It does not promise that the next head is at or above P, and it does not promise that a read issued immediately afterwards contains what was just written. This store reports a visibility frontier, the frontier trails the positions it has already assigned, and read-your-own-writes does not hold.

That is a documented capability limit of this adapter rather than a bug to report: there is no setting that turns it off, and the staleness is bounded by the longest open write transaction anywhere on the cluster — measured at a median of 0.593 ms with no holder, and 4,799 ms behind a five-second write transaction held in an unrelated database. A caller who needs the position immediately should keep the one this method returned rather than reading it back; the crate root explains why reading it back is not available here.

§Errors

AppendError::NoEvents for an empty batch, refused before the condition is evaluated; AppendError::ExceedsStoreLimit for a batch over one of this store’s stated ceilings, refused before anything reaches the wire; AppendError::ConditionViolated when the condition found a matching event, which is not an adapter failure; AppendError::Busy for a serialisation failure (40001) that outlived this store’s own retry budget, which aborted every attempt whole and so wrote nothing; and AppendError::Store for anything else the driver or this adapter reports, a deadlock (40P01) and a connection lost around COMMIT included.

§

async fn head(&self) -> Result<Option<SequencePosition>, Self::Error>

The highest position beneath this store’s visibility frontier, or None when nothing is visible yet.

§What a frontier is, and why it is not max(position)

A head is a promise that nothing at or below it will appear later (ES-10). max(position) cannot make that promise here: nextval() allocates outside the transaction, so the highest position assigned can name a row whose predecessors are still in flight. Each row therefore stamps its appending transaction’s xid8, and the frontier is pg_snapshot_xmin(pg_current_snapshot()) — the transaction id below which nothing can still be running. Everything beneath it has settled, and that is what this method reports.

The frontier legitimately trails the position append just returned, so read-your-own-writes does not hold and this crate does not claim it; ES-30’s head_is_the_highest_visible_position asserts a bound rather than an equality precisely to admit that. How far it trails is bounded by the longest open write transaction anywhere on the cluster — a median of 0.593 ms with no holder, and 4,799 ms behind a five-second write held in an unrelated database, against an unguarded arm unaffected by the same hold at 0.595 ms. A documented capability limit, not a tuning knob: nothing an operator configures moves it.

§Errors

The adapter’s own error if the query fails, or if a stored position cannot be decoded — which is a corrupt store and is deliberately not spelled the same way as an empty one.

§

type Error = PostgresEventStoreError

How this adapter fails for its own reasons. Read more
§

fn read( &self, query: &Query, options: ReadOptions, ) -> impl Stream<Item = Result<SequencedEvent, Self::Error>> + Send

Reads the events matching query, in the order options asks for. Read more
§

async fn contains_event_id(&self, id: EventId) -> Result<bool, Self::Error>

Whether this store holds an event with id. Read more
§

impl SendIngestStore for PostgresEventStore

Available on crate feature sync only.
§

async fn store_id(&self) -> Result<StoreId, Self::Error>

The identity store_meta holds, read on every call. Nothing is cached (ADR-0086), so a re-mint is answered by the next call on any handle, clones included.

§

type Error = PostgresEventStoreError

How this store fails, stating a class so a runner never infers one.
§

async fn ingest( &self, groups: &[IngestGroup<'_>], ) -> Result<Ingested, IngestError<Self::Error>>

Records events other stores minted, preserving their identity, together with any compensation this side writes for them. Read more
§

async fn watermark(&self) -> Result<Watermark, Self::Error>

The highest origin position this store holds from each origin store. Read more
§

impl SendWriteGroupStore for PostgresEventStore

Available on crate feature sync only.

The log in the writes that made it (SY-39): what a runner pushes from and a StoreSyncPeer serves a pull from. The Send flavour, as this store’s SendIngestStore is; trait_variant derives the bare one.

§

type Error = PostgresEventStoreError

How this store fails, stating a class so a runner never infers one.
§

async fn read_groups( &self, after: Option<SequencePosition>, max_events: NonZeroUsize, ) -> Result<GroupPage, Self::Error>

The write groups whose first position is above after (every group when None), in ascending first order, each whole. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<TraitVariantBlanketType> EventStore for TraitVariantBlanketType
where TraitVariantBlanketType: SendEventStore,

Source§

type Error = <TraitVariantBlanketType as SendEventStore>::Error

How this adapter fails for its own reasons. Read more
Source§

fn read( &self, query: &Query, options: ReadOptions, ) -> impl Stream<Item = Result<SequencedEvent, <TraitVariantBlanketType as EventStore>::Error>>

Reads the events matching query, in the order options asks for. Read more
Source§

async fn append( &self, events: &[Event], condition: Option<&AppendCondition>, ) -> Result<SequencePosition, AppendError<<TraitVariantBlanketType as EventStore>::Error>>

Atomically appends events, rejecting the write if condition matches. Read more
Source§

async fn head( &self, ) -> Result<Option<SequencePosition>, <TraitVariantBlanketType as EventStore>::Error>

The highest position currently visible in the store, or None when it holds nothing. Read more
Source§

async fn contains_event_id( &self, id: EventId, ) -> Result<bool, <TraitVariantBlanketType as EventStore>::Error>

Whether this store holds an event with id. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<TraitVariantBlanketType> IngestStore for TraitVariantBlanketType
where TraitVariantBlanketType: SendIngestStore,

Source§

type Error = <TraitVariantBlanketType as SendIngestStore>::Error

How this store fails, stating a class so a runner never infers one.
Source§

async fn store_id( &self, ) -> Result<StoreId, <TraitVariantBlanketType as IngestStore>::Error>

This store’s own incarnation identifier. Read more
Source§

async fn ingest( &self, groups: &[IngestGroup<'_>], ) -> Result<Ingested, IngestError<<TraitVariantBlanketType as IngestStore>::Error>>

Records events other stores minted, preserving their identity, together with any compensation this side writes for them. Read more
Source§

async fn watermark( &self, ) -> Result<Watermark, <TraitVariantBlanketType as IngestStore>::Error>

The highest origin position this store holds from each origin store. Read more
§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts 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 more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts 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 more
§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more
Source§

impl<TraitVariantBlanketType> WriteGroupStore for TraitVariantBlanketType
where TraitVariantBlanketType: SendWriteGroupStore,

Source§

type Error = <TraitVariantBlanketType as SendWriteGroupStore>::Error

How this store fails, stating a class so a runner never infers one.
Source§

async fn read_groups( &self, after: Option<SequencePosition>, max_events: NonZero<usize>, ) -> Result<GroupPage, <TraitVariantBlanketType as WriteGroupStore>::Error>

The write groups whose first position is above after (every group when None), in ascending first order, each whole. Read more