#![forbid(unsafe_code)]
#![allow(dead_code)]
use std::{
collections::{HashMap, HashSet, VecDeque},
fmt,
sync::{
Arc, RwLock,
atomic::{AtomicUsize, Ordering},
},
time::Duration,
};
use futures_util::stream;
use sqlx::{PgPool, Postgres, Row, Transaction, postgres::PgPoolOptions};
use tokio::sync::{OnceCell, mpsc, oneshot};
use crate::{
AppendOutcome, AtomicWrite, DurableStateStore, EventStream, Journal, PersistenceError,
PersistenceId, PersistenceResult, ReplayRange, Revision, SelectedSnapshot, SequenceNr,
SerializedPayload, SerializerId, SnapshotCriteria, SnapshotMetadata, SnapshotStore,
StoredEvent, Tag, VersionedState,
query::{
DeletedDurableState, DurableStateChange, DurableStateChangesQuery, EventEnvelope,
EventsByPersistenceIdQuery, EventsBySlicesQuery, EventsByTagQuery, Offset,
PersistenceIdsQuery, QueryMode, QueryStream, SLICE_COUNT, SliceRange, UpdatedDurableState,
slice_for,
},
};
const DEFAULT_MAX_CONNECTIONS: u32 = 16;
const DEFAULT_ACQUIRE_TIMEOUT: Duration = Duration::from_secs(30);
const DEFAULT_IDLE_TIMEOUT: Duration = Duration::from_secs(600);
const DEFAULT_MAX_LIFETIME: Duration = Duration::from_secs(1_800);
const DEFAULT_REPLAY_PAGE_SIZE: u32 = 2048;
const DEFAULT_POLL_MIN_INTERVAL: Duration = Duration::from_millis(50);
const DEFAULT_POLL_MAX_INTERVAL: Duration = Duration::from_secs(2);
const DEFAULT_POLL_BATCH_SIZE: u32 = 256;
const DEFAULT_QUERY_VISIBILITY_LAG: Duration = Duration::from_millis(250);
const MAX_TABLE_IDENTIFIER_BYTES: usize = 48;
const JOURNAL_COLUMN_COUNT: usize = 14;
const MAX_JOURNAL_ROWS_PER_INSERT: usize = 65_535 / JOURNAL_COLUMN_COUNT;
const INSERT_SQL_CACHE_CAP: usize = 64;
const DEFAULT_GROUP_COMMIT_QUEUE_CAPACITY: usize = 4_096;
const DEFAULT_GROUP_COMMIT_MAX_ATOMIC_WRITES: usize = 256;
const DEFAULT_GROUP_COMMIT_MAX_EVENTS: usize = 4_096;
const DEFAULT_GROUP_COMMIT_MAX_LINGER: Duration = Duration::from_micros(100);
const DEFAULT_GROUP_COMMIT_BYPASS_BELOW: usize = DEFAULT_MAX_CONNECTIONS as usize;
const TEST_GROUP_BARRIER_TIMEOUT: Duration = Duration::from_secs(10);
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub enum PostgresDeletePolicy {
#[default]
Soft,
Hard,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PostgresPollingConfig {
pub min_interval: Duration,
pub max_interval: Duration,
pub batch_size: u32,
pub visibility_lag: Duration,
}
impl Default for PostgresPollingConfig {
fn default() -> Self {
Self {
min_interval: DEFAULT_POLL_MIN_INTERVAL,
max_interval: DEFAULT_POLL_MAX_INTERVAL,
batch_size: DEFAULT_POLL_BATCH_SIZE,
visibility_lag: DEFAULT_QUERY_VISIBILITY_LAG,
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PostgresGroupCommitConfig {
pub enabled: bool,
pub queue_capacity: usize,
pub max_atomic_writes: usize,
pub max_events: usize,
pub max_linger: Duration,
pub bypass_below: usize,
}
impl Default for PostgresGroupCommitConfig {
fn default() -> Self {
Self {
enabled: true,
queue_capacity: DEFAULT_GROUP_COMMIT_QUEUE_CAPACITY,
max_atomic_writes: DEFAULT_GROUP_COMMIT_MAX_ATOMIC_WRITES,
max_events: DEFAULT_GROUP_COMMIT_MAX_EVENTS,
max_linger: DEFAULT_GROUP_COMMIT_MAX_LINGER,
bypass_below: DEFAULT_GROUP_COMMIT_BYPASS_BELOW,
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PostgresTableNames {
pub event_journal: String,
pub snapshot: String,
pub durable_state: String,
pub journal_head: String,
}
impl Default for PostgresTableNames {
fn default() -> Self {
Self {
event_journal: "event_journal".into(),
snapshot: "snapshot".into(),
durable_state: "durable_state".into(),
journal_head: "journal_head".into(),
}
}
}
#[derive(Clone)]
pub struct PostgresPersistenceConfig {
pub database_url: Option<String>,
pub max_connections: u32,
pub min_connections: u32,
pub acquire_timeout: Duration,
pub idle_timeout: Option<Duration>,
pub max_lifetime: Option<Duration>,
pub schema: String,
pub tables: PostgresTableNames,
pub delete_policy: PostgresDeletePolicy,
pub replay_page_size: u32,
pub polling: PostgresPollingConfig,
pub group_commit: PostgresGroupCommitConfig,
}
impl fmt::Debug for PostgresPersistenceConfig {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("PostgresPersistenceConfig")
.field(
"database_url",
&self.database_url.as_ref().map(|_| "<redacted>"),
)
.field("max_connections", &self.max_connections)
.field("min_connections", &self.min_connections)
.field("acquire_timeout", &self.acquire_timeout)
.field("idle_timeout", &self.idle_timeout)
.field("max_lifetime", &self.max_lifetime)
.field("schema", &self.schema)
.field("tables", &self.tables)
.field("delete_policy", &self.delete_policy)
.field("replay_page_size", &self.replay_page_size)
.field("polling", &self.polling)
.field("group_commit", &self.group_commit)
.finish()
}
}
impl PostgresPersistenceConfig {
#[must_use]
pub fn new(database_url: impl Into<String>) -> Self {
Self {
database_url: Some(database_url.into()),
max_connections: DEFAULT_MAX_CONNECTIONS,
min_connections: 0,
acquire_timeout: DEFAULT_ACQUIRE_TIMEOUT,
idle_timeout: Some(DEFAULT_IDLE_TIMEOUT),
max_lifetime: Some(DEFAULT_MAX_LIFETIME),
schema: "public".into(),
tables: PostgresTableNames::default(),
delete_policy: PostgresDeletePolicy::default(),
replay_page_size: DEFAULT_REPLAY_PAGE_SIZE,
polling: PostgresPollingConfig::default(),
group_commit: PostgresGroupCommitConfig::default(),
}
}
#[must_use]
pub fn for_pool() -> Self {
let mut config = Self::new(String::new());
config.database_url = None;
config
}
}
#[derive(Debug)]
struct PostgresSql {
event_journal: String,
snapshot: String,
durable_state: String,
journal_head: String,
ddl: Vec<String>,
lock_head_sql: String,
update_head_sql: String,
insert_sql_cache: RwLock<HashMap<usize, Arc<str>>>,
}
impl PostgresSql {
fn new(config: &PostgresPersistenceConfig) -> PersistenceResult<Self> {
validate_config(config)?;
let schema_identifier = quote_identifier(&config.schema);
let event_journal = qualified(&config.schema, &config.tables.event_journal);
let snapshot = qualified(&config.schema, &config.tables.snapshot);
let durable_state = qualified(&config.schema, &config.tables.durable_state);
let journal_head = qualified(&config.schema, &config.tables.journal_head);
let tags_index = quote_identifier(&format!("{}_tags_gin_idx", config.tables.event_journal));
let slice_index = quote_identifier(&format!(
"{}_slice_timestamp_idx",
config.tables.event_journal
));
let durable_state_index = quote_identifier(&format!(
"{}_tag_timestamp_idx",
config.tables.durable_state
));
let ddl = vec![
format!("CREATE SCHEMA IF NOT EXISTS {schema_identifier}"),
format!(
"CREATE TABLE IF NOT EXISTS {event_journal} (\
persistence_id TEXT NOT NULL,\
seq_nr BIGINT NOT NULL CHECK (seq_nr >= 0),\
slice INTEGER NOT NULL CHECK (slice >= 0 AND slice < {SLICE_COUNT}),\
entity_type TEXT NOT NULL,\
db_timestamp TIMESTAMPTZ NOT NULL DEFAULT now(),\
writer TEXT NOT NULL,\
adapter_manifest TEXT NOT NULL,\
ser_id BIGINT NOT NULL CHECK (ser_id >= 0),\
ser_manifest TEXT NOT NULL,\
payload BYTEA NOT NULL,\
meta_ser_id BIGINT,\
meta_manifest TEXT,\
meta_payload BYTEA,\
tags TEXT[] NOT NULL DEFAULT '{{}}',\
deleted BOOLEAN NOT NULL DEFAULT FALSE,\
PRIMARY KEY (persistence_id, seq_nr),\
CHECK ((meta_ser_id IS NULL AND meta_manifest IS NULL AND meta_payload IS NULL) OR \
(meta_ser_id IS NOT NULL AND meta_manifest IS NOT NULL AND meta_payload IS NOT NULL))\
)"
),
format!("CREATE INDEX IF NOT EXISTS {tags_index} ON {event_journal} USING GIN (tags)"),
format!(
"CREATE INDEX IF NOT EXISTS {slice_index} ON {event_journal} \
(slice, db_timestamp, seq_nr)"
),
format!(
"CREATE TABLE IF NOT EXISTS {snapshot} (\
persistence_id TEXT NOT NULL,\
seq_nr BIGINT NOT NULL CHECK (seq_nr >= 0),\
timestamp_ms BIGINT NOT NULL,\
adapter_manifest TEXT NOT NULL,\
ser_id BIGINT NOT NULL CHECK (ser_id >= 0),\
ser_manifest TEXT NOT NULL,\
payload BYTEA NOT NULL,\
PRIMARY KEY (persistence_id, seq_nr)\
)"
),
format!(
"CREATE TABLE IF NOT EXISTS {durable_state} (\
persistence_id TEXT PRIMARY KEY,\
revision BIGINT NOT NULL CHECK (revision >= 0),\
tag TEXT,\
ser_id BIGINT,\
ser_manifest TEXT,\
payload BYTEA,\
deleted BOOLEAN NOT NULL DEFAULT FALSE,\
db_timestamp TIMESTAMPTZ NOT NULL DEFAULT now(),\
CHECK ((deleted AND ser_id IS NULL AND ser_manifest IS NULL AND payload IS NULL) OR \
(NOT deleted AND ser_id IS NOT NULL AND ser_manifest IS NOT NULL AND payload IS NOT NULL))\
)"
),
format!(
"CREATE INDEX IF NOT EXISTS {durable_state_index} ON {durable_state} \
(tag, db_timestamp)"
),
format!(
"CREATE TABLE IF NOT EXISTS {journal_head} (\
persistence_id TEXT PRIMARY KEY,\
highest_seq_nr BIGINT NOT NULL CHECK (highest_seq_nr >= 0),\
deleted_to BIGINT NOT NULL DEFAULT 0 CHECK (deleted_to >= 0)\
)"
),
];
let lock_head_sql = format!(
"SELECT highest_seq_nr FROM {journal_head} WHERE persistence_id = $1 FOR UPDATE"
);
let update_head_sql =
format!("UPDATE {journal_head} SET highest_seq_nr = $2 WHERE persistence_id = $1");
Ok(Self {
event_journal,
snapshot,
durable_state,
journal_head,
ddl,
lock_head_sql,
update_head_sql,
insert_sql_cache: RwLock::new(HashMap::new()),
})
}
fn journal_insert_sql(&self, row_count: usize) -> Arc<str> {
if let Some(cached) = self
.insert_sql_cache
.read()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.get(&row_count)
{
return Arc::clone(cached);
}
let mut cache = self
.insert_sql_cache
.write()
.unwrap_or_else(std::sync::PoisonError::into_inner);
if let Some(cached) = cache.get(&row_count) {
return Arc::clone(cached);
}
if cache.len() >= INSERT_SQL_CACHE_CAP {
cache.clear();
}
let sql: Arc<str> = Arc::from(journal_insert_sql_text(&self.event_journal, row_count));
Arc::clone(cache.entry(row_count).or_insert(sql))
}
}
pub struct PostgresPersistence {
config: PostgresPersistenceConfig,
sql: Arc<PostgresSql>,
pool: OnceCell<PgPool>,
initialized: OnceCell<()>,
group_commit: OnceCell<GroupCommitHandle>,
group_commit_min_group: Arc<AtomicUsize>,
inflight_appends: Arc<AtomicUsize>,
}
impl fmt::Debug for PostgresPersistence {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("PostgresPersistence")
.field("config", &self.config)
.field("has_pool", &self.pool.get().is_some())
.field("initialized", &self.initialized.get().is_some())
.field("group_commit_active", &self.group_commit.get().is_some())
.finish()
}
}
impl PostgresPersistence {
pub fn new(config: PostgresPersistenceConfig) -> PersistenceResult<Self> {
let sql = Arc::new(PostgresSql::new(&config)?);
if config.database_url.as_deref().is_none_or(str::is_empty) {
return Err(PersistenceError::Rejected(
"PostgreSQL database_url is required when no PgPool is supplied".into(),
));
}
Ok(Self {
config,
sql,
pool: OnceCell::new(),
initialized: OnceCell::new(),
group_commit: OnceCell::new(),
group_commit_min_group: Arc::new(AtomicUsize::new(0)),
inflight_appends: Arc::new(AtomicUsize::new(0)),
})
}
pub fn from_pool(pool: PgPool, config: PostgresPersistenceConfig) -> PersistenceResult<Self> {
let sql = Arc::new(PostgresSql::new(&config)?);
Ok(Self {
config,
sql,
pool: OnceCell::new_with(Some(pool)),
initialized: OnceCell::new(),
group_commit: OnceCell::new(),
group_commit_min_group: Arc::new(AtomicUsize::new(0)),
inflight_appends: Arc::new(AtomicUsize::new(0)),
})
}
pub async fn connect(config: PostgresPersistenceConfig) -> PersistenceResult<Self> {
let backend = Self::new(config)?;
backend.initialize().await?;
Ok(backend)
}
pub async fn initialize(&self) -> PersistenceResult<()> {
let pool = self.ready_pool_without_schema().await?;
self.initialized
.get_or_try_init(|| async { bootstrap(pool, &self.sql.ddl).await })
.await
.map(|_| ())
}
#[must_use]
pub fn pool(&self) -> Option<&PgPool> {
self.pool.get()
}
#[must_use]
pub fn config(&self) -> &PostgresPersistenceConfig {
&self.config
}
#[must_use]
pub fn schema_ddl(&self) -> String {
let mut ddl = self.sql.ddl.join(";\n");
ddl.push(';');
ddl
}
async fn ready_pool_without_schema(&self) -> PersistenceResult<&PgPool> {
self.pool
.get_or_try_init(|| async {
let database_url = self.config.database_url.as_deref().ok_or_else(|| {
PersistenceError::Rejected(
"PostgreSQL database_url is required when no PgPool is supplied".into(),
)
})?;
pool_options(&self.config)
.connect(database_url)
.await
.map_err(|error| connection_error("connect PostgreSQL pool", error))
})
.await
}
async fn ready_pool(&self) -> PersistenceResult<&PgPool> {
self.initialize().await?;
self.pool.get().ok_or_else(|| {
PersistenceError::Connection(
"PostgreSQL pool was unavailable after successful initialization".into(),
)
})
}
#[doc(hidden)]
pub fn force_group_commit_min_group(&self, min_group: usize) {
self.group_commit_min_group
.store(min_group, Ordering::SeqCst);
}
fn enter_inflight_append(&self) -> (InflightAppendGuard<'_>, usize) {
let demand_before = self.inflight_appends.fetch_add(1, Ordering::AcqRel);
(
InflightAppendGuard {
inflight: &self.inflight_appends,
},
demand_before,
)
}
fn should_bypass_group_commit(&self, demand_before: usize) -> bool {
let bypass_below = self.config.group_commit.bypass_below;
bypass_below > 0 && demand_before < bypass_below
}
async fn append_write_solo(&self, write: AtomicWrite) -> PersistenceResult<AppendOutcome> {
let prepared = match prepare_atomic_write(write) {
Ok(prepared) => prepared,
Err(reason) => return Ok(AppendOutcome::Rejected { reason }),
};
let pool = self.ready_pool().await?;
let mut transaction = pool
.begin()
.await
.map_err(|error| storage_error("begin journal append transaction", error))?;
let lock_head = &self.sql.lock_head_sql;
let existing_head = sqlx::query(lock_head)
.bind(prepared.persistence_id.id())
.fetch_optional(&mut *transaction)
.await
.map_err(|error| storage_error("lock journal head", error))?;
let highest = if let Some(row) = existing_head {
let highest: i64 = row
.try_get("highest_seq_nr")
.map_err(|error| storage_error("decode journal head", error))?;
if let Err(reason) = validate_first_sequence(&prepared, highest) {
return rollback_rejection(transaction, reason).await;
}
highest
} else {
let fallback = format!(
"SELECT COALESCE(MAX(seq_nr), 0) AS highest_seq_nr FROM {} \
WHERE persistence_id = $1",
self.sql.event_journal
);
let row = sqlx::query(&fallback)
.bind(prepared.persistence_id.id())
.fetch_one(&mut *transaction)
.await
.map_err(|error| storage_error("read headless journal watermark", error))?;
let fallback_highest: i64 = row
.try_get("highest_seq_nr")
.map_err(|error| storage_error("decode headless journal watermark", error))?;
if let Err(reason) = validate_first_sequence(&prepared, fallback_highest) {
return rollback_rejection(transaction, reason).await;
}
let insert_head = format!(
"INSERT INTO {} (persistence_id, highest_seq_nr, deleted_to) \
VALUES ($1, $2, 0) ON CONFLICT (persistence_id) DO NOTHING",
self.sql.journal_head
);
let inserted = sqlx::query(&insert_head)
.bind(prepared.persistence_id.id())
.bind(fallback_highest)
.execute(&mut *transaction)
.await
.map_err(|error| storage_error("create journal head", error))?;
if inserted.rows_affected() == 1 {
fallback_highest
} else {
let row = sqlx::query(lock_head)
.bind(prepared.persistence_id.id())
.fetch_one(&mut *transaction)
.await
.map_err(|error| storage_error("lock raced journal head", error))?;
let raced_highest: i64 = row
.try_get("highest_seq_nr")
.map_err(|error| storage_error("decode raced journal head", error))?;
if let Err(reason) = validate_first_sequence(&prepared, raced_highest) {
return rollback_rejection(transaction, reason).await;
}
raced_highest
}
};
debug_assert_eq!(
highest.checked_add(1),
Some(prepared.first_sequence_nr),
"journal head was validated before insertion"
);
let insert = self.sql.journal_insert_sql(prepared.events.len());
let mut query = sqlx::query(&insert);
for event in &prepared.events {
query = query
.bind(event.persistence_id.id())
.bind(event.sequence_nr)
.bind(event.slice)
.bind(event.entity_type.as_str())
.bind(event.writer_uuid.as_str())
.bind(event.adapter_manifest.as_str())
.bind(event.serializer_id)
.bind(event.serializer_manifest.as_str())
.bind(event.payload.as_slice())
.bind(event.metadata_serializer_id)
.bind(event.metadata_manifest.as_deref())
.bind(event.metadata_payload.as_deref())
.bind(&event.tags)
.bind(false);
}
query
.execute(&mut *transaction)
.await
.map_err(|error| storage_error("insert atomic journal write", error))?;
sqlx::query(&self.sql.update_head_sql)
.bind(prepared.persistence_id.id())
.bind(prepared.last_sequence_nr)
.execute(&mut *transaction)
.await
.map_err(|error| storage_error("update journal head", error))?;
transaction
.commit()
.await
.map_err(|error| storage_error("commit atomic journal write", error))?;
Ok(AppendOutcome::Accepted)
}
async fn group_commit_handle(&self) -> PersistenceResult<&GroupCommitHandle> {
let pool = self.ready_pool().await?.clone();
self.group_commit
.get_or_try_init(|| async {
let (sender, receiver) =
mpsc::channel(self.config.group_commit.queue_capacity.max(1));
let flusher = GroupCommitFlusher {
pool,
sql: self.sql.clone(),
config: self.config.group_commit.clone(),
min_group: self.group_commit_min_group.clone(),
};
tokio::spawn(flusher.run(receiver));
Ok::<_, PersistenceError>(GroupCommitHandle { sender })
})
.await
}
async fn enqueue_grouped(
&self,
prepared: PreparedAtomicWrite,
) -> PersistenceResult<oneshot::Receiver<PersistenceResult<AppendOutcome>>> {
let handle = self.group_commit_handle().await?;
let (reply, receiver) = oneshot::channel();
handle
.sender
.send(GroupCommitRequest { prepared, reply })
.await
.map_err(|_| {
PersistenceError::Connection(
"PostgreSQL group-commit coordinator is unavailable".into(),
)
})?;
Ok(receiver)
}
async fn append_write_grouped(&self, write: AtomicWrite) -> PersistenceResult<AppendOutcome> {
let prepared = match prepare_atomic_write(write) {
Ok(prepared) => prepared,
Err(reason) => return Ok(AppendOutcome::Rejected { reason }),
};
let receiver = self.enqueue_grouped(prepared).await?;
receiver.await.map_err(|_| {
PersistenceError::Failure(
"PostgreSQL group-commit reply channel closed before a result".into(),
)
})?
}
async fn append_batch_grouped(
&self,
writes: Vec<AtomicWrite>,
) -> PersistenceResult<Vec<AppendOutcome>> {
let mut pending = Vec::with_capacity(writes.len());
for write in writes {
match prepare_atomic_write(write) {
Err(reason) => pending.push(GroupedPending::Rejected(reason)),
Ok(prepared) => {
pending.push(GroupedPending::Awaiting(
self.enqueue_grouped(prepared).await?,
));
}
}
}
let mut outcomes = Vec::with_capacity(pending.len());
for entry in pending {
match entry {
GroupedPending::Rejected(reason) => {
outcomes.push(AppendOutcome::Rejected { reason });
}
GroupedPending::Awaiting(receiver) => {
let outcome = receiver.await.map_err(|_| {
PersistenceError::Failure(
"PostgreSQL group-commit reply channel closed before a result".into(),
)
})??;
outcomes.push(outcome);
}
}
}
Ok(outcomes)
}
async fn revision_conflict(
&self,
persistence_id: &PersistenceId,
actual: Revision,
) -> PersistenceError {
match self.current_revision(persistence_id).await {
Ok(stored) if stored.as_u64() == i64::MAX as u64 => {
PersistenceError::RevisionExhausted {
persistence_id: persistence_id.clone(),
}
}
Ok(stored) => match stored.as_u64().checked_add(1) {
Some(expected) => PersistenceError::RevisionConflict {
persistence_id: persistence_id.clone(),
expected: Revision::new(expected),
actual,
},
None => PersistenceError::RevisionExhausted {
persistence_id: persistence_id.clone(),
},
},
Err(error) => error,
}
}
async fn current_revision(
&self,
persistence_id: &PersistenceId,
) -> PersistenceResult<Revision> {
let pool = self.ready_pool().await?;
let select = format!(
"SELECT revision FROM {} WHERE persistence_id = $1",
self.sql.durable_state
);
let row = sqlx::query(&select)
.bind(persistence_id.id())
.fetch_optional(pool)
.await
.map_err(|error| storage_error("read durable-state revision", error))?;
row.map_or(Ok(Revision::new(0)), |row| {
let revision: i64 = row
.try_get("revision")
.map_err(|error| storage_error("decode durable-state revision", error))?;
Ok(Revision::new(non_negative_u64(
revision,
"durable-state revision",
)?))
})
}
}
#[async_trait::async_trait]
impl Journal for PostgresPersistence {
async fn append(&self, writes: Vec<AtomicWrite>) -> PersistenceResult<Vec<AppendOutcome>> {
if !self.config.group_commit.enabled {
let mut outcomes = Vec::with_capacity(writes.len());
for write in writes {
outcomes.push(self.append_write_solo(write).await?);
}
return Ok(outcomes);
}
let (_inflight, demand_before) = self.enter_inflight_append();
if self.should_bypass_group_commit(demand_before) {
let mut outcomes = Vec::with_capacity(writes.len());
for write in writes {
outcomes.push(self.append_write_solo(write).await?);
}
Ok(outcomes)
} else {
self.append_batch_grouped(writes).await
}
}
async fn append_one(&self, write: AtomicWrite) -> PersistenceResult<AppendOutcome> {
if !self.config.group_commit.enabled {
return self.append_write_solo(write).await;
}
let (_inflight, demand_before) = self.enter_inflight_append();
if self.should_bypass_group_commit(demand_before) {
self.append_write_solo(write).await
} else {
self.append_write_grouped(write).await
}
}
async fn highest_sequence_nr(
&self,
persistence_id: &PersistenceId,
_from_hint: SequenceNr,
) -> PersistenceResult<SequenceNr> {
let pool = self.ready_pool().await?;
let select = format!(
"SELECT highest_seq_nr FROM {} WHERE persistence_id = $1",
self.sql.journal_head
);
if let Some(row) = sqlx::query(&select)
.bind(persistence_id.id())
.fetch_optional(pool)
.await
.map_err(|error| storage_error("read journal head", error))?
{
let value: i64 = row
.try_get("highest_seq_nr")
.map_err(|error| storage_error("decode journal head", error))?;
return Ok(SequenceNr::new(non_negative_u64(value, "journal head")?));
}
let fallback = format!(
"SELECT COALESCE(MAX(seq_nr), 0) AS highest_seq_nr FROM {} WHERE persistence_id = $1",
self.sql.event_journal
);
let row = sqlx::query(&fallback)
.bind(persistence_id.id())
.fetch_one(pool)
.await
.map_err(|error| storage_error("read journal watermark fallback", error))?;
let value: i64 = row
.try_get("highest_seq_nr")
.map_err(|error| storage_error("decode journal watermark fallback", error))?;
Ok(SequenceNr::new(non_negative_u64(
value,
"journal watermark fallback",
)?))
}
async fn replay(&self, range: ReplayRange) -> PersistenceResult<EventStream> {
if range.from > range.to || range.max == 0 || range.from.as_u64() > i64::MAX as u64 {
return Ok(Box::pin(stream::empty()));
}
let pool = self.ready_pool().await?.clone();
let state = ReplayState {
pool,
table: self.sql.event_journal.clone(),
persistence_id: range.persistence_id,
next_sequence_nr: i64::try_from(range.from.as_u64())
.expect("range was checked against i64::MAX"),
to_sequence_nr: i64::try_from(range.to.as_u64()).unwrap_or(i64::MAX),
remaining: range.max,
page_size: self.config.replay_page_size,
buffered: VecDeque::new(),
finished: false,
};
Ok(Box::pin(stream::try_unfold(state, replay_next)))
}
async fn delete_to(
&self,
persistence_id: &PersistenceId,
inclusive: SequenceNr,
) -> PersistenceResult<()> {
let pool = self.ready_pool().await?;
let mut transaction = pool
.begin()
.await
.map_err(|error| storage_error("begin journal delete transaction", error))?;
let ensure_head = format!(
"INSERT INTO {} (persistence_id, highest_seq_nr, deleted_to) \
SELECT $1, COALESCE(MAX(seq_nr), 0), 0 FROM {} WHERE persistence_id = $1 \
ON CONFLICT (persistence_id) DO NOTHING",
self.sql.journal_head, self.sql.event_journal
);
sqlx::query(&ensure_head)
.bind(persistence_id.id())
.execute(&mut *transaction)
.await
.map_err(|error| storage_error("ensure journal head for delete", error))?;
sqlx::query(&self.sql.lock_head_sql)
.bind(persistence_id.id())
.fetch_one(&mut *transaction)
.await
.map_err(|error| storage_error("lock journal head for delete", error))?;
let bound = i64::try_from(inclusive.as_u64()).unwrap_or(i64::MAX);
let delete = match self.config.delete_policy {
PostgresDeletePolicy::Soft => format!(
"UPDATE {} SET deleted = TRUE \
WHERE persistence_id = $1 AND seq_nr <= $2 AND NOT deleted",
self.sql.event_journal
),
PostgresDeletePolicy::Hard => format!(
"DELETE FROM {} WHERE persistence_id = $1 AND seq_nr <= $2",
self.sql.event_journal
),
};
sqlx::query(&delete)
.bind(persistence_id.id())
.bind(bound)
.execute(&mut *transaction)
.await
.map_err(|error| storage_error("delete journal events", error))?;
let update_head = format!(
"UPDATE {} SET deleted_to = GREATEST(deleted_to, $2) WHERE persistence_id = $1",
self.sql.journal_head
);
sqlx::query(&update_head)
.bind(persistence_id.id())
.bind(bound)
.execute(&mut *transaction)
.await
.map_err(|error| storage_error("record journal deletion watermark", error))?;
transaction
.commit()
.await
.map_err(|error| storage_error("commit journal delete", error))
}
}
#[async_trait::async_trait]
impl SnapshotStore for PostgresPersistence {
async fn load(
&self,
persistence_id: &PersistenceId,
criteria: &SnapshotCriteria,
) -> PersistenceResult<Option<SelectedSnapshot>> {
if criteria.min_sequence_nr > criteria.max_sequence_nr
|| criteria.min_timestamp_ms > criteria.max_timestamp_ms
|| criteria.min_sequence_nr.as_u64() > i64::MAX as u64
{
return Ok(None);
}
let pool = self.ready_pool().await?;
let select = format!(
"SELECT seq_nr, timestamp_ms, adapter_manifest, ser_id, ser_manifest, payload \
FROM {} WHERE persistence_id = $1 \
AND seq_nr >= $2 AND seq_nr <= $3 \
AND timestamp_ms >= $4 AND timestamp_ms <= $5 \
ORDER BY seq_nr DESC, timestamp_ms DESC LIMIT 1",
self.sql.snapshot
);
let row = sqlx::query(&select)
.bind(persistence_id.id())
.bind(i64::try_from(criteria.min_sequence_nr.as_u64()).expect("bound was checked"))
.bind(i64::try_from(criteria.max_sequence_nr.as_u64()).unwrap_or(i64::MAX))
.bind(criteria.min_timestamp_ms)
.bind(criteria.max_timestamp_ms)
.fetch_optional(pool)
.await
.map_err(|error| storage_error("load snapshot", error))?;
row.map(|row| decode_snapshot_row(persistence_id, &row))
.transpose()
}
async fn save(
&self,
metadata: SnapshotMetadata,
adapter_manifest: String,
state: SerializedPayload,
) -> PersistenceResult<()> {
let sequence_nr = sql_i64(metadata.sequence_nr.as_u64(), "snapshot sequence number")?;
let pool = self.ready_pool().await?;
let upsert = format!(
"INSERT INTO {} \
(persistence_id, seq_nr, timestamp_ms, adapter_manifest, ser_id, ser_manifest, payload) \
VALUES ($1, $2, $3, $4, $5, $6, $7) \
ON CONFLICT (persistence_id, seq_nr) DO UPDATE SET \
timestamp_ms = EXCLUDED.timestamp_ms, \
adapter_manifest = EXCLUDED.adapter_manifest, \
ser_id = EXCLUDED.ser_id, ser_manifest = EXCLUDED.ser_manifest, \
payload = EXCLUDED.payload",
self.sql.snapshot
);
sqlx::query(&upsert)
.bind(metadata.persistence_id.id())
.bind(sequence_nr)
.bind(metadata.timestamp_ms)
.bind(adapter_manifest)
.bind(i64::from(state.serializer_id.as_u32()))
.bind(state.manifest)
.bind(state.payload)
.execute(pool)
.await
.map_err(|error| storage_error("save snapshot", error))?;
Ok(())
}
async fn delete(&self, metadata: SnapshotMetadata) -> PersistenceResult<()> {
if metadata.sequence_nr.as_u64() > i64::MAX as u64 {
return Ok(());
}
let pool = self.ready_pool().await?;
let delete = format!(
"DELETE FROM {} WHERE persistence_id = $1 AND seq_nr = $2 AND timestamp_ms = $3",
self.sql.snapshot
);
sqlx::query(&delete)
.bind(metadata.persistence_id.id())
.bind(i64::try_from(metadata.sequence_nr.as_u64()).expect("bound was checked"))
.bind(metadata.timestamp_ms)
.execute(pool)
.await
.map_err(|error| storage_error("delete snapshot", error))?;
Ok(())
}
async fn delete_matching(
&self,
persistence_id: &PersistenceId,
criteria: &SnapshotCriteria,
) -> PersistenceResult<()> {
if criteria.min_sequence_nr > criteria.max_sequence_nr
|| criteria.min_timestamp_ms > criteria.max_timestamp_ms
|| criteria.min_sequence_nr.as_u64() > i64::MAX as u64
{
return Ok(());
}
let pool = self.ready_pool().await?;
let delete = format!(
"DELETE FROM {} WHERE persistence_id = $1 \
AND seq_nr >= $2 AND seq_nr <= $3 \
AND timestamp_ms >= $4 AND timestamp_ms <= $5",
self.sql.snapshot
);
sqlx::query(&delete)
.bind(persistence_id.id())
.bind(i64::try_from(criteria.min_sequence_nr.as_u64()).expect("bound was checked"))
.bind(i64::try_from(criteria.max_sequence_nr.as_u64()).unwrap_or(i64::MAX))
.bind(criteria.min_timestamp_ms)
.bind(criteria.max_timestamp_ms)
.execute(pool)
.await
.map_err(|error| storage_error("delete matching snapshots", error))?;
Ok(())
}
}
#[async_trait::async_trait]
impl DurableStateStore for PostgresPersistence {
async fn get(&self, persistence_id: &PersistenceId) -> PersistenceResult<VersionedState> {
let pool = self.ready_pool().await?;
let select = format!(
"SELECT revision, tag, ser_id, ser_manifest, payload, deleted \
FROM {} WHERE persistence_id = $1",
self.sql.durable_state
);
let row = sqlx::query(&select)
.bind(persistence_id.id())
.fetch_optional(pool)
.await
.map_err(|error| storage_error("get durable state", error))?;
row.map_or(Ok(VersionedState::default()), |row| {
decode_versioned_state(&row)
})
}
async fn upsert(
&self,
persistence_id: &PersistenceId,
new_revision: Revision,
state: SerializedPayload,
tag: Option<Tag>,
) -> PersistenceResult<()> {
let Ok(revision) = i64::try_from(new_revision.as_u64()) else {
return Err(self.revision_conflict(persistence_id, new_revision).await);
};
let pool = self.ready_pool().await?;
let upsert = format!(
"INSERT INTO {} \
(persistence_id, revision, tag, ser_id, ser_manifest, payload, deleted, db_timestamp) \
SELECT $1, $2, $3, $4, $5, $6, FALSE, now() \
WHERE ($2 = 1 AND NOT EXISTS \
(SELECT 1 FROM {} WHERE persistence_id = $1)) \
OR EXISTS (SELECT 1 FROM {} \
WHERE persistence_id = $1 AND revision = $2 - 1) \
ON CONFLICT (persistence_id) DO UPDATE SET \
revision = EXCLUDED.revision, tag = EXCLUDED.tag, \
ser_id = EXCLUDED.ser_id, ser_manifest = EXCLUDED.ser_manifest, \
payload = EXCLUDED.payload, deleted = FALSE, db_timestamp = now() \
WHERE {}.revision = EXCLUDED.revision - 1",
self.sql.durable_state,
self.sql.durable_state,
self.sql.durable_state,
self.sql.durable_state
);
let result = sqlx::query(&upsert)
.bind(persistence_id.id())
.bind(revision)
.bind(tag.as_ref().map(Tag::as_str))
.bind(i64::from(state.serializer_id.as_u32()))
.bind(state.manifest)
.bind(state.payload)
.execute(pool)
.await
.map_err(|error| storage_error("upsert durable state", error))?;
if result.rows_affected() == 1 {
Ok(())
} else {
Err(self.revision_conflict(persistence_id, new_revision).await)
}
}
async fn delete(
&self,
persistence_id: &PersistenceId,
new_revision: Revision,
) -> PersistenceResult<()> {
let Ok(revision) = i64::try_from(new_revision.as_u64()) else {
return Err(self.revision_conflict(persistence_id, new_revision).await);
};
let pool = self.ready_pool().await?;
let delete = format!(
"INSERT INTO {} \
(persistence_id, revision, tag, ser_id, ser_manifest, payload, deleted, db_timestamp) \
SELECT $1, $2, NULL, NULL, NULL, NULL, TRUE, now() \
WHERE ($2 = 1 AND NOT EXISTS \
(SELECT 1 FROM {} WHERE persistence_id = $1)) \
OR EXISTS (SELECT 1 FROM {} \
WHERE persistence_id = $1 AND revision = $2 - 1) \
ON CONFLICT (persistence_id) DO UPDATE SET \
revision = EXCLUDED.revision, tag = {}.tag, ser_id = NULL, \
ser_manifest = NULL, payload = NULL, deleted = TRUE, db_timestamp = now() \
WHERE {}.revision = EXCLUDED.revision - 1",
self.sql.durable_state,
self.sql.durable_state,
self.sql.durable_state,
self.sql.durable_state,
self.sql.durable_state
);
let result = sqlx::query(&delete)
.bind(persistence_id.id())
.bind(revision)
.execute(pool)
.await
.map_err(|error| storage_error("delete durable state", error))?;
if result.rows_affected() == 1 {
Ok(())
} else {
Err(self.revision_conflict(persistence_id, new_revision).await)
}
}
}
#[async_trait::async_trait]
impl EventsByPersistenceIdQuery for PostgresPersistence {
async fn events_by_persistence_id(
&self,
persistence_id: &PersistenceId,
from_sequence_nr: SequenceNr,
to_sequence_nr: SequenceNr,
mode: QueryMode,
) -> PersistenceResult<QueryStream<EventEnvelope>> {
if from_sequence_nr > to_sequence_nr || from_sequence_nr.as_u64() > i64::MAX as u64 {
return Ok(Box::pin(stream::empty()));
}
let pool = self.ready_pool().await?.clone();
let highest_sequence_nr =
postgres_highest_sequence_nr(&pool, &self.sql.journal_head, persistence_id).await?;
let boundary = to_sequence_nr.min(highest_sequence_nr);
let events = if from_sequence_nr <= boundary {
postgres_events_by_persistence_id(
&pool,
&self.sql.event_journal,
persistence_id,
from_sequence_nr,
boundary,
None,
)
.await?
} else {
Vec::new()
};
if mode == QueryMode::Current {
return Ok(Box::pin(stream::iter(events.into_iter().map(Ok))));
}
let cursor = PostgresPersistenceIdCursor {
pool,
event_journal: self.sql.event_journal.clone(),
journal_head: self.sql.journal_head.clone(),
persistence_id: persistence_id.clone(),
next_sequence_nr: highest_sequence_nr
.as_u64()
.checked_add(1)
.map(SequenceNr::new)
.map(|next_sequence_nr| next_sequence_nr.max(from_sequence_nr)),
to_sequence_nr,
buffered: VecDeque::from(events),
reached_end: highest_sequence_nr >= to_sequence_nr,
polling: self.config.polling.clone(),
delay: self.config.polling.min_interval,
};
Ok(Box::pin(stream::unfold(
cursor,
next_postgres_persistence_id_event,
)))
}
}
#[async_trait::async_trait]
impl EventsByTagQuery for PostgresPersistence {
async fn events_by_tag(
&self,
tag: &Tag,
offset: Offset,
mode: QueryMode,
) -> PersistenceResult<QueryStream<EventEnvelope>> {
let resume = postgres_resume(offset)?;
let pool = self.ready_pool().await?.clone();
let upper_bound = if mode == QueryMode::Current {
postgres_current_timestamp_upper_bound(&pool).await?
} else {
postgres_live_timestamp_upper_bound(&self.config.polling)?
};
let events = postgres_events_by_tag(
&pool,
&self.sql.event_journal,
tag,
&resume,
upper_bound,
None,
)
.await?;
if mode == QueryMode::Current {
return Ok(Box::pin(stream::iter(events.into_iter().map(Ok))));
}
let resume = events
.last()
.map(postgres_event_position)
.map_or(resume, PostgresResume::After);
let cursor = PostgresTagCursor {
pool,
event_journal: self.sql.event_journal.clone(),
tag: tag.clone(),
resume,
upper_bound,
buffered: VecDeque::from(events),
polling: self.config.polling.clone(),
delay: self.config.polling.min_interval,
};
Ok(Box::pin(stream::unfold(cursor, next_postgres_tag_event)))
}
}
#[async_trait::async_trait]
impl EventsBySlicesQuery for PostgresPersistence {
async fn events_by_slices(
&self,
entity_type: &str,
min_slice: u16,
max_slice: u16,
offset: Offset,
mode: QueryMode,
) -> PersistenceResult<QueryStream<EventEnvelope>> {
let range = SliceRange::new(min_slice, max_slice)?;
if entity_type.trim().is_empty() {
return Err(PersistenceError::Rejected(
"PostgreSQL events-by-slices entity_type must not be blank".into(),
));
}
let resume = postgres_resume(offset)?;
let pool = self.ready_pool().await?.clone();
let upper_bound = if mode == QueryMode::Current {
postgres_current_timestamp_upper_bound(&pool).await?
} else {
postgres_live_timestamp_upper_bound(&self.config.polling)?
};
let events = postgres_events_by_slices(
&pool,
&self.sql.event_journal,
entity_type,
range,
&resume,
upper_bound,
None,
)
.await?;
if mode == QueryMode::Current {
return Ok(Box::pin(stream::iter(events.into_iter().map(Ok))));
}
let resume = events
.last()
.map(postgres_event_position)
.map_or(resume, PostgresResume::After);
let cursor = PostgresSliceCursor {
pool,
event_journal: self.sql.event_journal.clone(),
entity_type: entity_type.to_owned(),
range,
resume,
upper_bound,
buffered: VecDeque::from(events),
polling: self.config.polling.clone(),
delay: self.config.polling.min_interval,
};
Ok(Box::pin(stream::unfold(cursor, next_postgres_slice_event)))
}
}
#[async_trait::async_trait]
impl PersistenceIdsQuery for PostgresPersistence {
async fn persistence_ids(
&self,
mode: QueryMode,
) -> PersistenceResult<QueryStream<PersistenceId>> {
let pool = self.ready_pool().await?.clone();
let ids = postgres_persistence_ids(&pool, &self.sql.journal_head).await?;
if mode == QueryMode::Current {
return Ok(Box::pin(stream::iter(ids.into_iter().map(Ok))));
}
let cursor = PostgresPersistenceIdsCursor {
pool,
journal_head: self.sql.journal_head.clone(),
known: ids.iter().cloned().collect(),
buffered: VecDeque::from(ids),
polling: self.config.polling.clone(),
delay: self.config.polling.min_interval,
};
Ok(Box::pin(stream::unfold(
cursor,
next_postgres_persistence_id,
)))
}
}
#[async_trait::async_trait]
impl DurableStateChangesQuery for PostgresPersistence {
async fn changes(
&self,
tag: &Tag,
offset: Offset,
mode: QueryMode,
) -> PersistenceResult<QueryStream<DurableStateChange>> {
let resume = postgres_resume(offset)?;
let pool = self.ready_pool().await?.clone();
let upper_bound = if mode == QueryMode::Current {
postgres_current_timestamp_upper_bound(&pool).await?
} else {
postgres_live_timestamp_upper_bound(&self.config.polling)?
};
let changes = postgres_durable_state_changes(
&pool,
&self.sql.durable_state,
tag,
&resume,
upper_bound,
None,
)
.await?;
if mode == QueryMode::Current {
return Ok(Box::pin(stream::iter(changes.into_iter().map(Ok))));
}
let resume = changes
.last()
.map(postgres_durable_position)
.map_or(resume, PostgresResume::After);
let cursor = PostgresDurableCursor {
pool,
durable_state: self.sql.durable_state.clone(),
tag: tag.clone(),
resume,
upper_bound,
buffered: VecDeque::from(changes),
polling: self.config.polling.clone(),
delay: self.config.polling.min_interval,
};
Ok(Box::pin(stream::unfold(
cursor,
next_postgres_durable_change,
)))
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
struct PostgresPosition {
epoch_micros: i64,
sequence: i64,
persistence_id: String,
}
#[derive(Debug, Clone, PartialEq, Eq)]
enum PostgresResume {
None,
Inclusive { epoch_micros: i64, sequence: i64 },
After(PostgresPosition),
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum PostgresTimestampUpperBound {
Current { epoch_micros: i64 },
Live { visibility_lag_micros: i64 },
}
impl PostgresTimestampUpperBound {
const fn value(self) -> i64 {
match self {
Self::Current { epoch_micros } => epoch_micros,
Self::Live {
visibility_lag_micros,
} => visibility_lag_micros,
}
}
fn sql_predicate(self, bind_index: usize) -> String {
match self {
Self::Current { .. } => format!(
"db_timestamp <= TIMESTAMPTZ 'epoch' + ${bind_index}::BIGINT * INTERVAL '1 microsecond'"
),
Self::Live { .. } => {
format!("db_timestamp <= now() - ${bind_index}::BIGINT * INTERVAL '1 microsecond'")
}
}
}
}
fn postgres_resume(offset: Offset) -> PersistenceResult<PostgresResume> {
match offset {
Offset::NoOffset => Ok(PostgresResume::None),
Offset::Timestamp {
epoch_micros,
seq_nr,
} => Ok(PostgresResume::Inclusive {
epoch_micros,
sequence: sql_i64(seq_nr, "PostgreSQL timestamp-offset sequence number")?,
}),
Offset::Sequence(_) => Err(PersistenceError::Rejected(
"PostgreSQL queries require a Timestamp offset produced by the same database"
.to_owned(),
)),
}
}
async fn postgres_current_timestamp_upper_bound(
pool: &PgPool,
) -> PersistenceResult<PostgresTimestampUpperBound> {
let row = sqlx::query(
"SELECT (EXTRACT(EPOCH FROM clock_timestamp()) * 1000000)::BIGINT AS epoch_micros",
)
.fetch_one(pool)
.await
.map_err(|error| storage_error("capture current query timestamp boundary", error))?;
let epoch_micros = row
.try_get("epoch_micros")
.map_err(|error| storage_error("decode current query timestamp boundary", error))?;
Ok(PostgresTimestampUpperBound::Current { epoch_micros })
}
fn postgres_live_timestamp_upper_bound(
polling: &PostgresPollingConfig,
) -> PersistenceResult<PostgresTimestampUpperBound> {
Ok(PostgresTimestampUpperBound::Live {
visibility_lag_micros: duration_micros_i64(
polling.visibility_lag,
"PostgreSQL polling visibility_lag",
)?,
})
}
async fn postgres_highest_sequence_nr(
pool: &PgPool,
journal_head: &str,
persistence_id: &PersistenceId,
) -> PersistenceResult<SequenceNr> {
let select = format!("SELECT highest_seq_nr FROM {journal_head} WHERE persistence_id = $1");
let row = sqlx::query(&select)
.bind(persistence_id.id())
.fetch_optional(pool)
.await
.map_err(|error| storage_error("read journal head for query", error))?;
row.map_or(Ok(SequenceNr::new(0)), |row| {
let highest: i64 = row
.try_get("highest_seq_nr")
.map_err(|error| storage_error("decode query journal head", error))?;
Ok(SequenceNr::new(non_negative_u64(
highest,
"query journal head",
)?))
})
}
async fn postgres_events_by_persistence_id(
pool: &PgPool,
event_journal: &str,
persistence_id: &PersistenceId,
from_sequence_nr: SequenceNr,
to_sequence_nr: SequenceNr,
limit: Option<u32>,
) -> PersistenceResult<Vec<EventEnvelope>> {
if from_sequence_nr > to_sequence_nr || from_sequence_nr.as_u64() > i64::MAX as u64 {
return Ok(Vec::new());
}
let select = format!(
"SELECT persistence_id, seq_nr, adapter_manifest, writer, \
(EXTRACT(EPOCH FROM db_timestamp) * 1000000)::BIGINT AS offset_epoch_micros, \
(EXTRACT(EPOCH FROM db_timestamp) * 1000)::BIGINT AS timestamp_ms, \
ser_id, ser_manifest, payload, meta_ser_id, meta_manifest, meta_payload, tags \
FROM {event_journal} WHERE persistence_id = $1 AND seq_nr >= $2 AND seq_nr <= $3 \
AND NOT deleted ORDER BY seq_nr ASC LIMIT $4"
);
let rows = sqlx::query(&select)
.bind(persistence_id.id())
.bind(i64::try_from(from_sequence_nr.as_u64()).expect("bound was checked"))
.bind(i64::try_from(to_sequence_nr.as_u64()).unwrap_or(i64::MAX))
.bind(limit.map_or(i64::MAX, i64::from))
.fetch_all(pool)
.await
.map_err(|error| storage_error("fetch events-by-persistence-id query", error))?;
rows.iter().map(decode_postgres_event_envelope).collect()
}
async fn postgres_events_by_tag(
pool: &PgPool,
event_journal: &str,
tag: &Tag,
resume: &PostgresResume,
upper_bound: PostgresTimestampUpperBound,
limit: Option<u32>,
) -> PersistenceResult<Vec<EventEnvelope>> {
let columns = "persistence_id, seq_nr, adapter_manifest, writer, \
(EXTRACT(EPOCH FROM db_timestamp) * 1000000)::BIGINT AS offset_epoch_micros, \
(EXTRACT(EPOCH FROM db_timestamp) * 1000)::BIGINT AS timestamp_ms, \
ser_id, ser_manifest, payload, meta_ser_id, meta_manifest, meta_payload, tags";
let rows = match resume {
PostgresResume::None => {
let upper_predicate = upper_bound.sql_predicate(2);
let select = format!(
"SELECT {columns} FROM {event_journal} \
WHERE tags @> ARRAY[$1]::TEXT[] AND NOT deleted AND {upper_predicate} \
ORDER BY db_timestamp ASC, seq_nr ASC, persistence_id ASC LIMIT $3"
);
sqlx::query(&select)
.bind(tag.as_str())
.bind(upper_bound.value())
.bind(limit.map_or(i64::MAX, i64::from))
.fetch_all(pool)
.await
}
PostgresResume::Inclusive {
epoch_micros,
sequence,
} => {
let upper_predicate = upper_bound.sql_predicate(4);
let select = format!(
"SELECT {columns} FROM {event_journal} \
WHERE tags @> ARRAY[$1]::TEXT[] AND NOT deleted \
AND (db_timestamp, seq_nr) >= \
(TIMESTAMPTZ 'epoch' + $2 * INTERVAL '1 microsecond', $3) \
AND {upper_predicate} \
ORDER BY db_timestamp ASC, seq_nr ASC, persistence_id ASC LIMIT $5"
);
sqlx::query(&select)
.bind(tag.as_str())
.bind(*epoch_micros)
.bind(*sequence)
.bind(upper_bound.value())
.bind(limit.map_or(i64::MAX, i64::from))
.fetch_all(pool)
.await
}
PostgresResume::After(position) => {
let upper_predicate = upper_bound.sql_predicate(5);
let select = format!(
"SELECT {columns} FROM {event_journal} \
WHERE tags @> ARRAY[$1]::TEXT[] AND NOT deleted \
AND (db_timestamp, seq_nr, persistence_id) > \
(TIMESTAMPTZ 'epoch' + $2 * INTERVAL '1 microsecond', $3, $4) \
AND {upper_predicate} \
ORDER BY db_timestamp ASC, seq_nr ASC, persistence_id ASC LIMIT $6"
);
sqlx::query(&select)
.bind(tag.as_str())
.bind(position.epoch_micros)
.bind(position.sequence)
.bind(&position.persistence_id)
.bind(upper_bound.value())
.bind(limit.map_or(i64::MAX, i64::from))
.fetch_all(pool)
.await
}
}
.map_err(|error| storage_error("fetch events-by-tag query", error))?;
rows.iter().map(decode_postgres_event_envelope).collect()
}
async fn postgres_events_by_slices(
pool: &PgPool,
event_journal: &str,
entity_type: &str,
range: SliceRange,
resume: &PostgresResume,
upper_bound: PostgresTimestampUpperBound,
limit: Option<u32>,
) -> PersistenceResult<Vec<EventEnvelope>> {
let columns = "persistence_id, seq_nr, adapter_manifest, writer, \
(EXTRACT(EPOCH FROM db_timestamp) * 1000000)::BIGINT AS offset_epoch_micros, \
(EXTRACT(EPOCH FROM db_timestamp) * 1000)::BIGINT AS timestamp_ms, \
ser_id, ser_manifest, payload, meta_ser_id, meta_manifest, meta_payload, tags";
let rows = match resume {
PostgresResume::None => {
let upper_predicate = upper_bound.sql_predicate(4);
let select = format!(
"SELECT {columns} FROM {event_journal} \
WHERE entity_type = $1 AND slice >= $2 AND slice <= $3 \
AND NOT deleted AND {upper_predicate} \
ORDER BY db_timestamp ASC, seq_nr ASC, persistence_id ASC LIMIT $5"
);
sqlx::query(&select)
.bind(entity_type)
.bind(i32::from(range.min()))
.bind(i32::from(range.max()))
.bind(upper_bound.value())
.bind(limit.map_or(i64::MAX, i64::from))
.fetch_all(pool)
.await
}
PostgresResume::Inclusive {
epoch_micros,
sequence,
} => {
let upper_predicate = upper_bound.sql_predicate(6);
let select = format!(
"SELECT {columns} FROM {event_journal} \
WHERE entity_type = $1 AND slice >= $2 AND slice <= $3 AND NOT deleted \
AND (db_timestamp, seq_nr) >= \
(TIMESTAMPTZ 'epoch' + $4 * INTERVAL '1 microsecond', $5) \
AND {upper_predicate} \
ORDER BY db_timestamp ASC, seq_nr ASC, persistence_id ASC LIMIT $7"
);
sqlx::query(&select)
.bind(entity_type)
.bind(i32::from(range.min()))
.bind(i32::from(range.max()))
.bind(*epoch_micros)
.bind(*sequence)
.bind(upper_bound.value())
.bind(limit.map_or(i64::MAX, i64::from))
.fetch_all(pool)
.await
}
PostgresResume::After(position) => {
let upper_predicate = upper_bound.sql_predicate(7);
let select = format!(
"SELECT {columns} FROM {event_journal} \
WHERE entity_type = $1 AND slice >= $2 AND slice <= $3 AND NOT deleted \
AND (db_timestamp, seq_nr, persistence_id) > \
(TIMESTAMPTZ 'epoch' + $4 * INTERVAL '1 microsecond', $5, $6) \
AND {upper_predicate} \
ORDER BY db_timestamp ASC, seq_nr ASC, persistence_id ASC LIMIT $8"
);
sqlx::query(&select)
.bind(entity_type)
.bind(i32::from(range.min()))
.bind(i32::from(range.max()))
.bind(position.epoch_micros)
.bind(position.sequence)
.bind(&position.persistence_id)
.bind(upper_bound.value())
.bind(limit.map_or(i64::MAX, i64::from))
.fetch_all(pool)
.await
}
}
.map_err(|error| storage_error("fetch events-by-slices query", error))?;
rows.iter().map(decode_postgres_event_envelope).collect()
}
async fn postgres_persistence_ids(
pool: &PgPool,
journal_head: &str,
) -> PersistenceResult<Vec<PersistenceId>> {
let select = format!("SELECT persistence_id FROM {journal_head} ORDER BY persistence_id ASC");
let rows = sqlx::query(&select)
.fetch_all(pool)
.await
.map_err(|error| storage_error("fetch persistence-ids query", error))?;
rows.iter()
.map(|row| {
let persistence_id: String = row
.try_get("persistence_id")
.map_err(|error| storage_error("decode query persistence id", error))?;
PersistenceId::from_unique(persistence_id)
})
.collect()
}
async fn postgres_durable_state_changes(
pool: &PgPool,
durable_state: &str,
tag: &Tag,
resume: &PostgresResume,
upper_bound: PostgresTimestampUpperBound,
limit: Option<u32>,
) -> PersistenceResult<Vec<DurableStateChange>> {
let columns = "persistence_id, revision, ser_id, ser_manifest, payload, deleted, \
(EXTRACT(EPOCH FROM db_timestamp) * 1000000)::BIGINT AS offset_epoch_micros, \
(EXTRACT(EPOCH FROM db_timestamp) * 1000)::BIGINT AS timestamp_ms";
let rows = match resume {
PostgresResume::None => {
let upper_predicate = upper_bound.sql_predicate(2);
let select = format!(
"SELECT {columns} FROM {durable_state} WHERE tag = $1 \
AND {upper_predicate} \
ORDER BY db_timestamp ASC, revision ASC, persistence_id ASC LIMIT $3"
);
sqlx::query(&select)
.bind(tag.as_str())
.bind(upper_bound.value())
.bind(limit.map_or(i64::MAX, i64::from))
.fetch_all(pool)
.await
}
PostgresResume::Inclusive {
epoch_micros,
sequence,
} => {
let upper_predicate = upper_bound.sql_predicate(4);
let select = format!(
"SELECT {columns} FROM {durable_state} WHERE tag = $1 \
AND (db_timestamp, revision) >= \
(TIMESTAMPTZ 'epoch' + $2 * INTERVAL '1 microsecond', $3) \
AND {upper_predicate} \
ORDER BY db_timestamp ASC, revision ASC, persistence_id ASC LIMIT $5"
);
sqlx::query(&select)
.bind(tag.as_str())
.bind(*epoch_micros)
.bind(*sequence)
.bind(upper_bound.value())
.bind(limit.map_or(i64::MAX, i64::from))
.fetch_all(pool)
.await
}
PostgresResume::After(position) => {
let upper_predicate = upper_bound.sql_predicate(5);
let select = format!(
"SELECT {columns} FROM {durable_state} WHERE tag = $1 \
AND (db_timestamp, revision, persistence_id) > \
(TIMESTAMPTZ 'epoch' + $2 * INTERVAL '1 microsecond', $3, $4) \
AND {upper_predicate} \
ORDER BY db_timestamp ASC, revision ASC, persistence_id ASC LIMIT $6"
);
sqlx::query(&select)
.bind(tag.as_str())
.bind(position.epoch_micros)
.bind(position.sequence)
.bind(&position.persistence_id)
.bind(upper_bound.value())
.bind(limit.map_or(i64::MAX, i64::from))
.fetch_all(pool)
.await
}
}
.map_err(|error| storage_error("fetch durable-state changes query", error))?;
rows.iter().map(decode_postgres_durable_change).collect()
}
fn decode_postgres_event_envelope(row: &sqlx::postgres::PgRow) -> PersistenceResult<EventEnvelope> {
let event = decode_event_row(row)?;
let epoch_micros: i64 = row
.try_get("offset_epoch_micros")
.map_err(|error| storage_error("decode event query offset timestamp", error))?;
Ok(EventEnvelope {
offset: Offset::Timestamp {
epoch_micros,
seq_nr: event.sequence_nr.as_u64(),
},
persistence_id: event.persistence_id,
sequence_nr: event.sequence_nr,
timestamp_ms: event.timestamp_ms,
adapter_manifest: event.adapter_manifest,
payload: event.payload,
metadata: event.metadata,
tags: event.tags,
})
}
fn decode_postgres_durable_change(
row: &sqlx::postgres::PgRow,
) -> PersistenceResult<DurableStateChange> {
let persistence_id: String = row
.try_get("persistence_id")
.map_err(|error| storage_error("decode durable change persistence id", error))?;
let persistence_id = PersistenceId::from_unique(persistence_id)?;
let revision: i64 = row
.try_get("revision")
.map_err(|error| storage_error("decode durable change revision", error))?;
let revision = Revision::new(non_negative_u64(revision, "durable change revision")?);
let epoch_micros: i64 = row
.try_get("offset_epoch_micros")
.map_err(|error| storage_error("decode durable change offset timestamp", error))?;
let timestamp_ms: i64 = row
.try_get("timestamp_ms")
.map_err(|error| storage_error("decode durable change timestamp", error))?;
let offset = Offset::Timestamp {
epoch_micros,
seq_nr: revision.as_u64(),
};
let deleted: bool = row
.try_get("deleted")
.map_err(|error| storage_error("decode durable change tombstone", error))?;
if deleted {
return Ok(DurableStateChange::Deleted(DeletedDurableState {
offset,
persistence_id,
revision,
timestamp_ms,
}));
}
let serializer_id: Option<i64> = row
.try_get("ser_id")
.map_err(|error| storage_error("decode durable change serializer id", error))?;
let serializer_manifest: Option<String> = row
.try_get("ser_manifest")
.map_err(|error| storage_error("decode durable change serializer manifest", error))?;
let payload: Option<Vec<u8>> = row
.try_get("payload")
.map_err(|error| storage_error("decode durable change payload", error))?;
let state = decode_optional_frame(
serializer_id,
serializer_manifest,
payload,
"durable change",
)?
.ok_or_else(|| {
PersistenceError::Failure(
"PostgreSQL durable change is live but has no serialization frame".to_owned(),
)
})?;
Ok(DurableStateChange::Updated(UpdatedDurableState {
offset,
persistence_id,
revision,
state,
timestamp_ms,
}))
}
fn postgres_event_position(envelope: &EventEnvelope) -> PostgresPosition {
let Offset::Timestamp {
epoch_micros,
seq_nr,
} = envelope.offset
else {
unreachable!("PostgreSQL event envelopes always carry timestamp offsets")
};
PostgresPosition {
epoch_micros,
sequence: i64::try_from(seq_nr).expect("PostgreSQL sequence numbers fit i64"),
persistence_id: envelope.persistence_id.id().to_owned(),
}
}
fn postgres_durable_position(change: &DurableStateChange) -> PostgresPosition {
let Offset::Timestamp {
epoch_micros,
seq_nr,
} = change.offset()
else {
unreachable!("PostgreSQL durable changes always carry timestamp offsets")
};
PostgresPosition {
epoch_micros,
sequence: i64::try_from(seq_nr).expect("PostgreSQL revisions fit i64"),
persistence_id: change.persistence_id().id().to_owned(),
}
}
struct PostgresPersistenceIdCursor {
pool: PgPool,
event_journal: String,
journal_head: String,
persistence_id: PersistenceId,
next_sequence_nr: Option<SequenceNr>,
to_sequence_nr: SequenceNr,
buffered: VecDeque<EventEnvelope>,
reached_end: bool,
polling: PostgresPollingConfig,
delay: Duration,
}
async fn next_postgres_persistence_id_event(
mut cursor: PostgresPersistenceIdCursor,
) -> Option<(
PersistenceResult<EventEnvelope>,
PostgresPersistenceIdCursor,
)> {
loop {
if let Some(envelope) = cursor.buffered.pop_front() {
return Some((Ok(envelope), cursor));
}
let next_sequence_nr = cursor.next_sequence_nr?;
if cursor.reached_end {
return None;
}
let highest = match postgres_highest_sequence_nr(
&cursor.pool,
&cursor.journal_head,
&cursor.persistence_id,
)
.await
{
Ok(highest) => highest,
Err(error) => return Some((Err(error), cursor)),
};
let boundary = highest.min(cursor.to_sequence_nr);
if next_sequence_nr <= boundary {
let events = match postgres_events_by_persistence_id(
&cursor.pool,
&cursor.event_journal,
&cursor.persistence_id,
next_sequence_nr,
boundary,
Some(cursor.polling.batch_size),
)
.await
{
Ok(events) => events,
Err(error) => return Some((Err(error), cursor)),
};
if let Some(last) = events.last() {
cursor.next_sequence_nr = last
.sequence_nr
.as_u64()
.checked_add(1)
.map(SequenceNr::new);
cursor.reached_end = last.sequence_nr >= cursor.to_sequence_nr;
cursor.buffered = VecDeque::from(events);
cursor.delay = cursor.polling.min_interval;
continue;
}
cursor.next_sequence_nr = highest.as_u64().checked_add(1).map(SequenceNr::new);
}
cursor.reached_end = highest >= cursor.to_sequence_nr;
if cursor.reached_end {
return None;
}
postgres_poll_sleep(&mut cursor.delay, &cursor.polling).await;
}
}
struct PostgresTagCursor {
pool: PgPool,
event_journal: String,
tag: Tag,
resume: PostgresResume,
upper_bound: PostgresTimestampUpperBound,
buffered: VecDeque<EventEnvelope>,
polling: PostgresPollingConfig,
delay: Duration,
}
async fn next_postgres_tag_event(
mut cursor: PostgresTagCursor,
) -> Option<(PersistenceResult<EventEnvelope>, PostgresTagCursor)> {
loop {
if let Some(envelope) = cursor.buffered.pop_front() {
return Some((Ok(envelope), cursor));
}
let events = match postgres_events_by_tag(
&cursor.pool,
&cursor.event_journal,
&cursor.tag,
&cursor.resume,
cursor.upper_bound,
Some(cursor.polling.batch_size),
)
.await
{
Ok(events) => events,
Err(error) => return Some((Err(error), cursor)),
};
if let Some(last) = events.last() {
cursor.resume = PostgresResume::After(postgres_event_position(last));
cursor.buffered = VecDeque::from(events);
cursor.delay = cursor.polling.min_interval;
continue;
}
postgres_poll_sleep(&mut cursor.delay, &cursor.polling).await;
}
}
struct PostgresSliceCursor {
pool: PgPool,
event_journal: String,
entity_type: String,
range: SliceRange,
resume: PostgresResume,
upper_bound: PostgresTimestampUpperBound,
buffered: VecDeque<EventEnvelope>,
polling: PostgresPollingConfig,
delay: Duration,
}
async fn next_postgres_slice_event(
mut cursor: PostgresSliceCursor,
) -> Option<(PersistenceResult<EventEnvelope>, PostgresSliceCursor)> {
loop {
if let Some(envelope) = cursor.buffered.pop_front() {
return Some((Ok(envelope), cursor));
}
let events = match postgres_events_by_slices(
&cursor.pool,
&cursor.event_journal,
&cursor.entity_type,
cursor.range,
&cursor.resume,
cursor.upper_bound,
Some(cursor.polling.batch_size),
)
.await
{
Ok(events) => events,
Err(error) => return Some((Err(error), cursor)),
};
if let Some(last) = events.last() {
cursor.resume = PostgresResume::After(postgres_event_position(last));
cursor.buffered = VecDeque::from(events);
cursor.delay = cursor.polling.min_interval;
continue;
}
postgres_poll_sleep(&mut cursor.delay, &cursor.polling).await;
}
}
struct PostgresPersistenceIdsCursor {
pool: PgPool,
journal_head: String,
known: HashSet<PersistenceId>,
buffered: VecDeque<PersistenceId>,
polling: PostgresPollingConfig,
delay: Duration,
}
async fn next_postgres_persistence_id(
mut cursor: PostgresPersistenceIdsCursor,
) -> Option<(
PersistenceResult<PersistenceId>,
PostgresPersistenceIdsCursor,
)> {
loop {
if let Some(persistence_id) = cursor.buffered.pop_front() {
return Some((Ok(persistence_id), cursor));
}
let ids = match postgres_persistence_ids(&cursor.pool, &cursor.journal_head).await {
Ok(ids) => ids,
Err(error) => return Some((Err(error), cursor)),
};
for persistence_id in ids {
if cursor.known.insert(persistence_id.clone()) {
cursor.buffered.push_back(persistence_id);
}
}
if cursor.buffered.is_empty() {
postgres_poll_sleep(&mut cursor.delay, &cursor.polling).await;
} else {
cursor.delay = cursor.polling.min_interval;
}
}
}
struct PostgresDurableCursor {
pool: PgPool,
durable_state: String,
tag: Tag,
resume: PostgresResume,
upper_bound: PostgresTimestampUpperBound,
buffered: VecDeque<DurableStateChange>,
polling: PostgresPollingConfig,
delay: Duration,
}
async fn next_postgres_durable_change(
mut cursor: PostgresDurableCursor,
) -> Option<(PersistenceResult<DurableStateChange>, PostgresDurableCursor)> {
loop {
if let Some(change) = cursor.buffered.pop_front() {
return Some((Ok(change), cursor));
}
let changes = match postgres_durable_state_changes(
&cursor.pool,
&cursor.durable_state,
&cursor.tag,
&cursor.resume,
cursor.upper_bound,
Some(cursor.polling.batch_size),
)
.await
{
Ok(changes) => changes,
Err(error) => return Some((Err(error), cursor)),
};
if let Some(last) = changes.last() {
cursor.resume = PostgresResume::After(postgres_durable_position(last));
cursor.buffered = VecDeque::from(changes);
cursor.delay = cursor.polling.min_interval;
continue;
}
postgres_poll_sleep(&mut cursor.delay, &cursor.polling).await;
}
}
async fn postgres_poll_sleep(delay: &mut Duration, polling: &PostgresPollingConfig) {
tokio::time::sleep(*delay).await;
*delay = delay.saturating_mul(2).min(polling.max_interval);
}
#[derive(Debug)]
struct PreparedAtomicWrite {
persistence_id: PersistenceId,
first_sequence_nr: i64,
last_sequence_nr: i64,
events: Vec<PreparedEvent>,
}
#[derive(Debug)]
struct PreparedEvent {
persistence_id: PersistenceId,
sequence_nr: i64,
slice: i32,
entity_type: String,
writer_uuid: String,
adapter_manifest: String,
serializer_id: i64,
serializer_manifest: String,
payload: Vec<u8>,
metadata_serializer_id: Option<i64>,
metadata_manifest: Option<String>,
metadata_payload: Option<Vec<u8>>,
tags: Vec<String>,
}
fn validate_first_sequence(
prepared: &PreparedAtomicWrite,
highest_sequence_nr: i64,
) -> Result<(), String> {
match highest_sequence_nr.checked_add(1) {
Some(expected) if expected == prepared.first_sequence_nr => Ok(()),
Some(expected) => Err(format!(
"expected first sequence number {expected} for {}, got {}",
prepared.persistence_id, prepared.first_sequence_nr
)),
None => Err(format!(
"persistence id {} already reached the maximum PostgreSQL sequence number",
prepared.persistence_id
)),
}
}
async fn rollback_rejection(
transaction: Transaction<'_, Postgres>,
reason: String,
) -> PersistenceResult<AppendOutcome> {
transaction
.rollback()
.await
.map_err(|error| storage_error("roll back rejected journal append", error))?;
Ok(AppendOutcome::Rejected { reason })
}
fn prepare_atomic_write(write: AtomicWrite) -> Result<PreparedAtomicWrite, String> {
let persistence_id = write.persistence_id().clone();
if write.events().len() > MAX_JOURNAL_ROWS_PER_INSERT {
return Err(format!(
"atomic write for {persistence_id} has {} events; PostgreSQL supports at most \
{MAX_JOURNAL_ROWS_PER_INSERT} events in one journal INSERT",
write.events().len()
));
}
let mut events = Vec::with_capacity(write.events().len());
for event in write.into_events() {
let sequence_nr = i64::try_from(event.sequence_nr.as_u64()).map_err(|_| {
format!(
"sequence number {} for {} exceeds PostgreSQL BIGINT",
event.sequence_nr, event.persistence_id
)
})?;
let (metadata_serializer_id, metadata_manifest, metadata_payload) =
event.metadata.map_or((None, None, None), |metadata| {
(
Some(i64::from(metadata.serializer_id.as_u32())),
Some(metadata.manifest),
Some(metadata.payload),
)
});
events.push(PreparedEvent {
slice: i32::from(slice_for(event.persistence_id.id())),
entity_type: event.persistence_id.entity_type().to_owned(),
persistence_id: event.persistence_id,
sequence_nr,
writer_uuid: event.writer_uuid,
adapter_manifest: event.adapter_manifest,
serializer_id: i64::from(event.payload.serializer_id.as_u32()),
serializer_manifest: event.payload.manifest,
payload: event.payload.payload,
metadata_serializer_id,
metadata_manifest,
metadata_payload,
tags: event.tags.into_iter().map(Tag::into_inner).collect(),
});
}
let first_sequence_nr = events[0].sequence_nr;
let last_sequence_nr = events[events.len() - 1].sequence_nr;
Ok(PreparedAtomicWrite {
persistence_id,
first_sequence_nr,
last_sequence_nr,
events,
})
}
fn journal_insert_sql_text(table: &str, row_count: usize) -> String {
let mut sql = format!(
"INSERT INTO {table} \
(persistence_id, seq_nr, slice, entity_type, writer, adapter_manifest, \
ser_id, ser_manifest, payload, meta_ser_id, meta_manifest, meta_payload, tags, deleted) \
VALUES "
);
for row in 0..row_count {
if row != 0 {
sql.push_str(", ");
}
sql.push('(');
for column in 0..JOURNAL_COLUMN_COUNT {
if column != 0 {
sql.push_str(", ");
}
let parameter = row * JOURNAL_COLUMN_COUNT + column + 1;
sql.push('$');
sql.push_str(¶meter.to_string());
}
sql.push(')');
}
sql
}
struct InflightAppendGuard<'a> {
inflight: &'a AtomicUsize,
}
impl Drop for InflightAppendGuard<'_> {
fn drop(&mut self) {
self.inflight.fetch_sub(1, Ordering::AcqRel);
}
}
enum GroupedPending {
Rejected(String),
Awaiting(oneshot::Receiver<PersistenceResult<AppendOutcome>>),
}
struct GroupCommitHandle {
sender: mpsc::Sender<GroupCommitRequest>,
}
struct GroupCommitRequest {
prepared: PreparedAtomicWrite,
reply: oneshot::Sender<PersistenceResult<AppendOutcome>>,
}
enum Decision {
Accepted,
Rejected(String),
}
impl Decision {
fn into_outcome(self) -> AppendOutcome {
match self {
Decision::Accepted => AppendOutcome::Accepted,
Decision::Rejected(reason) => AppendOutcome::Rejected { reason },
}
}
}
enum FlushError {
Pre(PersistenceError),
Post {
error: PersistenceError,
decisions: Vec<Decision>,
},
}
struct GroupCommitFlusher {
pool: PgPool,
sql: Arc<PostgresSql>,
config: PostgresGroupCommitConfig,
min_group: Arc<AtomicUsize>,
}
impl GroupCommitFlusher {
async fn run(self, mut receiver: mpsc::Receiver<GroupCommitRequest>) {
while let Some(first) = receiver.recv().await {
let batch = self.collect_batch(&mut receiver, first).await;
self.flush(batch).await;
}
}
async fn collect_batch(
&self,
receiver: &mut mpsc::Receiver<GroupCommitRequest>,
first: GroupCommitRequest,
) -> Vec<GroupCommitRequest> {
let mut batch = vec![first];
let min_group = self.min_group.load(Ordering::SeqCst);
if min_group >= 2 {
let deadline = tokio::time::Instant::now() + TEST_GROUP_BARRIER_TIMEOUT;
while batch.len() < min_group {
match tokio::time::timeout_at(deadline, receiver.recv()).await {
Ok(Some(request)) => batch.push(request),
_ => break,
}
}
return batch;
}
tokio::task::yield_now().await;
self.drain_ready(receiver, &mut batch);
if batch.len() >= 2 {
self.linger(receiver, &mut batch).await;
}
batch
}
fn drain_ready(
&self,
receiver: &mut mpsc::Receiver<GroupCommitRequest>,
batch: &mut Vec<GroupCommitRequest>,
) {
while !self.at_capacity(batch) {
match receiver.try_recv() {
Ok(request) => batch.push(request),
Err(_) => break,
}
}
}
async fn linger(
&self,
receiver: &mut mpsc::Receiver<GroupCommitRequest>,
batch: &mut Vec<GroupCommitRequest>,
) {
if self.config.max_linger.is_zero() {
return;
}
let deadline = tokio::time::Instant::now() + self.config.max_linger;
while !self.at_capacity(batch) {
match tokio::time::timeout_at(deadline, receiver.recv()).await {
Ok(Some(request)) => {
batch.push(request);
self.drain_ready(receiver, batch);
}
_ => break,
}
}
}
fn at_capacity(&self, batch: &[GroupCommitRequest]) -> bool {
if batch.len() >= self.config.max_atomic_writes {
return true;
}
let events: usize = batch
.iter()
.map(|request| request.prepared.events.len())
.sum();
events >= self.config.max_events
}
async fn flush(&self, batch: Vec<GroupCommitRequest>) {
match self.flush_inner(&batch).await {
Ok(decisions) => {
for (request, decision) in batch.into_iter().zip(decisions) {
let _ = request.reply.send(Ok(decision.into_outcome()));
}
}
Err(FlushError::Pre(error)) => {
for request in batch {
let _ = request.reply.send(Err(error.clone()));
}
}
Err(FlushError::Post { error, decisions }) => {
for (request, decision) in batch.into_iter().zip(decisions) {
let reply = match decision {
Decision::Accepted => Err(error.clone()),
Decision::Rejected(reason) => Ok(AppendOutcome::Rejected { reason }),
};
let _ = request.reply.send(reply);
}
}
}
}
async fn flush_inner(&self, batch: &[GroupCommitRequest]) -> Result<Vec<Decision>, FlushError> {
let mut transaction = self.pool.begin().await.map_err(|error| {
FlushError::Pre(storage_error("begin group-commit transaction", error))
})?;
let mut pids: Vec<&str> = batch
.iter()
.map(|request| request.prepared.persistence_id.id())
.collect();
pids.sort_unstable();
pids.dedup();
let pid_strings: Vec<String> = pids.iter().map(|pid| (*pid).to_owned()).collect();
let seed = format!(
"INSERT INTO {head} (persistence_id, highest_seq_nr, deleted_to) \
SELECT ids.pid, \
COALESCE((SELECT MAX(ej.seq_nr) FROM {journal} ej \
WHERE ej.persistence_id = ids.pid), 0), \
0 \
FROM unnest($1::TEXT[]) AS ids(pid) \
WHERE NOT EXISTS (SELECT 1 FROM {head} jh WHERE jh.persistence_id = ids.pid) \
ORDER BY ids.pid \
ON CONFLICT (persistence_id) DO NOTHING \
RETURNING persistence_id, highest_seq_nr",
head = self.sql.journal_head,
journal = self.sql.event_journal,
);
let seeded_rows = sqlx::query(&seed)
.bind(&pid_strings)
.fetch_all(&mut *transaction)
.await
.map_err(|error| {
FlushError::Pre(storage_error("seed group-commit journal heads", error))
})?;
let mut fresh_zero_seeds: HashSet<String> = HashSet::with_capacity(seeded_rows.len());
for row in &seeded_rows {
let pid: String = row.try_get("persistence_id").map_err(|error| {
FlushError::Pre(storage_error("decode seeded group-commit head id", error))
})?;
let highest: i64 = row.try_get("highest_seq_nr").map_err(|error| {
FlushError::Pre(storage_error(
"decode seeded group-commit head watermark",
error,
))
})?;
if highest == 0 {
fresh_zero_seeds.insert(pid);
}
}
let lock = format!(
"SELECT persistence_id, highest_seq_nr FROM {head} \
WHERE persistence_id = ANY($1::TEXT[]) ORDER BY persistence_id FOR UPDATE",
head = self.sql.journal_head,
);
let rows = sqlx::query(&lock)
.bind(&pid_strings)
.fetch_all(&mut *transaction)
.await
.map_err(|error| {
FlushError::Pre(storage_error("lock group-commit journal heads", error))
})?;
let mut heads: HashMap<String, i64> = HashMap::with_capacity(rows.len());
for row in &rows {
let pid: String = row.try_get("persistence_id").map_err(|error| {
FlushError::Pre(storage_error("decode group-commit head id", error))
})?;
let highest: i64 = row.try_get("highest_seq_nr").map_err(|error| {
FlushError::Pre(storage_error("decode group-commit head watermark", error))
})?;
heads.insert(pid, highest);
}
let mut shadow: HashMap<&str, i64> = HashMap::with_capacity(pids.len());
let mut updated: HashMap<&str, i64> = HashMap::new();
let mut accepted_events: Vec<&PreparedEvent> = Vec::new();
let mut decisions = Vec::with_capacity(batch.len());
for request in batch {
let prepared = &request.prepared;
let pid = prepared.persistence_id.id();
let current = match shadow.get(pid).copied().or_else(|| heads.get(pid).copied()) {
Some(current) => current,
None => {
return Err(FlushError::Pre(PersistenceError::Failure(format!(
"group-commit journal head missing for {}",
prepared.persistence_id
))));
}
};
match current.checked_add(1) {
Some(expected) if expected == prepared.first_sequence_nr => {
shadow.insert(pid, prepared.last_sequence_nr);
updated.insert(pid, prepared.last_sequence_nr);
accepted_events.extend(prepared.events.iter());
decisions.push(Decision::Accepted);
}
Some(expected) => decisions.push(Decision::Rejected(format!(
"expected first sequence number {expected} for {}, got {}",
prepared.persistence_id, prepared.first_sequence_nr
))),
None => decisions.push(Decision::Rejected(format!(
"persistence id {} already reached the maximum PostgreSQL sequence number",
prepared.persistence_id
))),
}
}
for chunk in accepted_events.chunks(MAX_JOURNAL_ROWS_PER_INSERT) {
let insert = self.sql.journal_insert_sql(chunk.len());
let mut query = sqlx::query(&insert);
for event in chunk {
query = query
.bind(event.persistence_id.id())
.bind(event.sequence_nr)
.bind(event.slice)
.bind(event.entity_type.as_str())
.bind(event.writer_uuid.as_str())
.bind(event.adapter_manifest.as_str())
.bind(event.serializer_id)
.bind(event.serializer_manifest.as_str())
.bind(event.payload.as_slice())
.bind(event.metadata_serializer_id)
.bind(event.metadata_manifest.as_deref())
.bind(event.metadata_payload.as_deref())
.bind(&event.tags)
.bind(false);
}
if let Err(error) = query.execute(&mut *transaction).await {
return Err(FlushError::Post {
error: storage_error("insert group-commit journal writes", error),
decisions,
});
}
}
if !updated.is_empty() {
let mut update_ids: Vec<String> = Vec::with_capacity(updated.len());
let mut update_highest: Vec<i64> = Vec::with_capacity(updated.len());
for (pid, highest) in &updated {
update_ids.push((*pid).to_owned());
update_highest.push(*highest);
}
let update = format!(
"UPDATE {head} AS jh SET highest_seq_nr = data.highest \
FROM (SELECT * FROM unnest($1::TEXT[], $2::BIGINT[]) AS t(pid, highest)) AS data \
WHERE jh.persistence_id = data.pid",
head = self.sql.journal_head,
);
if let Err(error) = sqlx::query(&update)
.bind(&update_ids)
.bind(&update_highest)
.execute(&mut *transaction)
.await
{
return Err(FlushError::Post {
error: storage_error("update group-commit journal heads", error),
decisions,
});
}
}
let stale_seeds: Vec<String> = fresh_zero_seeds
.into_iter()
.filter(|pid| !updated.contains_key(pid.as_str()))
.collect();
if !stale_seeds.is_empty() {
let delete_stale_seeds = format!(
"DELETE FROM {head} WHERE persistence_id = ANY($1::TEXT[]) AND highest_seq_nr = 0",
head = self.sql.journal_head,
);
if let Err(error) = sqlx::query(&delete_stale_seeds)
.bind(&stale_seeds)
.execute(&mut *transaction)
.await
{
return Err(FlushError::Post {
error: storage_error("delete stale group-commit journal head seeds", error),
decisions,
});
}
}
if let Err(error) = transaction.commit().await {
return Err(FlushError::Post {
error: storage_error("commit group-commit transaction", error),
decisions,
});
}
Ok(decisions)
}
}
#[derive(Debug)]
struct ReplayState {
pool: PgPool,
table: String,
persistence_id: PersistenceId,
next_sequence_nr: i64,
to_sequence_nr: i64,
remaining: u64,
page_size: u32,
buffered: VecDeque<StoredEvent>,
finished: bool,
}
async fn replay_next(
mut state: ReplayState,
) -> PersistenceResult<Option<(StoredEvent, ReplayState)>> {
loop {
if let Some(event) = state.buffered.pop_front() {
state.remaining -= 1;
if event.sequence_nr.as_u64() == i64::MAX as u64 {
state.finished = true;
} else {
state.next_sequence_nr = i64::try_from(event.sequence_nr.as_u64() + 1)
.expect("a replayed sequence below i64::MAX has a representable successor");
}
return Ok(Some((event, state)));
}
if state.finished || state.remaining == 0 || state.next_sequence_nr > state.to_sequence_nr {
return Ok(None);
}
let page_limit = u64::from(state.page_size).min(state.remaining);
let select = format!(
"SELECT persistence_id, seq_nr, adapter_manifest, writer, \
(EXTRACT(EPOCH FROM db_timestamp) * 1000)::BIGINT AS timestamp_ms, \
ser_id, ser_manifest, payload, meta_ser_id, meta_manifest, meta_payload, tags \
FROM {} WHERE persistence_id = $1 AND seq_nr >= $2 AND seq_nr <= $3 \
AND NOT deleted ORDER BY seq_nr ASC LIMIT $4",
state.table
);
let rows = sqlx::query(&select)
.bind(state.persistence_id.id())
.bind(state.next_sequence_nr)
.bind(state.to_sequence_nr)
.bind(i64::try_from(page_limit).unwrap_or(i64::MAX))
.fetch_all(&state.pool)
.await
.map_err(|error| storage_error("fetch journal replay page", error))?;
if rows.is_empty() {
return Ok(None);
}
for row in rows {
state.buffered.push_back(decode_event_row(&row)?);
}
}
}
fn decode_event_row(row: &sqlx::postgres::PgRow) -> PersistenceResult<StoredEvent> {
let persistence_id: String = row
.try_get("persistence_id")
.map_err(|error| storage_error("decode event persistence id", error))?;
let sequence_nr: i64 = row
.try_get("seq_nr")
.map_err(|error| storage_error("decode event sequence number", error))?;
let serializer_id: i64 = row
.try_get("ser_id")
.map_err(|error| storage_error("decode event serializer id", error))?;
let metadata_serializer_id: Option<i64> = row
.try_get("meta_ser_id")
.map_err(|error| storage_error("decode event metadata serializer id", error))?;
let metadata_manifest: Option<String> = row
.try_get("meta_manifest")
.map_err(|error| storage_error("decode event metadata manifest", error))?;
let metadata_payload: Option<Vec<u8>> = row
.try_get("meta_payload")
.map_err(|error| storage_error("decode event metadata payload", error))?;
let metadata = decode_optional_frame(
metadata_serializer_id,
metadata_manifest,
metadata_payload,
"event metadata",
)?;
let tags: Vec<String> = row
.try_get("tags")
.map_err(|error| storage_error("decode event tags", error))?;
Ok(StoredEvent {
persistence_id: PersistenceId::from_unique(persistence_id)?,
sequence_nr: SequenceNr::new(non_negative_u64(sequence_nr, "event sequence number")?),
adapter_manifest: row
.try_get("adapter_manifest")
.map_err(|error| storage_error("decode event adapter manifest", error))?,
writer_uuid: row
.try_get("writer")
.map_err(|error| storage_error("decode event writer", error))?,
timestamp_ms: row
.try_get("timestamp_ms")
.map_err(|error| storage_error("decode event database timestamp", error))?,
metadata,
payload: SerializedPayload::new(
serializer_id_from_i64(serializer_id, "event serializer id")?,
row.try_get::<String, _>("ser_manifest")
.map_err(|error| storage_error("decode event serializer manifest", error))?,
row.try_get::<Vec<u8>, _>("payload")
.map_err(|error| storage_error("decode event payload", error))?,
),
tags: tags.into_iter().map(Tag::new).collect(),
})
}
fn decode_snapshot_row(
persistence_id: &PersistenceId,
row: &sqlx::postgres::PgRow,
) -> PersistenceResult<SelectedSnapshot> {
let sequence_nr: i64 = row
.try_get("seq_nr")
.map_err(|error| storage_error("decode snapshot sequence number", error))?;
let serializer_id: i64 = row
.try_get("ser_id")
.map_err(|error| storage_error("decode snapshot serializer id", error))?;
Ok(SelectedSnapshot {
metadata: SnapshotMetadata {
persistence_id: persistence_id.clone(),
sequence_nr: SequenceNr::new(non_negative_u64(
sequence_nr,
"snapshot sequence number",
)?),
timestamp_ms: row
.try_get("timestamp_ms")
.map_err(|error| storage_error("decode snapshot timestamp", error))?,
},
adapter_manifest: row
.try_get("adapter_manifest")
.map_err(|error| storage_error("decode snapshot adapter manifest", error))?,
state: SerializedPayload::new(
serializer_id_from_i64(serializer_id, "snapshot serializer id")?,
row.try_get::<String, _>("ser_manifest")
.map_err(|error| storage_error("decode snapshot serializer manifest", error))?,
row.try_get::<Vec<u8>, _>("payload")
.map_err(|error| storage_error("decode snapshot payload", error))?,
),
})
}
fn decode_versioned_state(row: &sqlx::postgres::PgRow) -> PersistenceResult<VersionedState> {
let revision: i64 = row
.try_get("revision")
.map_err(|error| storage_error("decode durable-state revision", error))?;
let deleted: bool = row
.try_get("deleted")
.map_err(|error| storage_error("decode durable-state tombstone", error))?;
let revision = Revision::new(non_negative_u64(revision, "durable-state revision")?);
if deleted {
return Ok(VersionedState {
state: None,
revision,
tag: None,
});
}
let serializer_id: Option<i64> = row
.try_get("ser_id")
.map_err(|error| storage_error("decode durable-state serializer id", error))?;
let serializer_manifest: Option<String> = row
.try_get("ser_manifest")
.map_err(|error| storage_error("decode durable-state serializer manifest", error))?;
let payload: Option<Vec<u8>> = row
.try_get("payload")
.map_err(|error| storage_error("decode durable-state payload", error))?;
let state =
decode_optional_frame(serializer_id, serializer_manifest, payload, "durable state")?
.ok_or_else(|| {
PersistenceError::Failure(
"PostgreSQL durable-state row is live but has no serialization frame".into(),
)
})?;
let tag: Option<String> = row
.try_get("tag")
.map_err(|error| storage_error("decode durable-state tag", error))?;
Ok(VersionedState {
state: Some(state),
revision,
tag: tag.map(Tag::new),
})
}
fn decode_optional_frame(
serializer_id: Option<i64>,
manifest: Option<String>,
payload: Option<Vec<u8>>,
context: &str,
) -> PersistenceResult<Option<SerializedPayload>> {
match (serializer_id, manifest, payload) {
(None, None, None) => Ok(None),
(Some(serializer_id), Some(manifest), Some(payload)) => Ok(Some(SerializedPayload::new(
serializer_id_from_i64(serializer_id, context)?,
manifest,
payload,
))),
_ => Err(PersistenceError::Failure(format!(
"PostgreSQL {context} frame is only partially populated"
))),
}
}
fn serializer_id_from_i64(value: i64, context: &str) -> PersistenceResult<SerializerId> {
u32::try_from(value)
.map(SerializerId::new)
.map_err(|_| PersistenceError::Failure(format!("invalid {context} value {value}")))
}
fn non_negative_u64(value: i64, context: &str) -> PersistenceResult<u64> {
u64::try_from(value)
.map_err(|_| PersistenceError::Failure(format!("negative {context} value {value}")))
}
fn sql_i64(value: u64, context: &str) -> PersistenceResult<i64> {
i64::try_from(value).map_err(|_| {
PersistenceError::Rejected(format!("{context} {value} exceeds PostgreSQL BIGINT"))
})
}
fn duration_micros_i64(duration: Duration, context: &str) -> PersistenceResult<i64> {
i64::try_from(duration.as_micros()).map_err(|_| {
PersistenceError::Rejected(format!(
"{context} exceeds PostgreSQL's signed microsecond interval range"
))
})
}
fn pool_options(config: &PostgresPersistenceConfig) -> PgPoolOptions {
PgPoolOptions::new()
.max_connections(config.max_connections)
.min_connections(config.min_connections)
.acquire_timeout(config.acquire_timeout)
.idle_timeout(config.idle_timeout)
.max_lifetime(config.max_lifetime)
}
async fn bootstrap(pool: &PgPool, ddl: &[String]) -> PersistenceResult<()> {
let mut transaction = pool
.begin()
.await
.map_err(|error| storage_error("begin PostgreSQL schema bootstrap", error))?;
for statement in ddl {
sqlx::query(statement)
.execute(&mut *transaction)
.await
.map_err(|error| storage_error("execute PostgreSQL schema bootstrap", error))?;
}
transaction
.commit()
.await
.map_err(|error| storage_error("commit PostgreSQL schema bootstrap", error))
}
fn validate_config(config: &PostgresPersistenceConfig) -> PersistenceResult<()> {
validate_identifier("schema", &config.schema, 63)?;
validate_identifier(
"event journal table",
&config.tables.event_journal,
MAX_TABLE_IDENTIFIER_BYTES,
)?;
validate_identifier(
"snapshot table",
&config.tables.snapshot,
MAX_TABLE_IDENTIFIER_BYTES,
)?;
validate_identifier(
"durable-state table",
&config.tables.durable_state,
MAX_TABLE_IDENTIFIER_BYTES,
)?;
validate_identifier(
"journal-head table",
&config.tables.journal_head,
MAX_TABLE_IDENTIFIER_BYTES,
)?;
if config.max_connections == 0 {
return Err(PersistenceError::Rejected(
"PostgreSQL max_connections must be greater than zero".into(),
));
}
if config.min_connections > config.max_connections {
return Err(PersistenceError::Rejected(format!(
"PostgreSQL min_connections {} exceeds max_connections {}",
config.min_connections, config.max_connections
)));
}
if config.acquire_timeout.is_zero() {
return Err(PersistenceError::Rejected(
"PostgreSQL acquire_timeout must be greater than zero".into(),
));
}
if config.replay_page_size == 0 {
return Err(PersistenceError::Rejected(
"PostgreSQL replay_page_size must be greater than zero".into(),
));
}
if config.polling.batch_size == 0 {
return Err(PersistenceError::Rejected(
"PostgreSQL polling batch_size must be greater than zero".into(),
));
}
if config.polling.min_interval.is_zero() {
return Err(PersistenceError::Rejected(
"PostgreSQL polling min_interval must be greater than zero".into(),
));
}
if config.polling.min_interval > config.polling.max_interval {
return Err(PersistenceError::Rejected(
"PostgreSQL polling min_interval must not exceed max_interval".into(),
));
}
duration_micros_i64(
config.polling.visibility_lag,
"PostgreSQL polling visibility_lag",
)?;
if config.group_commit.enabled {
if config.group_commit.queue_capacity == 0 {
return Err(PersistenceError::Rejected(
"PostgreSQL group_commit queue_capacity must be greater than zero".into(),
));
}
if config.group_commit.max_atomic_writes == 0 {
return Err(PersistenceError::Rejected(
"PostgreSQL group_commit max_atomic_writes must be greater than zero".into(),
));
}
if config.group_commit.max_events == 0 {
return Err(PersistenceError::Rejected(
"PostgreSQL group_commit max_events must be greater than zero".into(),
));
}
}
Ok(())
}
fn validate_identifier(name: &str, value: &str, max_bytes: usize) -> PersistenceResult<()> {
let mut characters = value.chars();
let valid_first = characters
.next()
.is_some_and(|character| character == '_' || character.is_ascii_alphabetic());
if !valid_first
|| !characters.all(|character| character == '_' || character.is_ascii_alphanumeric())
|| value.len() > max_bytes
{
return Err(PersistenceError::Rejected(format!(
"invalid PostgreSQL {name} identifier {value:?}; expected an ASCII identifier of at most {max_bytes} bytes"
)));
}
Ok(())
}
fn quote_identifier(identifier: &str) -> String {
format!("\"{identifier}\"")
}
fn qualified(schema: &str, table: &str) -> String {
format!("{}.{}", quote_identifier(schema), quote_identifier(table))
}
fn connection_error(context: &str, error: sqlx::Error) -> PersistenceError {
PersistenceError::Connection(format!("{context}: {error}"))
}
fn storage_error(context: &str, error: sqlx::Error) -> PersistenceError {
match error {
error @ (sqlx::Error::Configuration(_)
| sqlx::Error::Io(_)
| sqlx::Error::Tls(_)
| sqlx::Error::Protocol(_)
| sqlx::Error::PoolTimedOut
| sqlx::Error::PoolClosed
| sqlx::Error::WorkerCrashed
| sqlx::Error::BeginFailed) => PersistenceError::Connection(format!("{context}: {error}")),
error => PersistenceError::Failure(format!("{context}: {error}")),
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn config_defaults_to_soft_delete_and_expected_tables() {
let config =
PostgresPersistenceConfig::new("postgres://datum:secret@example.invalid/datum");
assert_eq!(config.delete_policy, PostgresDeletePolicy::Soft);
assert_eq!(config.schema, "public");
assert_eq!(config.tables, PostgresTableNames::default());
assert!(config.replay_page_size > 0);
assert_eq!(config.polling.visibility_lag, DEFAULT_QUERY_VISIBILITY_LAG);
assert!(config.group_commit.enabled);
assert_eq!(
config.group_commit.queue_capacity,
DEFAULT_GROUP_COMMIT_QUEUE_CAPACITY
);
assert_eq!(
config.group_commit.max_atomic_writes,
DEFAULT_GROUP_COMMIT_MAX_ATOMIC_WRITES
);
assert_eq!(
config.group_commit.max_events,
DEFAULT_GROUP_COMMIT_MAX_EVENTS
);
assert_eq!(
config.group_commit.max_linger,
DEFAULT_GROUP_COMMIT_MAX_LINGER
);
assert_eq!(
config.group_commit.bypass_below,
DEFAULT_GROUP_COMMIT_BYPASS_BELOW
);
assert_eq!(
config.group_commit.bypass_below as u32,
DEFAULT_MAX_CONNECTIONS
);
assert!(config.group_commit.max_events <= MAX_JOURNAL_ROWS_PER_INSERT);
assert!(!format!("{config:?}").contains("secret"));
}
#[test]
fn group_commit_bypass_threshold_uses_demand_before_self_without_io() {
let mut config = PostgresPersistenceConfig::new("postgres://example.invalid/datum");
config.group_commit.bypass_below = 2;
let backend = PostgresPersistence::new(config).expect("valid config constructs lazily");
assert!(backend.should_bypass_group_commit(0));
assert!(backend.should_bypass_group_commit(1));
assert!(!backend.should_bypass_group_commit(2));
assert!(!backend.should_bypass_group_commit(100));
let mut zero_config = PostgresPersistenceConfig::new("postgres://example.invalid/datum");
zero_config.group_commit.bypass_below = 0;
let disabled =
PostgresPersistence::new(zero_config).expect("valid config constructs lazily");
assert!(!disabled.should_bypass_group_commit(0));
}
#[test]
fn group_commit_inflight_guard_tracks_demand_before_self_without_io() {
let config = PostgresPersistenceConfig::new("postgres://example.invalid/datum");
let backend = PostgresPersistence::new(config).expect("valid config constructs lazily");
let (guard_a, demand_a) = backend.enter_inflight_append();
assert_eq!(demand_a, 0, "the first append observes zero prior demand");
let (guard_b, demand_b) = backend.enter_inflight_append();
assert_eq!(
demand_b, 1,
"the second append observes the first as demand"
);
drop(guard_a);
let (guard_c, demand_c) = backend.enter_inflight_append();
assert_eq!(
demand_c, 1,
"dropping the first guard frees its demand slot"
);
drop(guard_b);
drop(guard_c);
let (guard_d, demand_d) = backend.enter_inflight_append();
assert_eq!(demand_d, 0, "demand returns to zero once all guards drop");
drop(guard_d);
}
#[test]
fn zero_group_commit_bounds_are_rejected_without_io() {
for mutate in [
|config: &mut PostgresPersistenceConfig| config.group_commit.queue_capacity = 0,
|config: &mut PostgresPersistenceConfig| config.group_commit.max_atomic_writes = 0,
|config: &mut PostgresPersistenceConfig| config.group_commit.max_events = 0,
] {
let mut config = PostgresPersistenceConfig::new("postgres://example.invalid/datum");
mutate(&mut config);
assert!(
matches!(
PostgresPersistence::new(config),
Err(PersistenceError::Rejected(_))
),
"zero group-commit bound must be rejected without IO"
);
}
let mut config = PostgresPersistenceConfig::new("postgres://example.invalid/datum");
config.group_commit.enabled = false;
config.group_commit.queue_capacity = 0;
assert!(PostgresPersistence::new(config).is_ok());
}
#[test]
fn timestamp_cursor_predicates_distinguish_current_boundaries_from_live_lag() {
let current = PostgresTimestampUpperBound::Current { epoch_micros: 17 };
assert_eq!(current.value(), 17);
assert_eq!(
current.sql_predicate(4),
"db_timestamp <= TIMESTAMPTZ 'epoch' + $4::BIGINT * INTERVAL '1 microsecond'"
);
let live = PostgresTimestampUpperBound::Live {
visibility_lag_micros: 250_000,
};
assert_eq!(live.value(), 250_000);
assert_eq!(
live.sql_predicate(5),
"db_timestamp <= now() - $5::BIGINT * INTERVAL '1 microsecond'"
);
}
#[test]
fn construction_is_lazy_and_ddl_contains_required_shape() {
let backend = PostgresPersistence::new(PostgresPersistenceConfig::new(
"postgres://example.invalid/datum",
))
.expect("local configuration is valid");
assert!(backend.pool().is_none());
let ddl = backend.schema_ddl();
for fragment in [
"CREATE TABLE IF NOT EXISTS \"public\".\"event_journal\"",
"PRIMARY KEY (persistence_id, seq_nr)",
"db_timestamp TIMESTAMPTZ NOT NULL DEFAULT now()",
"USING GIN (tags)",
"CREATE TABLE IF NOT EXISTS \"public\".\"snapshot\"",
"adapter_manifest TEXT NOT NULL",
"CREATE TABLE IF NOT EXISTS \"public\".\"durable_state\"",
"CREATE INDEX IF NOT EXISTS \"durable_state_tag_timestamp_idx\" ON \"public\".\"durable_state\" (tag, db_timestamp)",
"CREATE TABLE IF NOT EXISTS \"public\".\"journal_head\"",
"highest_seq_nr BIGINT NOT NULL",
"deleted_to BIGINT NOT NULL DEFAULT 0",
] {
assert!(ddl.contains(fragment), "missing DDL fragment {fragment:?}");
}
}
#[test]
fn invalid_identifiers_and_pool_bounds_are_rejected_without_io() {
let mut config = PostgresPersistenceConfig::new("postgres://example.invalid/datum");
config.schema = "bad-schema".into();
assert!(matches!(
PostgresPersistence::new(config),
Err(PersistenceError::Rejected(_))
));
let mut config = PostgresPersistenceConfig::new("postgres://example.invalid/datum");
config.min_connections = 2;
config.max_connections = 1;
assert!(matches!(
PostgresPersistence::new(config),
Err(PersistenceError::Rejected(_))
));
}
#[test]
fn zero_and_inverted_poll_intervals_are_rejected_without_io() {
let mut config = PostgresPersistenceConfig::new("postgres://example.invalid/datum");
config.polling.min_interval = Duration::ZERO;
assert!(
matches!(
PostgresPersistence::new(config),
Err(PersistenceError::Rejected(reason))
if reason == "PostgreSQL polling min_interval must be greater than zero"
),
"zero poll delay must be rejected"
);
let mut config = PostgresPersistenceConfig::new("postgres://example.invalid/datum");
config.polling.min_interval = Duration::from_millis(2);
config.polling.max_interval = Duration::from_millis(1);
assert!(
matches!(
PostgresPersistence::new(config),
Err(PersistenceError::Rejected(reason))
if reason == "PostgreSQL polling min_interval must not exceed max_interval"
),
"inverted poll bounds must be rejected"
);
}
#[test]
fn generated_multi_row_insert_has_contiguous_parameters() {
let sql = journal_insert_sql_text("events", 2);
assert!(sql.contains("($1, $2, $3"));
assert!(sql.contains("$14), ($15"));
assert!(sql.ends_with("$28)"));
}
#[test]
fn precomputed_lock_and_update_head_sql_reference_journal_head_table() {
let config = PostgresPersistenceConfig::new("postgres://example.invalid/datum");
let sql = PostgresSql::new(&config).expect("local configuration is valid");
assert!(sql.lock_head_sql.contains(&sql.journal_head));
assert!(sql.lock_head_sql.contains("FOR UPDATE"));
assert!(sql.update_head_sql.contains(&sql.journal_head));
assert!(sql.update_head_sql.contains("SET highest_seq_nr = $2"));
}
#[test]
fn journal_insert_sql_is_cached_per_row_count() {
let config = PostgresPersistenceConfig::new("postgres://example.invalid/datum");
let sql = PostgresSql::new(&config).expect("local configuration is valid");
let first = sql.journal_insert_sql(3);
let second = sql.journal_insert_sql(3);
assert!(
Arc::ptr_eq(&first, &second),
"repeated calls with the same row count must reuse the cached allocation"
);
assert_eq!(
&*first,
journal_insert_sql_text(&sql.event_journal, 3).as_str()
);
let different = sql.journal_insert_sql(4);
assert!(
!Arc::ptr_eq(&first, &different),
"distinct row counts must not alias the same template"
);
assert_eq!(
&*different,
journal_insert_sql_text(&sql.event_journal, 4).as_str()
);
}
#[test]
fn journal_insert_sql_cache_is_bounded() {
let config = PostgresPersistenceConfig::new("postgres://example.invalid/datum");
let sql = PostgresSql::new(&config).expect("local configuration is valid");
for row_count in 1..=(INSERT_SQL_CACHE_CAP + 8) {
let _ = sql.journal_insert_sql(row_count);
}
let cache_len = sql
.insert_sql_cache
.read()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.len();
assert!(
cache_len <= INSERT_SQL_CACHE_CAP,
"cache must stay bounded by INSERT_SQL_CACHE_CAP, got {cache_len}"
);
}
#[test]
fn published_slice_is_used_by_the_postgres_journal() {
let first = slice_for("account|42");
assert_eq!(first, slice_for("account|42"));
assert!(first < SLICE_COUNT);
}
}