Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PG_RECEIVEXLOG(1)	PostgreSQL 9.6.20 Documentation	     PG_RECEIVEXLOG(1)

NAME
       pg_receivexlog -	stream transaction logs	from a PostgreSQL server

SYNOPSIS
       pg_receivexlog [option...]

DESCRIPTION
       pg_receivexlog is used to stream	the transaction	log from a running
       PostgreSQL cluster. The transaction log is streamed using the streaming
       replication protocol, and is written to a local directory of files.
       This directory can be used as the archive location for doing a restore
       using point-in-time recovery (see Section 25.3, "Continuous Archiving
       and Point-in-Time Recovery (PITR)", in the documentation).

       pg_receivexlog streams the transaction log in real time as it's being
       generated on the	server,	and does not wait for segments to complete
       like archive_command does. For this reason, it is not necessary to set
       archive_timeout when using pg_receivexlog.

       Unlike the WAL receiver of a PostgreSQL standby server, pg_receivexlog
       by default flushes WAL data only	when a WAL file	is closed. The option
       --synchronous must be specified to flush	WAL data in real time. Since
       pg_receivexlog does not apply WAL, you should not allow it to become a
       synchronous standby when	synchronous_commit equals remote_apply.	If it
       does, it	will appear to be a standby that never catches up, and will
       cause transaction commits to block. To avoid this, you should either
       configure an appropriate	value for synchronous_standby_names, or
       specify application_name	for pg_receivexlog that	does not match it, or
       change the value	of synchronous_commit to something other than
       remote_apply.

       The transaction log is streamed over a regular PostgreSQL connection
       and uses	the replication	protocol. The connection must be made with a
       superuser or a user having REPLICATION permissions (see Section 21.2,
       "Role Attributes", in the documentation), and pg_hba.conf must permit
       the replication connection. The server must also	be configured with
       max_wal_senders set high	enough to leave	at least one session available
       for the stream.

       If the connection is lost, or if	it cannot be initially established,
       with a non-fatal	error, pg_receivexlog will retry the connection
       indefinitely, and reestablish streaming as soon as possible. To avoid
       this behavior, use the -n parameter.

OPTIONS
       -D directory
       --directory=directory
	   Directory to	write the output to.

	   This	parameter is required.

       --if-not-exists
	   Do not error	out when --create-slot is specified and	a slot with
	   the specified name already exists.

       -n
       --no-loop
	   Don't loop on connection errors. Instead, exit right	away with an
	   error.

       -s interval
       --status-interval=interval
	   Specifies the number	of seconds between status packets sent back to
	   the server. This allows for easier monitoring of the	progress from
	   server. A value of zero disables the	periodic status	updates
	   completely, although	an update will still be	sent when requested by
	   the server, to avoid	timeout	disconnect. The	default	value is 10
	   seconds.

       -S slotname
       --slot=slotname
	   Require pg_receivexlog to use an existing replication slot (see
	   Section 26.2.6, "Replication	Slots",	in the documentation). When
	   this	option is used,	pg_receivexlog will report a flush position to
	   the server, indicating when each segment has	been synchronized to
	   disk	so that	the server can remove that segment if it is not
	   otherwise needed.

	   When	the replication	client of pg_receivexlog is configured on the
	   server as a synchronous standby, then using a replication slot will
	   report the flush position to	the server, but	only when a WAL	file
	   is closed. Therefore, that configuration will cause transactions on
	   the primary to wait for a long time and effectively not work
	   satisfactorily. The option --synchronous (see below)	must be
	   specified in	addition to make this work correctly.

       --synchronous
	   Flush the WAL data to disk immediately after	it has been received.
	   Also	send a status packet back to the server	immediately after
	   flushing, regardless	of --status-interval.

	   This	option should be specified if the replication client of
	   pg_receivexlog is configured	on the server as a synchronous
	   standby, to ensure that timely feedback is sent to the server.

       -v
       --verbose
	   Enables verbose mode.

       The following command-line options control the database connection
       parameters.

       -d connstr
       --dbname=connstr
	   Specifies parameters	used to	connect	to the server, as a connection
	   string. See Section 32.1.1, "Connection Strings", in	the
	   documentation for more information.

	   The option is called	--dbname for consistency with other client
	   applications, but because pg_receivexlog doesn't connect to any
	   particular database in the cluster, database	name in	the connection
	   string will be ignored.

       -h host
       --host=host
	   Specifies the host name of the machine on which the server is
	   running. If the value begins	with a slash, it is used as the
	   directory for the Unix domain socket. The default is	taken from the
	   PGHOST environment variable,	if set,	else a Unix domain socket
	   connection is attempted.

       -p port
       --port=port
	   Specifies the TCP port or local Unix	domain socket file extension
	   on which the	server is listening for	connections. Defaults to the
	   PGPORT environment variable,	if set,	or a compiled-in default.

       -U username
       --username=username
	   User	name to	connect	as.

       -w
       --no-password
	   Never issue a password prompt. If the server	requires password
	   authentication and a	password is not	available by other means such
	   as a	.pgpass	file, the connection attempt will fail.	This option
	   can be useful in batch jobs and scripts where no user is present to
	   enter a password.

       -W
       --password
	   Force pg_receivexlog	to prompt for a	password before	connecting to
	   a database.

	   This	option is never	essential, since pg_receivexlog	will
	   automatically prompt	for a password if the server demands password
	   authentication. However, pg_receivexlog will	waste a	connection
	   attempt finding out that the	server wants a password. In some cases
	   it is worth typing -W to avoid the extra connection attempt.

       pg_receivexlog can perform one of the two following actions in order to
       control physical	replication slots:

       --create-slot
	   Create a new	physical replication slot with the name	specified in
	   --slot, then	exit.

       --drop-slot
	   Drop	the replication	slot with the name specified in	--slot,	then
	   exit.

       Other options are also available:

       -V
       --version
	   Print the pg_receivexlog version and	exit.

       -?
       --help
	   Show	help about pg_receivexlog command line arguments, and exit.

ENVIRONMENT
       This utility, like most other PostgreSQL	utilities, uses	the
       environment variables supported by libpq	(see Section 32.14,
       "Environment Variables",	in the documentation).

NOTES
       When using pg_receivexlog instead of archive_command as the main	WAL
       backup method, it is strongly recommended to use	replication slots.
       Otherwise, the server is	free to	recycle	or remove transaction log
       files before they are backed up,	because	it does	not have any
       information, either from	archive_command	or the replication slots,
       about how far the WAL stream has	been archived. Note, however, that a
       replication slot	will fill up the server's disk space if	the receiver
       does not	keep up	with fetching the WAL data.

EXAMPLES
       To stream the transaction log from the server at	mydbserver and store
       it in the local directory /usr/local/pgsql/archive:

	   $ pg_receivexlog -h mydbserver -D /usr/local/pgsql/archive

SEE ALSO
       pg_basebackup(1)

PostgreSQL 9.6.20		     2020		     PG_RECEIVEXLOG(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | ENVIRONMENT | NOTES | EXAMPLES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pg_receivexlog&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help