Struct PostgresEventStore
#[non_exhaustive]pub struct PostgresEventStore { /* private fields */ }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
impl PostgresEventStore
pub const MAX_EVENT_DATA_LEN: usize = 1_048_576
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
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
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
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.sqlxacquires every connection undertokio::time::timeout, so a call from a runtime built withoutenable_timefails asWorkercarrying a panickedJoinError, and opening a new connection needsenable_ioas well. - Open
poolon 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,sqlxdoes not see the connection as broken, and a query handed it ends inPoolTimedOutor 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 astaticinitialised 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>
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
PostgresEventStoreError::MissingIdentityifstore_metahas nostore_idrow, which means migration 1 has not been applied. No row is created.PostgresEventStoreError::MalformedIdentityif the minted row does not read back as sixteen bytes.PostgresEventStoreError::Driverif the server refuses the statement, andPostgresEventStoreError::NoRuntimeorPostgresEventStoreError::Workeras for every other operation.
§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
pub fn pool(&self) -> &PgPool
The pool this store reads and writes through.
Trait Implementations§
§impl Clone for PostgresEventStore
impl Clone for PostgresEventStore
§impl Debug for PostgresEventStore
impl Debug for PostgresEventStore
§impl SendEventStore for PostgresEventStore
impl SendEventStore for PostgresEventStore
§async fn append(
&self,
events: &[Event],
condition: Option<&AppendCondition>,
) -> Result<SequencePosition, AppendError<Self::Error>>
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>
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
type Error = PostgresEventStoreError
§fn read(
&self,
query: &Query,
options: ReadOptions,
) -> impl Stream<Item = Result<SequencedEvent, Self::Error>> + Send
fn read( &self, query: &Query, options: ReadOptions, ) -> impl Stream<Item = Result<SequencedEvent, Self::Error>> + Send
§impl SendIngestStore for PostgresEventStore
Available on crate feature sync only.
impl SendIngestStore for PostgresEventStore
sync only.§async fn store_id(&self) -> Result<StoreId, Self::Error>
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
type Error = PostgresEventStoreError
§async fn ingest(
&self,
groups: &[IngestGroup<'_>],
) -> Result<Ingested, IngestError<Self::Error>>
async fn ingest( &self, groups: &[IngestGroup<'_>], ) -> Result<Ingested, IngestError<Self::Error>>
§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.
impl SendWriteGroupStore for PostgresEventStore
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
type Error = PostgresEventStoreError
§async fn read_groups(
&self,
after: Option<SequencePosition>,
max_events: NonZeroUsize,
) -> Result<GroupPage, Self::Error>
async fn read_groups( &self, after: Option<SequencePosition>, max_events: NonZeroUsize, ) -> Result<GroupPage, Self::Error>
Auto Trait Implementations§
impl !RefUnwindSafe for PostgresEventStore
impl !UnwindSafe for PostgresEventStore
impl Freeze for PostgresEventStore
impl Send for PostgresEventStore
impl Sync for PostgresEventStore
impl Unpin for PostgresEventStore
impl UnsafeUnpin for PostgresEventStore
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<TraitVariantBlanketType> EventStore for TraitVariantBlanketTypewhere
TraitVariantBlanketType: SendEventStore,
impl<TraitVariantBlanketType> EventStore for TraitVariantBlanketTypewhere
TraitVariantBlanketType: SendEventStore,
Source§type Error = <TraitVariantBlanketType as SendEventStore>::Error
type Error = <TraitVariantBlanketType as SendEventStore>::Error
Source§fn read(
&self,
query: &Query,
options: ReadOptions,
) -> impl Stream<Item = Result<SequencedEvent, <TraitVariantBlanketType as EventStore>::Error>>
fn read( &self, query: &Query, options: ReadOptions, ) -> impl Stream<Item = Result<SequencedEvent, <TraitVariantBlanketType as EventStore>::Error>>
Source§async fn append(
&self,
events: &[Event],
condition: Option<&AppendCondition>,
) -> Result<SequencePosition, AppendError<<TraitVariantBlanketType as EventStore>::Error>>
async fn append( &self, events: &[Event], condition: Option<&AppendCondition>, ) -> Result<SequencePosition, AppendError<<TraitVariantBlanketType as EventStore>::Error>>
Source§async fn head(
&self,
) -> Result<Option<SequencePosition>, <TraitVariantBlanketType as EventStore>::Error>
async fn head( &self, ) -> Result<Option<SequencePosition>, <TraitVariantBlanketType as EventStore>::Error>
None when it
holds nothing. Read moreSource§async fn contains_event_id(
&self,
id: EventId,
) -> Result<bool, <TraitVariantBlanketType as EventStore>::Error>
async fn contains_event_id( &self, id: EventId, ) -> Result<bool, <TraitVariantBlanketType as EventStore>::Error>
id. Read moreSource§impl<TraitVariantBlanketType> IngestStore for TraitVariantBlanketTypewhere
TraitVariantBlanketType: SendIngestStore,
impl<TraitVariantBlanketType> IngestStore for TraitVariantBlanketTypewhere
TraitVariantBlanketType: SendIngestStore,
Source§type Error = <TraitVariantBlanketType as SendIngestStore>::Error
type Error = <TraitVariantBlanketType as SendIngestStore>::Error
Source§async fn store_id(
&self,
) -> Result<StoreId, <TraitVariantBlanketType as IngestStore>::Error>
async fn store_id( &self, ) -> Result<StoreId, <TraitVariantBlanketType as IngestStore>::Error>
Source§async fn ingest(
&self,
groups: &[IngestGroup<'_>],
) -> Result<Ingested, IngestError<<TraitVariantBlanketType as IngestStore>::Error>>
async fn ingest( &self, groups: &[IngestGroup<'_>], ) -> Result<Ingested, IngestError<<TraitVariantBlanketType as IngestStore>::Error>>
§impl<T> Instrument for T
impl<T> Instrument for T
§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> 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 more