Table of Contents

Class PostgresCdcProcessor

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

Postgres CDC processor using logical replication with pgoutput protocol.

public sealed class PostgresCdcProcessor : IPostgresCdcProcessor, ICdcStreamProcessor<PostgresDataChangeEvent, PostgresCdcPosition>, ICdcProcessor<PostgresDataChangeEvent>, IAsyncDisposable, IDisposable
Inheritance
PostgresCdcProcessor
Implements
Inherited Members

Remarks

Where processing resumes. Both StartAsync(Func<PostgresDataChangeEvent, CancellationToken, Task>, CancellationToken) and ProcessBatchAsync(Func<PostgresDataChangeEvent, CancellationToken, Task>, CancellationToken) resume from the replication slot's confirmed position, which PostgreSQL records durably alongside the write-ahead log. The slot is acknowledged only after the changes of a transaction have been handed to your handler, so a restart never resumes past a change that was not delivered. A change may be delivered again after a restart, so handlers must be idempotent.

The position saved to the CDC state store is for observation, reported by GetCurrentPositionAsync(CancellationToken) and useful for monitoring. It does not decide where processing resumes, so editing or rewinding it does not cause a replay. To replay, reposition or recreate the replication slot.

Constructors

PostgresCdcProcessor(IOptions<PostgresCdcOptions>, IPostgresCdcStateStore, ILogger<PostgresCdcProcessor>, IOptions<CdcFatalErrorOptions<PostgresDataChangeEvent>>?, IMessageFailureClassifier?, TimeProvider?, CdcHealthState?)

Initializes a new instance of the PostgresCdcProcessor class.

public PostgresCdcProcessor(IOptions<PostgresCdcOptions> options, IPostgresCdcStateStore stateStore, ILogger<PostgresCdcProcessor> logger, IOptions<CdcFatalErrorOptions<PostgresDataChangeEvent>>? fatalErrorOptions = null, IMessageFailureClassifier? failureClassifier = null, TimeProvider? timeProvider = null, CdcHealthState? healthState = null)

Parameters

options IOptions<PostgresCdcOptions>

The CDC options.

stateStore IPostgresCdcStateStore

The state store for position tracking.

logger ILogger<PostgresCdcProcessor>

The logger.

fatalErrorOptions IOptions<CdcFatalErrorOptions<PostgresDataChangeEvent>>

Optional fatal-error handling. When omitted (or its handler is null), a fatal error rethrows and stops the processor (fail-loud — never an infinite silent reconnect loop).

failureClassifier IMessageFailureClassifier

Optional shared classifier deciding whether a processing error is fatal (non-retryable) or transient. When omitted, a conservative built-in fallback is used (only definitively non-retryable faults are fatal; everything else is retried with backoff).

timeProvider TimeProvider

The clock the reconnect backoff waits on and measures stable connections with; defaults to the system clock.

healthState CdcHealthState

Where consecutive reconnect failures are reported for the CDC health check, when one is registered.

Methods

ConfirmPositionAsync(PostgresCdcPosition, CancellationToken)

Confirms that all events up to the specified position have been processed.

public Task ConfirmPositionAsync(PostgresCdcPosition position, CancellationToken cancellationToken)

Parameters

position PostgresCdcPosition

The position to confirm.

cancellationToken CancellationToken

A token to observe for cancellation requests.

Returns

Task

A task representing the asynchronous operation.

Remarks

This persists the position to the state store. On restart, processing will resume from this confirmed position. When using StartAsync(Func<TEvent, CancellationToken, Task>, CancellationToken), position confirmation is typically automatic. Use this method for manual control in batch scenarios.

Dispose()

Marks this processor as disposed.

public void Dispose()

Remarks

This method cannot release the underlying Postgres logical replication connection. Npgsql's replication connection exposes only asynchronous disposal (it does not implement IDisposable), so a synchronous using block leaves the connection — and the replication slot it holds open on the server — alive. An unreleased slot accumulates WAL until the connection is eventually closed by the server or the process exits.

Always dispose this processor with await using (see DisposeAsync()) so the connection and its replication slot are released deterministically. This method exists only to satisfy IDisposable; when it detects a live replication connection it logs an error identifying the leaked slot instead of leaking it silently.

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.

GetCurrentPositionAsync(CancellationToken)

Gets the current processing position.

public Task<PostgresCdcPosition> GetCurrentPositionAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

A token to observe for cancellation requests.

Returns

Task<PostgresCdcPosition>

The current position, or a beginning position if none exists.

ProcessBatchAsync(Func<PostgresDataChangeEvent, CancellationToken, Task>, CancellationToken)

Processes a single batch of CDC changes and returns.

public Task<int> ProcessBatchAsync(Func<PostgresDataChangeEvent, CancellationToken, Task> eventHandler, CancellationToken cancellationToken)

Parameters

eventHandler Func<PostgresDataChangeEvent, CancellationToken, Task>

A delegate that handles each change event.

cancellationToken CancellationToken

A token to observe for cancellation requests.

Returns

Task<int>

The number of events processed in this batch.

Remarks

Use this method for serverless scenarios or when you need explicit control over batch processing cadence.

Delivery semantics are provider-specific and this contract does not strengthen them. Providers differ in whether a batch that ends abnormally — a handler that throws, a cancelled token, a process that stops — redelivers the changes it had already read, and in whether a durable position is advanced on this path at all. Consult the documentation of the provider you register before relying on redelivery, and prefer ICdcStreamProcessor<TEvent, TPosition> where the provider offers it: its position management is explicit, whereas this method's is not part of the shared contract.

Consumer obligation: handlers MUST be idempotent. A provider that does redeliver does so without coordinating with the handler, so a handler that succeeded before a batch failed can be called again with the same change.

A return of zero does not necessarily mean "no changes were available". A provider that holds per-stream state MAY serve overlapping calls single-flight: while one call is processing, a second returns 0 immediately without touching the stream, and the work is picked up by a later invocation. This is specified behaviour rather than a failure — overlapping invocations are ordinary for the documented timer-trigger usage, and refusing them with an exception would surface as an unobserved task exception in most hosts. A provider that does this MUST log each skip so it is distinguishable from a stalled processor. Treat the return value as "changes processed by THIS call", never as "changes outstanding".

StartAsync(Func<PostgresDataChangeEvent, CancellationToken, Task>, CancellationToken)

Starts continuous CDC processing until cancellation.

public Task StartAsync(Func<PostgresDataChangeEvent, CancellationToken, Task> eventHandler, CancellationToken cancellationToken)

Parameters

eventHandler Func<PostgresDataChangeEvent, CancellationToken, Task>

A delegate that handles each change event.

cancellationToken CancellationToken

A token to observe for cancellation requests.

Returns

Task

A task that completes when processing stops due to cancellation.

Remarks

This method runs continuously until cancelled. It automatically handles connection management, reconnection, and position tracking. Position is confirmed after each successfully processed event. Use ProcessBatchAsync(Func<TEvent, CancellationToken, Task>, CancellationToken) for manual batch control.