Struct ReplicationConfig 

#[non_exhaustive]
pub struct ReplicationConfig {

    pub host: String,
    pub port: u16,
    pub user: String,
    pub password: String,
    pub database: String,
    pub tls: TlsConfig,
    pub slot: String,
    pub publication: Publication,
    pub start_lsn: Lsn,
    pub ack_lsn: Option<Lsn>,
    pub stop_at_lsn: Option<Lsn>,
    pub status_interval: Duration,
    pub idle_wakeup_interval: Duration,
    pub buffer_events: usize,
    pub binary: bool,
    pub options: Option<String>,
    pub max_message_size: usize,
    pub application_name: Option<String>,
    pub feedback_observer: Option<FeedbackObserver>,
}

Configuration for PostgreSQL logical replication connections.

Example

use pgwire_replication::config::{ReplicationConfig, TlsConfig};

let config = ReplicationConfig::new(
    "db.example.com",
    "replicator",
    "secret",
    "mydb",
    "my_slot",
    "my_publication",
)
.with_tls(TlsConfig::verify_full(Some("/path/to/ca.pem".into())));

This struct is #[non_exhaustive]: construct it with ReplicationConfig::new (or unix) plus the with_* builder methods rather than a struct literal, so new fields can be added without breaking you.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

host: String

PostgreSQL server hostname or IP address.

port: u16

PostgreSQL server port (default: 5432).

user: String

PostgreSQL username with replication privileges.

The user must have the REPLICATION attribute or be a superuser.

password: String

Password for authentication.

database: String

Database name to connect to.

tls: TlsConfig

TLS/SSL configuration.

slot: String

Name of the replication slot to use.

The slot must already exist and be a logical replication slot using the pgoutput plugin.

publication: Publication

Publication(s) to subscribe to.

Each publication must exist and include the tables you want to replicate. Accepts a single name or a collection — see Publication.

start_lsn: Lsn

LSN position to start replication from.

• Lsn(0): Start from slot’s confirmed_flush_lsn
• Specific LSN: Resume from that position (must be >= slot’s restart_lsn)

ack_lsn: Option<Lsn>

LSN reported to the server as flushed and applied until the consumer reports more through update_applied_lsn.

• None (default): start_lsn.
• Some(lsn): report lsn instead. A consumer that resumes reading from a position it has not made durable sets this to its durable position, so the slot’s confirmed_flush_lsn never advances past what the consumer could recover from after a crash.

stop_at_lsn: Option<Lsn>

Optional LSN to stop replication at.

When set, replication will stop once a commit with end_lsn >= stop_at_lsn is received. Useful for:

• Bounded replay (e.g., point-in-time recovery)
• Testing with known data ranges

If None, replication continues indefinitely (normal CDC mode).

status_interval: Duration

Interval for sending standby status updates to the server.

Status updates inform PostgreSQL of the client’s replay position, allowing the server to release WAL segments. Too infrequent updates may cause WAL accumulation; too frequent updates add overhead.

Default: 10 seconds (pg_recvlogical defaults to 10 seconds too)

idle_wakeup_interval: Duration

Maximum time to wait for server messages before waking up.

Silence is normal during logical replication. When this interval elapses with no incoming messages, the client will send a standby status update (feedback) and continue waiting.

A raised applied LSN does not wait for this wakeup: it is sent within status_interval of update_applied_lsn.

This effectively bounds how long the worker can stay blocked in a read while idle.

Default: 10 seconds

buffer_events: usize

Size of the bounded event buffer between replication worker and consumer.

Larger buffers can smooth out processing latency spikes but use more memory. Each event is typically 100-1000 bytes depending on row size.

Default: 8192 events

binary: bool

Request column values in PostgreSQL binary wire format.

When true, the binary 'true' option is added to START_REPLICATION and pgoutput encodes column values using each type’s binary send function instead of text output.

This does not change anything the library parses — the worker decodes only Begin/Commit/Message boundaries and forwards XLogData tuple bytes raw — so it is the consumer’s decoder that must handle binary values.

Leave as false (the default) unless you control both ends and have measured a real win: any column whose type lacks a binary send function makes the walsender error and close the replication stream.

Requires PostgreSQL 14 or newer.

Default: false

options: Option<String>

Value for the startup options parameter, passed through to the server the same way libpq’s options connection parameter (or the PGOPTIONS environment variable) would on an ordinary connection.

PostgreSQL honors options on replication connections too, so this is typically used to pin session GUCs (e.g. "-c datestyle=ISO,MDY -c intervalstyle=iso_8601") so that values decoded from the replication stream are rendered in text the same way as values read through a regular connection whose GUCs are also pinned.

See PGOPTIONS for the -c name=value syntax.

Default: None (server defaults apply).

max_message_size: usize

Largest backend message payload accepted, in bytes.

Measured as the message’s length field minus 4, so it excludes the 1-byte tag and the 4-byte length field: the bytes on the wire for a message at the limit are max_message_size + 5.

The worker sizes its buffer from the length the server announces, so this bounds the memory one message can take. A message over the limit is refused before any of it is buffered and ends the stream with PgWireError::MessageTooLarge. The refused payload is never consumed, so the connection cannot be resumed past it — the reader and connection must be discarded. The same limit bounds each row of a gated session’s simple_query.

It bounds exactly one backend-message payload allocation. It does not bound an entire transaction (whose changes span many messages), the event channel or the decoded events buffered in buffer_events, total process memory, or aggregate memory across connections.

As a matter of PostgreSQL framing, pgoutput writes each row change as one CopyData message, so a single wide row or a large pg_logical_emit_message() payload arrives as one message and must fit under this limit. Set below that and the stream ends on the first such row. That is a statement about framing, not a memory guarantee.

Default: MAX_MESSAGE_SIZE (1 GiB)

application_name: Option<String>

application_name sent in the startup message, shown in pg_stat_activity and pg_stat_replication. A consumer that must tell its own walsender from other sessions sets a unique value.

Default: None (pgwire-replication).

feedback_observer: Option<FeedbackObserver>

Called after each successful standby status update that advanced the position reported to the server, with how long that position waited (FeedbackSent). Without one, no timing is kept.

Default: None

Implementations

impl ReplicationConfig

pub fn new( host: impl Into<String>, user: impl Into<String>, password: impl Into<String>, database: impl Into<String>, slot: impl Into<String>, publication: impl Into<Publication>, ) -> Self

Create a new configuration with required fields.

Other fields use defaults and can be customized with builder methods.

Example

use pgwire_replication::config::ReplicationConfig;

let config = ReplicationConfig::new(
    "db.example.com",
    "replicator",
    "secret",
    "mydb",
    "my_slot",
    "my_pub",
);

pub fn is_unix_socket(&self) -> bool

Returns true if host refers to a Unix domain socket directory.

Following libpq convention, a host starting with / is treated as the directory containing the PostgreSQL Unix socket file.

pub fn unix_socket_path(&self) -> PathBuf

Returns the full Unix socket path: {host}/.s.PGSQL.{port}.

Panics

Panics if host does not start with / (i.e. is_unix_socket() is false).

pub fn unix( socket_dir: impl Into<String>, port: u16, user: impl Into<String>, password: impl Into<String>, database: impl Into<String>, slot: impl Into<String>, publication: impl Into<Publication>, ) -> Self

Create a configuration for connecting via Unix domain socket.

socket_dir is the directory containing the PostgreSQL socket file (e.g. /var/run/postgresql). The actual socket path will be {socket_dir}/.s.PGSQL.{port}.

TLS is automatically disabled for Unix socket connections.

Example

use pgwire_replication::config::ReplicationConfig;

let config = ReplicationConfig::unix(
    "/var/run/postgresql",
    5432,
    "replicator",
    "secret",
    "mydb",
    "my_slot",
    "my_pub",
);
assert!(config.is_unix_socket());

pub fn with_port(self, port: u16) -> Self

Set the server port.

pub fn with_tls(self, tls: TlsConfig) -> Self

Set TLS configuration.

pub fn with_start_lsn(self, lsn: Lsn) -> Self

Set the starting LSN.

pub fn with_ack_lsn(self, lsn: Lsn) -> Self

Report lsn as the initially applied position instead of the start position (see ReplicationConfig::ack_lsn).

pub fn with_stop_lsn(self, lsn: Lsn) -> Self

Set an optional stop LSN for bounded replay.

pub fn with_status_interval(self, interval: Duration) -> Self

Set the status update interval.

pub fn with_wakeup_interval(self, timeout: Duration) -> Self

Set the idle wakeup interval.

pub fn with_buffer_size(self, size: usize) -> Self

Set the event buffer size.

pub fn with_binary(self, binary: bool) -> Self

Request binary-format column values from pgoutput (requires PG 14+).

See binary for caveats — off by default.

pub fn with_options(self, options: impl Into<String>) -> Self

Set the startup options parameter (equivalent to libpq’s options connection parameter / PGOPTIONS).

Example

use pgwire_replication::config::ReplicationConfig;

let config = ReplicationConfig::new("h", "u", "p", "db", "slot", "pub")
    .with_options("-c datestyle=ISO,MDY -c intervalstyle=iso_8601");
assert_eq!(
    config.options.as_deref(),
    Some("-c datestyle=ISO,MDY -c intervalstyle=iso_8601")
);

pub fn with_max_message_size(self, bytes: usize) -> Self

Set the largest backend message payload accepted, in bytes.

See max_message_size for what the bound covers. This can only lower the limit: a value above MAX_MESSAGE_SIZE is capped to it.

Example

use pgwire_replication::config::ReplicationConfig;

let config = ReplicationConfig::new("localhost", "u", "p", "db", "slot", "pub")
    .with_max_message_size(64 * 1024 * 1024);
assert_eq!(config.max_message_size, 64 * 1024 * 1024);

pub fn with_application_name(self, name: impl Into<String>) -> Self

Set the startup application_name (see ReplicationConfig::application_name).

pub fn with_feedback_observer(self, observer: FeedbackObserver) -> Self

Observe successful standby status updates that advanced the reported position (see feedback_observer).

pub fn display_connection(&self) -> String

Returns the connection string for display (password masked).

Useful for logging without exposing credentials.

Trait Implementations

impl Clone for ReplicationConfig

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ReplicationConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ReplicationConfig

fn default() -> Self

Returns the “default value” for a type.

impl Eq for ReplicationConfig

impl PartialEq for ReplicationConfig

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for ReplicationConfig