Table of Contents

Class PostgresCdcStateStore

Namespace
Excalibur.Cdc.Postgres
Assembly
Excalibur.Cdc.Postgres.dll

Postgres implementation of IPostgresCdcStateStore using a state table.

public sealed class PostgresCdcStateStore : IPostgresCdcStateStore, ICdcStateStore, IAsyncDisposable, IDisposable
Inheritance
PostgresCdcStateStore
Implements
Inherited Members

Remarks

This store is global infrastructure, not tenant-partitioned, and that is deliberate. A row here records how far a replication slot has been consumed. A replication slot and its LSN are properties of the database, not of any tenant, so partitioning a checkpoint per tenant would not isolate anything - it would break the mechanism, because a slot advanced by one partition is advanced for every other reader of that slot. The consequences of that election are named here rather than left implicit:

  1. GetAllPositionsAsync(CancellationToken) enumerates every consumer's checkpoint - that is the method's documented purpose (operational visibility into consumer progress), so it is scoped to the store, not to the caller. Any component holding this store therefore observes the existence, identity and replication progress of every other consumer sharing the table. In a shared deployment, hand this store only to components entitled to that view, or give each tenant its own state table via TableName.
  2. A consumer's identity on the ICdcStateStore path is its consumerId alone. Two consumers configured with the same id share one checkpoint and each will advance past changes the other has not read. Distinct consumers require distinct ids; the store cannot detect a collision because both callers are, by construction, indistinguishable to it.
  3. ClearStateAsync(string, CancellationToken) removes every row for a processor - all slots and all per-table state - which is its documented contract ("clears all state for a processor"), not an oversight. It is not a per-slot reset; to reset one generic checkpoint use DeletePositionAsync(string, CancellationToken).

The generic ICdcStateStore checkpoint and the typed per-slot positions share one table and are separated by a reserved discriminator, described on the discriminator constant itself.

Constructors

PostgresCdcStateStore(string, IOptions<PostgresCdcStateStoreOptions>)

Initializes a new instance of the PostgresCdcStateStore class with options.

public PostgresCdcStateStore(string connectionString, IOptions<PostgresCdcStateStoreOptions> options)

Parameters

connectionString string
options IOptions<PostgresCdcStateStoreOptions>

Methods

ClearStateAsync(string, CancellationToken)

Clears all state for a processor.

public Task ClearStateAsync(string processorId, CancellationToken cancellationToken)

Parameters

processorId string
cancellationToken CancellationToken

Returns

Task

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

DisposeAsync()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.

public ValueTask DisposeAsync()

Returns

ValueTask

A task that represents the asynchronous dispose operation.

GetAllStatesAsync(string, CancellationToken)

Gets detailed state information for all tracked tables.

public Task<IReadOnlyList<PostgresCdcStateEntry>> GetAllStatesAsync(string processorId, CancellationToken cancellationToken)

Parameters

processorId string
cancellationToken CancellationToken

Returns

Task<IReadOnlyList<PostgresCdcStateEntry>>

GetLastPositionAsync(string, string, CancellationToken)

Gets the last processed LSN position for a processor.

public Task<PostgresCdcPosition> GetLastPositionAsync(string processorId, string slotName, CancellationToken cancellationToken)

Parameters

processorId string
slotName string
cancellationToken CancellationToken

Returns

Task<PostgresCdcPosition>

SavePositionAsync(string, string, PostgresCdcPosition, CancellationToken)

Saves the current LSN position for a processor, refusing to move it backwards.

public Task<CdcPositionSaveOutcome> SavePositionAsync(string processorId, string slotName, PostgresCdcPosition position, CancellationToken cancellationToken)

Parameters

processorId string
slotName string
position PostgresCdcPosition
cancellationToken CancellationToken

Returns

Task<CdcPositionSaveOutcome>

Advanced when the stored LSN now is position, or RefusedAsStale when the stored LSN was already at or beyond it and nothing was written. The guard makes a regression a no-op, and this is how the caller learns that is what happened.

SaveStateAsync(PostgresCdcStateEntry, CancellationToken)

Saves detailed state for a specific table.

public Task SaveStateAsync(PostgresCdcStateEntry entry, CancellationToken cancellationToken)

Parameters

entry PostgresCdcStateEntry
cancellationToken CancellationToken

Returns

Task