Table of Contents

Class PostgresCursorMapStore

Namespace
Excalibur.EventSourcing.Postgres
Assembly
Excalibur.EventSourcing.Postgres.dll

PostgreSQL implementation of ICursorMapStore using a key-value table.

public sealed class PostgresCursorMapStore : ICursorMapStore
Inheritance
PostgresCursorMapStore
Implements
Inherited Members

Remarks

Uses a projection_cursor_maps table with columns (projection_name, stream_id, position). Saves are atomic via INSERT ... ON CONFLICT ... DO UPDATE.

This store issues no DDL at run time. Provision the table from the 008_CreateCursorMapSchema.sql script shipped in this package's scripts folder before the first checkpoint; without it every save fails with 42P01: relation "projection_cursor_maps" does not exist.

Table DDL — run the script rather than transcribing this. The primary key is what makes the upsert legal as well as what keeps cursors per-tenant: the save path says ON CONFLICT (tenant_id, projection_name, stream_id), and PostgreSQL requires a matching unique constraint or it rejects every save with 42P10.

CREATE TABLE projection_cursor_maps (
    tenant_id VARCHAR(64) NOT NULL,
    projection_name VARCHAR(256) NOT NULL,
    stream_id VARCHAR(256) NOT NULL,
    position BIGINT NOT NULL,
    CONSTRAINT pk_projection_cursor_maps PRIMARY KEY (tenant_id, projection_name, stream_id)
);

Constructors

PostgresCursorMapStore(NpgsqlDataSource, ILogger<PostgresCursorMapStore>, ITenantContext)

Initializes a new instance with an Npgsql.NpgsqlDataSource and an ambient tenant context.

public PostgresCursorMapStore(NpgsqlDataSource dataSource, ILogger<PostgresCursorMapStore> logger, ITenantContext tenantContext)

Parameters

dataSource NpgsqlDataSource

The Npgsql data source for connection management.

logger ILogger<PostgresCursorMapStore>

The logger instance.

tenantContext ITenantContext

The ambient tenant context. Required: this store partitions rows by tenant, and it resolves that partition from here, so there is no state in which the partition is undecided. A single-tenant host receives the framework default context and operates as the one canonical tenant.

PostgresCursorMapStore(string, ILogger<PostgresCursorMapStore>, ITenantContext)

Initializes a new instance with a connection string and an ambient tenant context.

public PostgresCursorMapStore(string connectionString, ILogger<PostgresCursorMapStore> logger, ITenantContext tenantContext)

Parameters

connectionString string

The PostgreSQL connection string.

logger ILogger<PostgresCursorMapStore>

The logger instance.

tenantContext ITenantContext

The ambient tenant context. Required: this store partitions rows by tenant, and it resolves that partition from here, so there is no state in which the partition is undecided. A single-tenant host receives the framework default context and operates as the one canonical tenant.

Methods

GetCursorMapAsync(string, CancellationToken)

Gets the cursor map for a named projection.

public Task<IReadOnlyDictionary<string, long>> GetCursorMapAsync(string projectionName, CancellationToken cancellationToken)

Parameters

projectionName string

The unique projection identifier.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<IReadOnlyDictionary<string, long>>

A dictionary mapping stream identifiers to their last-processed positions. Returns an empty dictionary if no cursor map exists.

ResetCursorMapAsync(string, CancellationToken)

Resets the cursor map for a named projection, removing all stored positions. Used during projection rebuild to restart from the beginning.

public Task ResetCursorMapAsync(string projectionName, CancellationToken cancellationToken)

Parameters

projectionName string

The unique projection identifier.

cancellationToken CancellationToken

Cancellation token.

Returns

Task

SaveCursorMapAsync(string, IReadOnlyDictionary<string, long>, CancellationToken)

Saves the cursor map for a named projection atomically. All stream positions are updated together or not at all.

public Task SaveCursorMapAsync(string projectionName, IReadOnlyDictionary<string, long> cursorMap, CancellationToken cancellationToken)

Parameters

projectionName string

The unique projection identifier.

cursorMap IReadOnlyDictionary<string, long>

The stream positions to persist.

cancellationToken CancellationToken

Cancellation token.

Returns

Task