Class ReplicationConnection

Namespace

Npgsql.Replication

Assembly

Npgsql.dll

Defines the core behavior of replication connections and provides the base class for LogicalReplicationConnection and PhysicalReplicationConnection.

public abstract class ReplicationConnection : IAsyncDisposable

Inheritance

object

ReplicationConnection

Implements

IAsyncDisposable

Derived

LogicalReplicationConnection

PhysicalReplicationConnection

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Properties

CommandTimeout

Gets or sets the wait time before terminating the attempt to execute a command and generating an error.

public TimeSpan CommandTimeout { get; set; }

Property Value

TimeSpan

The time to wait for the command to execute. The default value is 30 seconds.

ConnectionString

Gets or sets the string used to connect to a PostgreSQL database. See the manual for details.

public string ConnectionString { get; set; }

Property Value

string

The connection string that includes the server name, the database name, and other parameters needed to establish the initial connection. The default value is an empty string.

Remarks

Since replication connections are a special kind of connection, Pooling, Enlist, Multiplexing and KeepAlive are always disabled no matter what you set them to in your connection string.

Encoding

The client encoding for the connection This can only be called when there is an active connection.

public Encoding Encoding { get; }

Property Value

Encoding

LastAppliedLsn

The location of the last WAL byte + 1 applied (e. g. written to disk) in the standby.

public NpgsqlLogSequenceNumber LastAppliedLsn { get; set; }

Property Value

NpgsqlLogSequenceNumber

LastFlushedLsn

The location of the last WAL byte + 1 flushed to disk in the standby.

public NpgsqlLogSequenceNumber LastFlushedLsn { get; set; }

Property Value

NpgsqlLogSequenceNumber

LastReceivedLsn

The location of the last WAL byte + 1 received in the standby.

public NpgsqlLogSequenceNumber LastReceivedLsn { get; }

Property Value

NpgsqlLogSequenceNumber

PostgreSqlVersion

The version of the PostgreSQL server we're connected to.

This can only be called when the connection is open.

In case of a development or pre-release version this field will contain the version of the next version to be released from this branch.

public Version PostgreSqlVersion { get; }

Property Value

Version

ProcessID

Process id of backend server. This can only be called when there is an active connection.

public int ProcessID { get; }

Property Value

int

ServerVersion

The PostgreSQL server version as returned by the server_version option. This can only be called when the connection is open.

public string ServerVersion { get; }

Property Value

string

WalReceiverStatusInterval

Send replies at least this often. Timeout.InfiniteTimeSpan disables automated replies.

public TimeSpan WalReceiverStatusInterval { get; set; }

Property Value

TimeSpan

WalReceiverTimeout

Time that receiver waits for communication from master. Timeout.InfiniteTimeSpan disables the timeout.

public TimeSpan WalReceiverTimeout { get; set; }

Property Value

TimeSpan

Methods

DisposeAsync()

Closes the replication connection and performs tasks associated with freeing, releasing, or resetting its unmanaged resources asynchronously.

public ValueTask DisposeAsync()

Returns

ValueTask

A task that represents the asynchronous dispose operation.

DropReplicationSlot(string, bool, CancellationToken)

Drops a replication slot, freeing any reserved server-side resources. If the slot is a logical slot that was created in a database other than the database the walsender is connected to, this command fails.

public Task DropReplicationSlot(string slotName, bool wait = false, CancellationToken cancellationToken = default)

Parameters

slotName string

The name of the slot to drop.

wait bool

true causes the command to wait until the slot becomes inactive if it currently is active instead of the default behavior of raising an error.

cancellationToken CancellationToken

An optional token to cancel the asynchronous operation. The default value is None.

Returns

Task

A task representing the asynchronous drop operation.

IdentifySystem(CancellationToken)

Requests the server to identify itself.

public Task<ReplicationSystemIdentification> IdentifySystem(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

An optional token to cancel the asynchronous operation. The default value is None.

Returns

Task<ReplicationSystemIdentification>

A ReplicationSystemIdentification containing information about the system we are connected to.

Open(CancellationToken)

Opens a database replication connection with the property settings specified by the ConnectionString.

public Task Open(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

An optional token to cancel the asynchronous operation. The default value is None.

Returns

Task

A task representing the asynchronous open operation.

SendStatusUpdate(CancellationToken)

Sends a forced status update to PostgreSQL with the current WAL tracking information.

public Task SendStatusUpdate(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

Task

A Task representing the sending of the status update (and not any PostgreSQL response).

Exceptions

InvalidOperationException

The connection currently isn't streaming

SetReplicationStatus(NpgsqlLogSequenceNumber)

Sets the current status of the replication as it is interpreted by the consuming client. The value supplied in will be sent to the server via LastAppliedLsn and LastFlushedLsn with the next status update.

A status update which will happen upon server request, upon expiration of WalReceiverStatusInterval our upon an enforced status update via SendStatusUpdate(CancellationToken), whichever happens first. If you want the value you set here to be pushed to the server immediately (e. g. in synchronous replication scenarios), call SendStatusUpdate(CancellationToken) after calling this method.

public void SetReplicationStatus(NpgsqlLogSequenceNumber lastAppliedAndFlushedLsn)

Parameters

lastAppliedAndFlushedLsn NpgsqlLogSequenceNumber

The location of the last WAL byte + 1 applied (e. g. processed or written to disk) and flushed to disk in the standby.

Remarks

This is a convenience method setting both LastAppliedLsn and LastFlushedLsn in one operation. You can use it if your application processes replication messages in a way that doesn't care about the difference between writing a message and flushing it to a permanent storage medium.

Show(string, CancellationToken)

Requests the server to send the current setting of a run-time parameter. This is similar to the SQL command SHOW.

public Task<string> Show(string parameterName, CancellationToken cancellationToken = default)

Parameters

parameterName string

The name of a run-time parameter. Available parameters are documented in https://www.postgresql.org/docs/current/runtime-config.html.

cancellationToken CancellationToken

An optional token to cancel the asynchronous operation. The default value is None.

Returns

Task<string>

The current setting of the run-time parameter specified in parameterName as string.

TimelineHistory(uint, CancellationToken)

Requests the server to send over the timeline history file for timeline tli.

public Task<TimelineHistoryFile> TimelineHistory(uint tli, CancellationToken cancellationToken = default)

Parameters

tli uint

The timeline for which the history file should be sent.

cancellationToken CancellationToken

An optional token to cancel the asynchronous operation. The default value is None.

Returns

Task<TimelineHistoryFile>

The timeline history file for timeline tli