NpgsqlCdc 0.0.3-preview

NpgsqlCdc

NpgsqlCdc is a thin PostgreSQL logical replication CDC library for .NET.

Package ID:

• NpgsqlCdc

Primary namespace:

• NpgsqlCdc

The goal is to stay close to projects like MySqlCdc:

• one package
• one database
• low-level access to the replication stream
• no required ASP.NET Core integration
• no required checkpoint persistence

Minimal usage

using NpgsqlCdc;

var options = new NpgsqlCdcOptions
{
    ConnectionString = "Host=localhost;Database=postgres;Username=postgres;Password=postgres",
    SlotName = "npgsqlcdc_slot",
    CreateSlotIfNotExists = true
};

options.AddPublication("npgsqlcdc_publication");

var client = new NpgsqlCdcClient(options);

await foreach (var @event in client.Replicate())
{
    Console.WriteLine($"{@event.Kind} @ {@event.WalEnd}");
}

NpgsqlCdcClient tracks a safe resume LSN in memory. After successful processing you can read it from client.State.ResumeLsn and persist it anywhere you want.

var checkpoint = client.State.ResumeLsn;

var resumedClient = new NpgsqlCdcClient(options);
resumedClient.SetResumeLsn(checkpoint);

What the library includes

• NpgsqlCdcClient for streaming pgoutput
• NpgsqlCdcOptions for replication setup
• NpgsqlReplicationEvent models for relation, insert, update, delete, truncate, begin, and commit
• NpgsqlTransaction / ReplicateTransactions() if you prefer committed transaction batches
• optional helpers for publication setup, replica identity, and slot flush LSN

What the library does not require

• ASP.NET Core
• hosted services
• Redis
• PostgreSQL cache tables
• a built-in sink abstraction

Checkpoint persistence is application-owned. The library keeps a safe resume LSN in memory through client.State.ResumeLsn, and your application decides whether to persist it in a file, a database, Redis, or not at all.

Notes

• The library is focused on row-level PostgreSQL CDC through logical replication and pgoutput.
• Supported data-change events are INSERT, UPDATE, DELETE, and TRUNCATE.
• Transaction boundary events and relation metadata are exposed so consumers can group changes and interpret row payloads.
• DDL CDC is intentionally out of scope. CREATE TABLE, ALTER TABLE, DROP TABLE, and other DDL statements are not emitted as DDL events by this library.
• PostgreSQL UPDATE and DELETE payloads depend on REPLICA IDENTITY.
• If you need the full old row image for updates or deletes, configure the table with REPLICA IDENTITY FULL.
• During an open transaction, resume checkpoint stays at the transaction start to reduce partial-loss risk.
• Checkpoint persistence is not built in. Persist client.State.ResumeLsn in your application if you need durable resume.

Samples

• Console sample: samples/NpgsqlCdc.Sample/README.md
• Minimal ASP.NET Core host sample: samples/Npgsql.Web/README.md