PgReplicationOrigin

Namespace: Ankus

Assembly: Ankus.Runtime.dll

Manages PostgreSQL’s replication origins, which record how far a subscriber has applied each source’s changes and mark the commits it makes on that source’s behalf.

public static class PgReplicationOrigin

A worker that applies one source’s changes sets up a session origin, then, in each transaction, records the source’s commit position and time before committing. PostgreSQL stores that position with the commit, so the origin’s progress survives a crash, and logical decoding can filter changes by the origin that made them. An origin’s numeric ID is what CommitOrigin reports. Each operation makes the checks its pg_replication_origin_* SQL function makes, except privileges: an extension decides who may call the functions that use these operations. Creating, finding, dropping and advancing origins read or change the catalog, so they need a transaction.

Inheritance: object

Methods

Advance(ushort, PgLsn, PgLsn, bool, bool)

Moves an origin’s progress, as pg_replication_origin_advance does.

public static void Advance(ushort origin, PgLsn remoteCommit, PgLsn localCommit = default, bool goBackward = false, bool walLog = true)

Parameters:

origin — ushort

The origin’s ID.

remoteCommit — PgLsn

The source commit position the origin has applied.

localCommit — PgLsn

The local commit that applied it, or Invalid.

goBackward — bool

Whether the progress may move to an earlier position.

walLog — bool

Whether to write the change to the write-ahead log so it survives a crash.

Exceptions:

• PgException: The origin does not exist, or there is no transaction.

Without goBackward, an earlier position leaves the progress where it is. The SQL function always allows moving backward.

Create(string)

Creates an origin in the current transaction.

public static ushort Create(string name)

Parameters:

name — string

The origin’s name.

Returns: ushort

The new origin’s ID.

Exceptions:

• PgException: An origin has the name, the name is reserved, or there is no transaction.

Names starting with pg_ are reserved, and from PostgreSQL 16 so are any and none.

Drop(string, bool)

Drops an origin.

public static void Drop(string name, bool missingOk = false)

Parameters:

name — string

The origin’s name.

missingOk — bool

Whether a missing origin is ignored rather than an error.

Exceptions:

• PgException: The origin does not exist, or a session is using it.

Find(string)

Looks up an origin by name.

public static ushort? Find(string name)

Parameters:

name — string

The origin’s name.

Returns: ushort?

The origin’s ID, or null when no origin has the name.

GetProgress(ushort, bool)

Gets how far an origin has applied.

public static PgLsn GetProgress(ushort origin, bool flush = false)

Parameters:

origin — ushort

The origin’s ID.

flush — bool

Whether to wait until the position is durable on disk.

Returns: PgLsn

The last source commit position applied, or Invalid when there is none.

GetSessionProgress(bool)

Gets how far the session’s origin has applied.

public static PgLsn GetSessionProgress(bool flush = false)

Parameters:

flush — bool

Whether to wait until the position is durable on disk.

Returns: PgLsn

The last source commit position applied.

Exceptions:

• PgException: The session has no origin.

ResetSession()

Releases the session’s origin.

public static void ResetSession()

SetTransactionOrigin(PgLsn, PgTimestampTz?)

Records the source’s commit position and time for the current transaction, which PostgreSQL stores with its commit and uses to advance the session origin’s progress.

public static void SetTransactionOrigin(PgLsn remoteCommit, PgTimestampTz? commitTime)

Parameters:

remoteCommit — PgLsn

The position of the source’s commit.

commitTime — PgTimestampTz?

The time the source committed, or null to record the local commit time.

Exceptions:

• PgException: The session has no origin, or there is no transaction.

PostgreSQL records the time as the commit timestamp in place of the local time. It keeps both values for the session’s later commits until they are set again or the session is reset, so an apply worker sets them in every transaction it applies. PostgreSQL treats a time of zero, the start of 2000 UTC, as no time.

SetupSession(ushort)

Makes an origin this session’s, so its commits are marked with it and advance its progress.

public static void SetupSession(ushort origin)

Parameters:

origin — ushort

The origin’s ID.

Exceptions:

• PgException: The session already has an origin, or another session uses this one.

Properties

SessionOrigin

Gets the session’s origin, or zero when none is set up.

public static ushort SessionOrigin { get; }

Value: ushort