use std::{fmt, sync::Arc, time::Duration};
use sqlx::{
PgPool, Postgres, Row, Transaction,
postgres::{PgPoolOptions, PgRow},
};
use tokio::sync::OnceCell;
use crate::{PersistenceId, SequenceNr};
use super::{
BoundaryEvent, CursorPosition, DeduplicationBoundary, PostgresProjectionTx, ProjectionCursor,
ProjectionError, ProjectionGeneration, ProjectionId, ProjectionOffsetStore, ProjectionResult,
ProviderManifest, SaveCrashPoint,
};
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 MAX_TABLE_IDENTIFIER_BYTES: usize = 48;
const MAX_GENERATION: i64 = i64::MAX;
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PostgresProjectionTableNames {
pub offset_store: String,
pub timestamp_offset_store: String,
pub management: String,
}
impl Default for PostgresProjectionTableNames {
fn default() -> Self {
Self {
offset_store: "datum_projection_offset_store".into(),
timestamp_offset_store: "datum_projection_timestamp_offset_store".into(),
management: "datum_projection_management".into(),
}
}
}
#[derive(Clone)]
pub struct PostgresProjectionOffsetStoreConfig {
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: PostgresProjectionTableNames,
}
impl PostgresProjectionOffsetStoreConfig {
#[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: PostgresProjectionTableNames::default(),
}
}
#[must_use]
pub fn for_pool() -> Self {
let mut config = Self::new(String::new());
config.database_url = None;
config
}
}
impl fmt::Debug for PostgresProjectionOffsetStoreConfig {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("PostgresProjectionOffsetStoreConfig")
.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)
.finish()
}
}
#[derive(Debug)]
struct PostgresProjectionSql {
bootstrap_lock_key: i64,
management: String,
ddl: Vec<String>,
load: String,
lock: String,
insert_claim_row: String,
insert_claim_owner: String,
load_generation: String,
lock_generation: String,
increment_generation: String,
update_cursor: String,
clear_cursor: String,
delete_boundary: String,
insert_boundary: String,
}
impl PostgresProjectionSql {
fn new(config: &PostgresProjectionOffsetStoreConfig) -> ProjectionResult<Self> {
validate_config(config)?;
let schema = quote_identifier(&config.schema);
let offset_store = qualified(&config.schema, &config.tables.offset_store);
let timestamp_offset_store =
qualified(&config.schema, &config.tables.timestamp_offset_store);
let management = qualified(&config.schema, &config.tables.management);
let ddl = vec![
format!("CREATE SCHEMA IF NOT EXISTS {schema}"),
format!(
"CREATE TABLE IF NOT EXISTS {offset_store} (\
projection_name TEXT NOT NULL,\
projection_key TEXT NOT NULL,\
current_offset TEXT,\
manifest TEXT,\
mergeable BOOLEAN NOT NULL DEFAULT FALSE,\
last_updated BIGINT NOT NULL DEFAULT 0,\
generation BIGINT NOT NULL DEFAULT 0 CHECK (generation >= 0),\
PRIMARY KEY (projection_name, projection_key),\
CHECK ((current_offset IS NULL) = (manifest IS NULL))\
)"
),
format!(
"ALTER TABLE {offset_store} ADD COLUMN IF NOT EXISTS \
generation BIGINT NOT NULL DEFAULT 0"
),
format!(
"ALTER TABLE {offset_store} ADD COLUMN IF NOT EXISTS \
mergeable BOOLEAN NOT NULL DEFAULT FALSE"
),
format!(
"ALTER TABLE {offset_store} ALTER COLUMN current_offset TYPE TEXT, \
ALTER COLUMN current_offset DROP NOT NULL"
),
format!(
"ALTER TABLE {offset_store} ALTER COLUMN manifest TYPE TEXT, \
ALTER COLUMN manifest DROP NOT NULL"
),
format!(
"CREATE TABLE IF NOT EXISTS {timestamp_offset_store} (\
projection_name TEXT NOT NULL,\
projection_key TEXT NOT NULL,\
current_offset TEXT NOT NULL,\
persistence_id TEXT NOT NULL,\
seq_nr BIGINT NOT NULL CHECK (seq_nr >= 0),\
PRIMARY KEY (projection_name, projection_key, persistence_id, seq_nr),\
FOREIGN KEY (projection_name, projection_key) \
REFERENCES {offset_store} (projection_name, projection_key) \
ON DELETE CASCADE\
)"
),
format!(
"CREATE TABLE IF NOT EXISTS {management} (\
projection_name TEXT NOT NULL,\
projection_key TEXT NOT NULL,\
paused BOOLEAN NOT NULL,\
last_updated BIGINT NOT NULL DEFAULT 0,\
generation BIGINT NOT NULL DEFAULT 0 CHECK (generation >= 0),\
PRIMARY KEY (projection_name, projection_key)\
)"
),
format!(
"ALTER TABLE {management} ADD COLUMN IF NOT EXISTS \
generation BIGINT NOT NULL DEFAULT 0"
),
format!(
"UPDATE {management} AS management SET generation = offsets.generation \
FROM {offset_store} AS offsets \
WHERE management.projection_name = offsets.projection_name \
AND management.projection_key = offsets.projection_key \
AND management.generation < offsets.generation"
),
];
Ok(Self {
bootstrap_lock_key: bootstrap_lock_key(config),
load: format!(
"SELECT offsets.current_offset, offsets.manifest, \
boundary.current_offset AS boundary_offset, \
boundary.persistence_id, boundary.seq_nr \
FROM {offset_store} AS offsets \
LEFT JOIN {timestamp_offset_store} AS boundary \
ON boundary.projection_name = offsets.projection_name \
AND boundary.projection_key = offsets.projection_key \
WHERE offsets.projection_name = $1 AND offsets.projection_key = $2 \
ORDER BY boundary.persistence_id, boundary.seq_nr"
),
lock: format!(
"SELECT current_offset FROM {offset_store} \
WHERE projection_name = $1 AND projection_key = $2 FOR UPDATE"
),
insert_claim_row: format!(
"INSERT INTO {offset_store} \
(projection_name, projection_key, current_offset, manifest, \
mergeable, last_updated, generation) \
VALUES ($1, $2, NULL, NULL, FALSE, 0, 0) \
ON CONFLICT (projection_name, projection_key) DO NOTHING"
),
insert_claim_owner: format!(
"INSERT INTO {management} \
(projection_name, projection_key, paused, last_updated, generation) \
SELECT $1, $2, FALSE, 0, generation FROM {offset_store} \
WHERE projection_name = $1 AND projection_key = $2 \
ON CONFLICT (projection_name, projection_key) DO NOTHING"
),
load_generation: format!(
"SELECT generation FROM {management} \
WHERE projection_name = $1 AND projection_key = $2"
),
lock_generation: format!(
"SELECT generation FROM {management} \
WHERE projection_name = $1 AND projection_key = $2 FOR UPDATE"
),
increment_generation: format!(
"UPDATE {management} SET generation = generation + 1 \
WHERE projection_name = $1 AND projection_key = $2 \
AND generation < {MAX_GENERATION} \
RETURNING generation"
),
update_cursor: format!(
"UPDATE {offset_store} SET current_offset = $3, manifest = $4, \
mergeable = FALSE, generation = $5, \
last_updated = floor(extract(epoch from clock_timestamp()) * 1000)::BIGINT \
WHERE projection_name = $1 AND projection_key = $2"
),
clear_cursor: format!(
"UPDATE {offset_store} SET current_offset = NULL, manifest = NULL, \
mergeable = FALSE, generation = $3, \
last_updated = floor(extract(epoch from clock_timestamp()) * 1000)::BIGINT \
WHERE projection_name = $1 AND projection_key = $2"
),
delete_boundary: format!(
"DELETE FROM {timestamp_offset_store} \
WHERE projection_name = $1 AND projection_key = $2"
),
insert_boundary: format!(
"INSERT INTO {timestamp_offset_store} \
(projection_name, projection_key, current_offset, persistence_id, seq_nr) \
VALUES ($1, $2, $3, $4, $5)"
),
management,
ddl,
})
}
}
struct PostgresProjectionOffsetStoreInner {
config: PostgresProjectionOffsetStoreConfig,
sql: PostgresProjectionSql,
pool: OnceCell<PgPool>,
initialized: OnceCell<()>,
}
#[derive(Clone)]
pub struct PostgresProjectionOffsetStore {
inner: Arc<PostgresProjectionOffsetStoreInner>,
}
impl fmt::Debug for PostgresProjectionOffsetStore {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("PostgresProjectionOffsetStore")
.field("config", &self.inner.config)
.field("has_pool", &self.inner.pool.get().is_some())
.field("initialized", &self.inner.initialized.get().is_some())
.finish()
}
}
impl PostgresProjectionOffsetStore {
pub fn new(config: PostgresProjectionOffsetStoreConfig) -> ProjectionResult<Self> {
let sql = PostgresProjectionSql::new(&config)?;
if config.database_url.as_deref().is_none_or(str::is_empty) {
return Err(ProjectionError::invalid_config(
"postgres.database_url",
"database_url is required when no PgPool is supplied",
));
}
Ok(Self {
inner: Arc::new(PostgresProjectionOffsetStoreInner {
config,
sql,
pool: OnceCell::new(),
initialized: OnceCell::new(),
}),
})
}
pub fn from_pool(
pool: PgPool,
config: PostgresProjectionOffsetStoreConfig,
) -> ProjectionResult<Self> {
let sql = PostgresProjectionSql::new(&config)?;
Ok(Self {
inner: Arc::new(PostgresProjectionOffsetStoreInner {
config,
sql,
pool: OnceCell::new_with(Some(pool)),
initialized: OnceCell::new(),
}),
})
}
pub async fn connect(config: PostgresProjectionOffsetStoreConfig) -> ProjectionResult<Self> {
let store = Self::new(config)?;
store.initialize().await?;
Ok(store)
}
pub async fn initialize(&self) -> ProjectionResult<()> {
let pool = self.ready_pool_without_schema().await?;
self.inner
.initialized
.get_or_try_init(|| async {
bootstrap(pool, self.inner.sql.bootstrap_lock_key, &self.inner.sql.ddl).await
})
.await
.map(|_| ())
}
#[must_use]
pub fn pool(&self) -> Option<&PgPool> {
self.inner.pool.get()
}
#[must_use]
pub fn config(&self) -> &PostgresProjectionOffsetStoreConfig {
&self.inner.config
}
#[must_use]
pub fn schema_ddl(&self) -> String {
let mut ddl = self.inner.sql.ddl.join(";\n");
ddl.push(';');
ddl
}
async fn ready_pool_without_schema(&self) -> ProjectionResult<&PgPool> {
self.inner
.pool
.get_or_try_init(|| async {
let database_url = self.inner.config.database_url.as_deref().ok_or_else(|| {
ProjectionError::invalid_config(
"postgres.database_url",
"database_url is required when no PgPool is supplied",
)
})?;
pool_options(&self.inner.config)
.connect(database_url)
.await
.map_err(|error| postgres_error("connect PostgreSQL projection pool", error))
})
.await
}
async fn ready_pool(&self) -> ProjectionResult<&PgPool> {
self.initialize().await?;
self.inner.pool.get().ok_or_else(|| {
ProjectionError::OffsetStore(
"PostgreSQL pool unavailable after successful initialization".into(),
)
})
}
pub(crate) async fn begin_exactly_once(
&self,
projection_id: &ProjectionId,
generation: ProjectionGeneration,
expected_position: Option<&CursorPosition>,
) -> ProjectionResult<PostgresProjectionTx> {
projection_id.validate()?;
let mut transaction = self
.ready_pool()
.await?
.begin()
.await
.map_err(|error| postgres_error("begin exactly-once transaction", error))?;
self.lock_and_validate(
&mut transaction,
projection_id,
generation,
expected_position,
true,
)
.await?;
Ok(PostgresProjectionTx::new(transaction))
}
pub(crate) async fn commit_exactly_once(
&self,
mut transaction: PostgresProjectionTx,
projection_id: &ProjectionId,
generation: ProjectionGeneration,
cursor: &ProjectionCursor,
) -> ProjectionResult<()> {
let connection = transaction.connection_for_cursor()?;
self.lock_generation_and_validate(connection, projection_id, generation)
.await?;
self.write_cursor(connection, projection_id, generation, cursor)
.await?;
transaction.commit().await
}
#[doc(hidden)]
pub async fn save_with_crash_hook_for_test<F>(
&self,
projection_id: &ProjectionId,
generation: ProjectionGeneration,
expected_position: Option<&CursorPosition>,
cursor: ProjectionCursor,
crash_point: SaveCrashPoint,
reached_seam: F,
) -> ProjectionResult<()>
where
F: FnOnce(),
{
let mut transaction = self
.begin_exactly_once(projection_id, generation, expected_position)
.await?;
self.lock_generation_and_validate(
transaction.connection_for_cursor()?,
projection_id,
generation,
)
.await?;
self.write_cursor(
transaction.connection_for_cursor()?,
projection_id,
generation,
&cursor,
)
.await?;
match crash_point {
SaveCrashPoint::BeforeCommit => {
reached_seam();
std::future::pending::<ProjectionResult<()>>().await
}
SaveCrashPoint::AfterCommitBeforeAcknowledgement => {
transaction.commit().await?;
reached_seam();
std::future::pending::<ProjectionResult<()>>().await
}
}
}
async fn lock_and_validate(
&self,
transaction: &mut Transaction<'_, Postgres>,
projection_id: &ProjectionId,
attempted: ProjectionGeneration,
expected_position: Option<&CursorPosition>,
compare_position: bool,
) -> ProjectionResult<()> {
let row = sqlx::query(&self.inner.sql.lock)
.bind(projection_id.name())
.bind(projection_id.key())
.fetch_optional(&mut **transaction)
.await
.map_err(|error| postgres_error("lock PostgreSQL projection offset row", error))?;
let Some(row) = row else {
return Err(ProjectionError::Fenced {
projection_id: projection_id.clone(),
attempted_generation: attempted.as_u64(),
current_generation: 0,
});
};
let generation_row = sqlx::query(&self.inner.sql.load_generation)
.bind(projection_id.name())
.bind(projection_id.key())
.fetch_optional(&mut **transaction)
.await
.map_err(|error| {
postgres_error("load PostgreSQL projection owner generation", error)
})?;
let current = generation_row
.as_ref()
.map(decode_generation)
.transpose()?
.unwrap_or_default();
if attempted != current || attempted == ProjectionGeneration::default() {
return Err(ProjectionError::Fenced {
projection_id: projection_id.clone(),
attempted_generation: attempted.as_u64(),
current_generation: current.as_u64(),
});
}
let actual: Option<String> = row
.try_get("current_offset")
.map_err(|error| postgres_error("decode PostgreSQL current offset", error))?;
if compare_position && actual.as_deref() != expected_position.map(CursorPosition::as_str) {
return Err(ProjectionError::UnexpectedPosition {
projection_id: projection_id.clone(),
expected: expected_position.map(ToString::to_string),
actual,
});
}
Ok(())
}
async fn lock_generation_and_validate(
&self,
connection: &mut sqlx::PgConnection,
projection_id: &ProjectionId,
attempted: ProjectionGeneration,
) -> ProjectionResult<()> {
let row = sqlx::query(&self.inner.sql.lock_generation)
.bind(projection_id.name())
.bind(projection_id.key())
.fetch_optional(connection)
.await
.map_err(|error| {
postgres_error("lock PostgreSQL projection owner generation", error)
})?;
let current = row
.as_ref()
.map(decode_generation)
.transpose()?
.unwrap_or_default();
if attempted != current || attempted == ProjectionGeneration::default() {
return Err(ProjectionError::Fenced {
projection_id: projection_id.clone(),
attempted_generation: attempted.as_u64(),
current_generation: current.as_u64(),
});
}
Ok(())
}
async fn write_cursor(
&self,
connection: &mut sqlx::PgConnection,
projection_id: &ProjectionId,
generation: ProjectionGeneration,
cursor: &ProjectionCursor,
) -> ProjectionResult<()> {
let generation = encode_generation(generation)?;
sqlx::query(&self.inner.sql.update_cursor)
.bind(projection_id.name())
.bind(projection_id.key())
.bind(cursor.position().as_str())
.bind(cursor.provider_manifest().as_str())
.bind(generation)
.execute(&mut *connection)
.await
.map_err(|error| postgres_error("update PostgreSQL projection cursor", error))?;
self.delete_boundary(connection, projection_id).await?;
for event in cursor.boundary().consumed() {
let sequence_nr = i64::try_from(event.sequence_nr().as_u64()).map_err(|_| {
ProjectionError::CursorCodec(format!(
"boundary sequence number {} exceeds PostgreSQL BIGINT",
event.sequence_nr()
))
})?;
sqlx::query(&self.inner.sql.insert_boundary)
.bind(projection_id.name())
.bind(projection_id.key())
.bind(cursor.position().as_str())
.bind(event.persistence_id().id())
.bind(sequence_nr)
.execute(&mut *connection)
.await
.map_err(|error| {
postgres_error("insert PostgreSQL projection boundary member", error)
})?;
}
Ok(())
}
async fn delete_boundary(
&self,
connection: &mut sqlx::PgConnection,
projection_id: &ProjectionId,
) -> ProjectionResult<()> {
sqlx::query(&self.inner.sql.delete_boundary)
.bind(projection_id.name())
.bind(projection_id.key())
.execute(connection)
.await
.map_err(|error| postgres_error("delete PostgreSQL projection boundary", error))?;
Ok(())
}
}
#[async_trait::async_trait]
impl ProjectionOffsetStore for PostgresProjectionOffsetStore {
fn validate_exactly_once(&self) -> ProjectionResult<()> {
Ok(())
}
async fn claim(&self, projection_id: &ProjectionId) -> ProjectionResult<ProjectionGeneration> {
projection_id.validate()?;
let mut transaction = self
.ready_pool()
.await?
.begin()
.await
.map_err(|error| postgres_error("begin PostgreSQL projection claim", error))?;
let row = sqlx::query(&self.inner.sql.increment_generation)
.bind(projection_id.name())
.bind(projection_id.key())
.fetch_optional(&mut *transaction)
.await
.map_err(|error| postgres_error("increment PostgreSQL projection generation", error))?;
if let Some(row) = row {
let generation = decode_generation(&row)?;
transaction
.commit()
.await
.map_err(|error| postgres_error("commit PostgreSQL projection claim", error))?;
return Ok(generation);
}
let existing_owner = sqlx::query(&self.inner.sql.load_generation)
.bind(projection_id.name())
.bind(projection_id.key())
.fetch_optional(&mut *transaction)
.await
.map_err(|error| postgres_error("load PostgreSQL projection generation", error))?;
if existing_owner.is_some() {
return Err(ProjectionError::GenerationExhausted {
projection_id: projection_id.clone(),
});
}
sqlx::query(&self.inner.sql.insert_claim_row)
.bind(projection_id.name())
.bind(projection_id.key())
.execute(&mut *transaction)
.await
.map_err(|error| postgres_error("create PostgreSQL projection claim row", error))?;
sqlx::query(&self.inner.sql.insert_claim_owner)
.bind(projection_id.name())
.bind(projection_id.key())
.execute(&mut *transaction)
.await
.map_err(|error| postgres_error("create PostgreSQL projection owner row", error))?;
let row = sqlx::query(&self.inner.sql.increment_generation)
.bind(projection_id.name())
.bind(projection_id.key())
.fetch_optional(&mut *transaction)
.await
.map_err(|error| postgres_error("increment PostgreSQL projection generation", error))?;
let Some(row) = row else {
return Err(ProjectionError::GenerationExhausted {
projection_id: projection_id.clone(),
});
};
let generation = decode_generation(&row)?;
transaction
.commit()
.await
.map_err(|error| postgres_error("commit PostgreSQL projection claim", error))?;
Ok(generation)
}
async fn load(
&self,
projection_id: &ProjectionId,
) -> ProjectionResult<Option<ProjectionCursor>> {
projection_id.validate()?;
let rows = sqlx::query(&self.inner.sql.load)
.bind(projection_id.name())
.bind(projection_id.key())
.fetch_all(self.ready_pool().await?)
.await
.map_err(|error| postgres_error("load PostgreSQL projection cursor", error))?;
decode_cursor_rows(rows)
}
async fn save(
&self,
projection_id: &ProjectionId,
generation: ProjectionGeneration,
expected_position: Option<&CursorPosition>,
cursor: ProjectionCursor,
) -> ProjectionResult<()> {
let transaction = self
.begin_exactly_once(projection_id, generation, expected_position)
.await?;
self.commit_exactly_once(transaction, projection_id, generation, &cursor)
.await
}
async fn clear(
&self,
projection_id: &ProjectionId,
generation: ProjectionGeneration,
) -> ProjectionResult<()> {
projection_id.validate()?;
let mut transaction = self
.ready_pool()
.await?
.begin()
.await
.map_err(|error| postgres_error("begin PostgreSQL projection clear", error))?;
self.lock_and_validate(&mut transaction, projection_id, generation, None, false)
.await?;
self.lock_generation_and_validate(&mut transaction, projection_id, generation)
.await?;
let generation = encode_generation(generation)?;
sqlx::query(&self.inner.sql.clear_cursor)
.bind(projection_id.name())
.bind(projection_id.key())
.bind(generation)
.execute(&mut *transaction)
.await
.map_err(|error| postgres_error("clear PostgreSQL projection cursor", error))?;
self.delete_boundary(&mut transaction, projection_id)
.await?;
transaction
.commit()
.await
.map_err(|error| postgres_error("commit PostgreSQL projection clear", error))
}
async fn load_paused(&self, projection_id: &ProjectionId) -> ProjectionResult<bool> {
projection_id.validate()?;
let sql = format!(
"SELECT paused FROM {} WHERE projection_name = $1 AND projection_key = $2",
self.inner.sql.management
);
let row = sqlx::query(&sql)
.bind(projection_id.name())
.bind(projection_id.key())
.fetch_optional(self.ready_pool().await?)
.await
.map_err(|error| postgres_error("load PostgreSQL projection management", error))?;
row.map(|row| {
row.try_get("paused")
.map_err(|error| postgres_error("decode PostgreSQL paused flag", error))
})
.transpose()
.map(Option::unwrap_or_default)
}
async fn set_paused(&self, projection_id: &ProjectionId, paused: bool) -> ProjectionResult<()> {
projection_id.validate()?;
let sql = format!(
"INSERT INTO {} \
(projection_name, projection_key, paused, last_updated) \
VALUES ($1, $2, $3, \
floor(extract(epoch from clock_timestamp()) * 1000)::BIGINT) \
ON CONFLICT (projection_name, projection_key) DO UPDATE \
SET paused = EXCLUDED.paused, last_updated = EXCLUDED.last_updated",
self.inner.sql.management
);
sqlx::query(&sql)
.bind(projection_id.name())
.bind(projection_id.key())
.bind(paused)
.execute(self.ready_pool().await?)
.await
.map_err(|error| postgres_error("save PostgreSQL projection management", error))?;
Ok(())
}
fn postgres_store(&self) -> Option<&PostgresProjectionOffsetStore> {
Some(self)
}
}
fn decode_cursor_rows(rows: Vec<PgRow>) -> ProjectionResult<Option<ProjectionCursor>> {
let Some(first) = rows.first() else {
return Ok(None);
};
let position: Option<String> = first
.try_get("current_offset")
.map_err(|error| postgres_error("decode PostgreSQL projection position", error))?;
let manifest: Option<String> = first
.try_get("manifest")
.map_err(|error| postgres_error("decode PostgreSQL provider manifest", error))?;
let (position, manifest) = match (position, manifest) {
(Some(position), Some(manifest)) => (position, manifest),
(None, None) => {
let mut has_boundary_member = false;
for row in &rows {
has_boundary_member |= boundary_row_has_member(row)?;
}
if has_boundary_member {
return Err(ProjectionError::CursorCodec(
"PostgreSQL cursor boundary exists without a main cursor".into(),
));
}
return Ok(None);
}
_ => {
return Err(ProjectionError::CursorCodec(
"PostgreSQL cursor has only one of position and manifest".into(),
));
}
};
let mut consumed = Vec::new();
for row in &rows {
let boundary_position: Option<String> = row
.try_get("boundary_offset")
.map_err(|error| postgres_error("decode PostgreSQL boundary position", error))?;
let persistence_id: Option<String> = row
.try_get("persistence_id")
.map_err(|error| postgres_error("decode PostgreSQL boundary persistence id", error))?;
let sequence_nr: Option<i64> = row
.try_get("seq_nr")
.map_err(|error| postgres_error("decode PostgreSQL boundary sequence", error))?;
match (boundary_position, persistence_id, sequence_nr) {
(None, None, None) => {}
(Some(boundary_position), Some(persistence_id), Some(sequence_nr)) => {
if boundary_position != position {
return Err(ProjectionError::CursorCodec(format!(
"PostgreSQL boundary position {boundary_position:?} disagrees with \
main cursor {position:?}"
)));
}
let sequence_nr = u64::try_from(sequence_nr).map_err(|_| {
ProjectionError::CursorCodec(format!(
"PostgreSQL boundary has negative sequence number {sequence_nr}"
))
})?;
let persistence_id = PersistenceId::from_unique(persistence_id)
.map_err(|error| ProjectionError::CursorCodec(error.to_string()))?;
consumed.push(BoundaryEvent::new(
persistence_id,
SequenceNr::new(sequence_nr),
));
}
_ => {
return Err(ProjectionError::CursorCodec(
"PostgreSQL boundary row is partially null".into(),
));
}
}
}
Ok(Some(ProjectionCursor::new(
ProviderManifest::new(manifest)
.map_err(|error| ProjectionError::CursorCodec(error.to_string()))?,
DeduplicationBoundary::with_consumed(position, consumed),
)))
}
fn boundary_row_has_member(row: &PgRow) -> ProjectionResult<bool> {
let persistence_id: Option<String> = row
.try_get("persistence_id")
.map_err(|error| postgres_error("decode PostgreSQL boundary persistence id", error))?;
Ok(persistence_id.is_some())
}
fn decode_generation(row: &PgRow) -> ProjectionResult<ProjectionGeneration> {
let generation: i64 = row
.try_get("generation")
.map_err(|error| postgres_error("decode PostgreSQL projection generation", error))?;
let generation = u64::try_from(generation).map_err(|_| {
ProjectionError::OffsetStore(format!(
"PostgreSQL projection generation is negative: {generation}"
))
})?;
Ok(ProjectionGeneration::new(generation))
}
fn encode_generation(generation: ProjectionGeneration) -> ProjectionResult<i64> {
i64::try_from(generation.as_u64()).map_err(|_| {
ProjectionError::OffsetStore(format!(
"PostgreSQL projection generation {} exceeds BIGINT",
generation.as_u64()
))
})
}
fn pool_options(config: &PostgresProjectionOffsetStoreConfig) -> 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, lock_key: i64, ddl: &[String]) -> ProjectionResult<()> {
let mut transaction = pool
.begin()
.await
.map_err(|error| postgres_error("begin PostgreSQL projection schema bootstrap", error))?;
sqlx::query("SELECT pg_advisory_xact_lock($1)")
.bind(lock_key)
.execute(&mut *transaction)
.await
.map_err(|error| {
postgres_error(
"lock PostgreSQL projection schema bootstrap namespace",
error,
)
})?;
for statement in ddl {
sqlx::query(statement)
.execute(&mut *transaction)
.await
.map_err(|error| {
postgres_error("execute PostgreSQL projection schema bootstrap", error)
})?;
}
transaction
.commit()
.await
.map_err(|error| postgres_error("commit PostgreSQL projection schema bootstrap", error))
}
fn bootstrap_lock_key(config: &PostgresProjectionOffsetStoreConfig) -> i64 {
const FNV_OFFSET_BASIS: u64 = 0xcbf2_9ce4_8422_2325;
const FNV_PRIME: u64 = 0x0000_0100_0000_01b3;
let mut hash = FNV_OFFSET_BASIS;
for component in [
"datum-projection-postgres-bootstrap-v1",
config.schema.as_str(),
config.tables.offset_store.as_str(),
config.tables.timestamp_offset_store.as_str(),
config.tables.management.as_str(),
] {
for byte in component.bytes().chain(std::iter::once(0xff)) {
hash ^= u64::from(byte);
hash = hash.wrapping_mul(FNV_PRIME);
}
}
hash as i64
}
fn validate_config(config: &PostgresProjectionOffsetStoreConfig) -> ProjectionResult<()> {
validate_identifier("schema", &config.schema, 63)?;
validate_identifier(
"offset table",
&config.tables.offset_store,
MAX_TABLE_IDENTIFIER_BYTES,
)?;
validate_identifier(
"timestamp-offset table",
&config.tables.timestamp_offset_store,
MAX_TABLE_IDENTIFIER_BYTES,
)?;
validate_identifier(
"management table",
&config.tables.management,
MAX_TABLE_IDENTIFIER_BYTES,
)?;
if config.max_connections == 0 {
return Err(ProjectionError::invalid_config(
"postgres.max_connections",
"max_connections must be greater than zero",
));
}
if config.min_connections > config.max_connections {
return Err(ProjectionError::invalid_config(
"postgres.min_connections",
format!(
"min_connections {} exceeds max_connections {}",
config.min_connections, config.max_connections
),
));
}
if config.acquire_timeout.is_zero() {
return Err(ProjectionError::invalid_config(
"postgres.acquire_timeout",
"acquire_timeout must be greater than zero",
));
}
Ok(())
}
fn validate_identifier(name: &'static str, value: &str, max_bytes: usize) -> ProjectionResult<()> {
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(ProjectionError::invalid_config(
name,
format!(
"invalid PostgreSQL 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 postgres_error(context: &str, error: sqlx::Error) -> ProjectionError {
ProjectionError::OffsetStore(format!("{context}: {error}"))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn config_is_lazy_redacts_url_and_uses_akka_shaped_tables() {
let config = PostgresProjectionOffsetStoreConfig::new(
"postgres://datum:secret@example.invalid/datum",
);
let store = PostgresProjectionOffsetStore::new(config.clone())
.expect("default PostgreSQL projection config is valid");
assert!(store.pool().is_none());
assert!(!format!("{config:?}").contains("secret"));
assert_eq!(
config.tables,
PostgresProjectionTableNames {
offset_store: "datum_projection_offset_store".into(),
timestamp_offset_store: "datum_projection_timestamp_offset_store".into(),
management: "datum_projection_management".into(),
}
);
let ddl = store.schema_ddl();
assert!(ddl.contains("current_offset TEXT"));
assert!(ddl.contains("generation BIGINT"));
assert!(ddl.contains("persistence_id TEXT"));
assert!(ddl.contains("paused BOOLEAN"));
}
}