Highest LSN the application has confirmed durably flushed for the current replication stream via confirmFlushed. Initialised to the stream's startLsn by startReplication / startPhysicalReplication; this is the flush/apply position carried by automatic keepalive replies.

Only meaningful during an active stream: outside csReplicating (before a stream starts or after it ends) this returns InvalidLsn (0/0) rather than a stale value left over from a previous stream.

Record that received WAL up to and including lsn has been durably persisted by the application, so automatic keepalive replies (see autoKeepaliveReply on startReplication) report it as the flush/apply position and let the server advance confirmed_flush_lsn and recycle WAL.

Call this from the replication callback after the received changes are durable. Until you do, the automatic reply acknowledges only receipt (the receive LSN), never flush — so a crash re-streams the unprocessed WAL, giving at-least-once delivery. Calls that would move the confirmed position backwards are ignored, so duplicate or out-of-order confirmations are safe.

lsn is clamped to the WAL actually received: you cannot have durably persisted WAL you have not yet received, so an lsn beyond the highest XLogData.receivedEndLsn observed confirms only up to that received position (passing walEnd — which runs ahead of the data this message carries — therefore confirms received WAL rather than over-advancing). Because of this clamp the confirmed position can never exceed received WAL, so automatic replies never emit a flush ahead of receive, and the call never raises on an out-of-range LSN (an uncaught raise from the callback would strand the stream). Must be called while the connection is csReplicating (i.e. from the replication callback); calling it outside an active stream raises PgConnectionError.

Returns true when the confirmed-flush position actually moved forward (after clamping and the monotonic guard). false means the request was ignored because it was behind the current confirmed position.

Create a logical replication slot. Returns slot info including the consistent point LSN.

On timeout, the connection is marked csClosed (protocol out of sync).

Drop a replication slot.

On timeout, the connection is marked csClosed (protocol out of sync).

Execute IDENTIFY_SYSTEM and return system identification info.

On timeout, the connection is marked csClosed (protocol out of sync).

Read information about an existing replication slot.

On timeout, the connection is marked csClosed (protocol out of sync).

Send a raw CopyData frame to the server during a CopyBoth stream (i.e. while the connection is in csReplicating). Useful for protocols layered on top of CopyBoth — for example, physical replication acknowledgements or custom replication plugins that exchange messages the library does not know about. For Standby Status Updates, prefer sendStandbyStatus which builds the payload for you.

data is encoded into a CopyData frame synchronously before the first async suspension, so the caller's buffer does not need to outlive the returned Future.

Send a Standby Status Update to the server during replication streaming. Must be called while the connection is in csReplicating state.

When flushLsn/applyLsn are left at InvalidLsn (0/0) they default up to receiveLsn — convenient for callers that ACK received data eagerly. Pass an explicit flushLsn/applyLsn to report a position behind receiveLsn (e.g. only what the callback has durably flushed). The automatic keepalive reply does not use this proc; it sends the confirmed-flush position verbatim via an internal path so it never inflates flush to merely-received WAL.

Begin physical replication streaming.

slotName is optional; pass "" for a slot-less stream. timeline is appended as TIMELINE n when non-zero — useful when the standby is following a specific timeline and must abort if the primary advanced past it.

The callback contract matches startReplication: each XLogData or PrimaryKeepalive is delivered as a ReplicationMessage. The raw WAL bytes inside XLogData.data are the physical WAL stream; no pgoutput decoding applies.

autoKeepaliveReply behaves identically to startReplication: when true, PrimaryKeepalive(replyRequested=true) is answered before the callback runs, reporting the highest observed receivedEndLsn as the receive LSN and the confirmFlushed position (initially startLsn) as flush/apply. For physical replication the flush LSN governs how much WAL the primary may recycle, so call confirmFlushed only once that WAL is safely on durable storage. A physical standby listed in synchronous_standby_names that relies on the auto-reply must likewise call confirmFlushed (or reply manually), or the primary's synchronous COMMITs will block waiting for a flush position that never advances.

statusInterval behaves as documented on startReplication: a positive value makes the standby send a proactive Standby Status Update at least that often (receive = highest received, flush/apply = confirmFlushed) so the primary can recycle WAL even when it never requests a reply (e.g. wal_sender_timeout = 0); it is honoured only with autoKeepaliveReply, and on asyncdispatch only fires while messages are flowing.

Error handling matches startReplication: a callback exception or any other mid-stream failure poisons the connection (marked closed) and propagates, so reconnect and resume from the last LSN you tracked durable.

On a timeline switch the server may send a final result set describing the next timeline (RowDescription + DataRow + CommandComplete) between CopyDone and ReadyForQuery. This proc drains and discards those messages; callers that need the next-timeline information should re-issue IDENTIFY_SYSTEM after this proc returns.

Begin logical replication streaming from the given slot.

The callback is invoked for each XLogData or PrimaryKeepalive message received. The callback is awaited, providing natural TCP backpressure. From the callback, acknowledge durable progress with confirmFlushed (the default path; see below). With autoKeepaliveReply = false you instead drive replies yourself with sendStandbyStatus; do not mix the two, since the auto-reply would report a flush position behind your manual ACKs.

When autoKeepaliveReply is true (the default), the library responds automatically to PrimaryKeepalive messages with replyRequested = true before invoking the callback. The reply reports the highest receivedEndLsn (startLsn + data.len) observed so far across received XLogData messages — or the caller-supplied startLsn if no XLogData has arrived yet — as the receive LSN, which resets wal_sender_timeout and prevents silent disconnects when the callback is slow. The flush/apply LSN, however, carries only what you have confirmed durable via confirmFlushed (initially startLsn), not the receive LSN. This keeps confirmed_flush_lsn from advancing past WAL the callback has not yet persisted, so a crash re-streams unprocessed changes (at-least-once delivery). The keepalive is still delivered to the callback.

To advance the slot, call confirmFlushed(conn, lsn) from the callback once the received changes are durable. The confirmed position reaches the server on the next reply-requested keepalive and on stopReplication (a clean stop flushes it), not on the confirmFlushed call itself. Set autoKeepaliveReply = false to manage replies entirely by hand with sendStandbyStatus instead — for example, to batch acknowledgements or report apply separately from flush.

Until confirmFlushed is called and while startLsn is at its default InvalidLsn (0/0), the auto-reply carries 0/0 for flush/apply. PostgreSQL treats this as "position unknown" and will not move confirmed_flush_lsn backwards, so the reply is still useful for resetting wal_sender_timeout without risking data loss.

Synchronous standbys: because the auto-reply reports receive and flush/apply separately, a consumer listed in synchronous_standby_names (with synchronous_commit at on/remote_write/remote_apply) that never calls confirmFlushed keeps wal_sender_timeout reset via the receive field yet never advances flush — so the primary's COMMITs block indefinitely waiting for a flush confirmation that never arrives. Call confirmFlushed promptly (or manage replies manually) in that setup.

Proactive status interval: statusInterval (ZeroDuration = off, the default) makes the library send a Standby Status Update on its own at least that often, in addition to answering reply-requested keepalives. The proactive update reports the highest received LSN as receive and the confirmFlushed position as flush/apply — same as the auto-reply — so it advances confirmed_flush_lsn (letting the server recycle WAL) without ever flushing past unconfirmed WAL. Set it when the server uses wal_sender_timeout = 0 (or a long timeout): such a server never asks for a reply, so without a proactive interval the slot only advances on stopReplication and WAL accumulates meanwhile. It is honoured only when autoKeepaliveReply is true; under manual reply management drive the cadence yourself with sendStandbyStatus. Under asyncdispatch the interval only fires while messages are flowing (it cannot safely interrupt a blocked read, so a fully idle stream sends nothing until the next message); chronos honours it even on a completely idle stream.

If the auto-reply itself fails (for example, the connection is lost between receiving the keepalive and writing the Standby Status Update), the exception is propagated out of startReplication and the callback is not invoked for that keepalive.

Errors invalidate the connection. If the callback raises — or the stream fails for any other reason mid-flight — the exception propagates out of this proc and the connection is poisoned (marked closed): the CopyBoth exchange is left half-open and the protocol stream is out of sync, so the connection cannot be reused. There is no built-in reconnect; treat the connection as dead, close it (a pool discards it automatically), and resume on a fresh connection. Because confirmFlushed / confirmedFlushLsn reset once the stream ends, track the last LSN you confirmed durable yourself in the callback so you know the restart point, then pass it as startLsn on the new stream. See examples/replication.nim for a reconnect-and-resume loop.

The proc returns when the server sends CopyDone or the connection closes. To stop replication from the client side, call stopReplication from within the callback (or from a concurrent task).

The bundled pgoutput decoder (parsePgOutputMessage / decodePgOutput) supports protocol version 1 only. Passing a proto_version other than 1 in options raises ValueError, because a v2/v3 stream reshapes and adds messages the decoder cannot parse.

Gracefully terminate the replication stream.

Before sending CopyDone, this flushes the latest confirmFlushed position to the server (receive = highest WAL received, flush/apply = confirmed) so a clean shutdown does not lose the final acknowledgement. confirmFlushed only records locally; without this flush the confirmed position would reach the server only on the next PrimaryKeepalive(replyRequested), which may never arrive before stop — leaving the slot behind and re-streaming the last batch on restart. When nothing has been confirmed the flush is the stream's startLsn (0/0 only when startLsn was left at its default InvalidLsn, which PostgreSQL reads as "position unknown" and will not move the slot backwards), so manual-ACK callers are unaffected.

The server responds with CopyDone and ReadyForQuery, which are handled by the startReplication recv loop.

If flushing the confirmed position fails (for example because the connection is already lost), the exception propagates and CopyDone is not sent. In that situation the server has already dropped the connection, so the missing CopyDone does not change the outcome.

Execute TIMELINE_HISTORY <tli> and return the history file metadata plus its raw contents. Required when a physical standby needs to follow a timeline switch on the primary.

On timeout, the connection is marked csClosed (protocol out of sync).