pg_receivewal — transmite en flujo (stream) los archivos de registro de escritura anticipada (WAL) de un servidor PostgreSQL
pg_receivewal [option...]
pg_receivewal se utiliza para transmitir en flujo el registro de escritura anticipada (WAL) de un clúster de PostgreSQL en ejecución. El registro de escritura anticipada se transmite en flujo utilizando el protocolo de replicación en flujo, y se escribe en un directorio local de archivos. Este directorio se puede utilizar como la ubicación de archivo para realizar una restauración mediante la recuperación en el tiempo (point-in-time recovery, véase Section 25.3).
pg_receivewal transmite en flujo el registro de escritura anticipada en tiempo real a medida que se genera en el servidor, y no espera a que se completen los segmentos como lo hacen archive_command y archive_library. Por esta razón, no es necesario configurar archive_timeout al utilizar pg_receivewal.
A diferencia del receptor de WAL de un servidor en espera (standby) de PostgreSQL, pg_receivewal
por defecto vuelca (flush) los datos WAL a disco solo cuando se cierra un archivo WAL.
Se debe especificar la opción --synchronous para volcar los datos WAL
en tiempo real. Dado que pg_receivewal no
aplica WAL, no deberías permitir que se convierta en un standby síncrono cuando
synchronous_commit sea igual a
remote_apply. Si lo hace, parecerá ser un
standby que nunca se pone al día, y provocará que las confirmaciones (commits) de
transacciones se bloqueen. Para evitar esto, deberías configurar un valor adecuado
para synchronous_standby_names, o especificar
application_name para
pg_receivewal que no coincida con él, o
cambiar el valor de synchronous_commit a
algo distinto de remote_apply.
El registro de escritura anticipada se transmite en flujo a través de una conexión regular
de PostgreSQL y utiliza el protocolo de replicación.
La conexión debe realizarse con un usuario que tenga permisos de
REPLICATION (véase
Section 21.2) o un superusuario, y
pg_hba.conf debe permitir la conexión de replicación.
El servidor también debe estar configurado con
max_wal_senders establecido con un valor lo suficientemente alto como para dejar al menos
una sesión disponible para la transmisión en flujo.
El punto de partida de la transmisión en flujo del registro de escritura anticipada se calcula cuando se inicia pg_receivewal:
Primero, se escanea el directorio donde se escriben los archivos de segmento WAL y se busca el archivo de segmento completado más reciente, utilizando como punto de partida el inicio del siguiente archivo de segmento WAL.
Si no se puede calcular un punto de partida con el método anterior,
y si se utiliza una ranura (slot) de replicación, se emite un comando
READ_REPLICATION_SLOT adicional para recuperar
el restart_lsn del slot para usarlo como punto de partida.
Esta opción solo está disponible al transmitir en flujo registros de escritura anticipada desde
PostgreSQL 15 en adelante.
Si no se puede calcular un punto de partida con el método anterior,
se utiliza la última ubicación de volcado de WAL reportada por el servidor a partir
de un comando IDENTIFY_SYSTEM.
Si se pierde la conexión, o si no se puede establecer inicialmente,
con un error no fatal, pg_receivewal
reintentará la conexión indefinidamente y restablecerá la transmisión en flujo tan pronto
como sea posible. Para evitar este comportamiento, utiliza el parámetro -n.
En ausencia de errores fatales, pg_receivewal se ejecutará hasta que sea terminado por la señal SIGINT (Control+C) o la señal SIGTERM.
-D directory--directory=directoryDirectorio en el que escribir la salida.
Este parámetro es obligatorio.
-E lsn--endpos=lsnDetiene automáticamente la replicación y termina con un estado de salida normal 0 cuando la recepción alcanza el LSN especificado.
Si hay un registro con un LSN exactamente igual a lsn,
el registro será procesado.
--if-not-exists
No genera un error cuando se especifica --create-slot
y ya existe un slot con el nombre especificado.
-n--no-loopNo entra en bucle ante errores de conexión. En su lugar, termina inmediatamente con un error.
--no-sync
Esta opción hace que pg_receivewal no fuerce el volcado de los
datos WAL al disco. Esto es más rápido, pero significa que una posterior caída
del sistema operativo puede dejar los segmentos WAL corruptos. Por lo general,
esta opción es útil para pruebas, pero no debe utilizarse al archivar WAL
en un despliegue de producción.
Esta opción es incompatible con --synchronous.
-s interval--status-interval=intervalEspecifica el número de segundos entre los paquetes de estado enviados de vuelta al servidor. Esto permite un monitoreo más sencillo del progreso desde el servidor. Un valor de cero desactiva por completo las actualizaciones de estado periódicas, aunque se seguirá enviando una actualización cuando el servidor lo solicite, para evitar la desconexión por tiempo de espera. El valor por defecto es 10 segundos.
-S slotname--slot=slotnameRequiere que pg_receivewal utilice una ranura (slot) de replicación existente (véase Section 26.2.6). Cuando se utiliza esta opción, pg_receivewal informará una posición de volcado al servidor, indicando cuándo se ha sincronizado cada segmento en el disco para que el servidor pueda eliminar ese segmento si no es necesario por otra razón.
Cuando el cliente de replicación
de pg_receivewal está configurado en el
servidor como un standby síncrono, el uso de una ranura de replicación
informará la posición de volcado al servidor, pero solo cuando se cierre un archivo WAL.
Por lo tanto, esa configuración hará que las transacciones en el
primario esperen durante mucho tiempo y, efectivamente, no funcionen de
manera satisfactoria. Además, se debe especificar la opción --synchronous (véase
más abajo) para que esto funcione correctamente.
--synchronous
Vuelca los datos WAL al disco inmediatamente después de haber sido recibidos. También
envía un paquete de estado de vuelta al servidor inmediatamente después del volcado,
independientemente de --status-interval.
Esta opción debe especificarse si el cliente de replicación de pg_receivewal está configurado en el servidor como un standby síncrono, para asegurar que se envíe una respuesta oportuna al servidor.
-v--verboseActiva el modo detallado.
-Z level-Z method[:detail]--compress=level--compress=method[:detail]Activa la compresión de los registros de escritura anticipada.
El método de compresión se puede establecer en gzip,
lz4 (si PostgreSQL
se compiló con --with-lz4) o
none para no aplicar compresión.
Opcionalmente, se puede especificar una cadena de detalles de compresión. Si la
cadena de detalles es un entero, especifica el nivel de compresión.
De lo contrario, debe ser una lista de elementos separados por comas, cada uno con la
forma keyword o
keyword=value.
Actualmente, la única palabra clave admitida es level.
Si no se especifica un nivel de compresión, se utilizará el nivel de compresión
predeterminado. Si solo se especifica un nivel sin mencionar un
algoritmo, se utilizará la compresión gzip si el
nivel es mayor que 0, y no se utilizará ninguna compresión si el nivel
es 0.
El sufijo .gz se añadirá automáticamente a
todos los nombres de archivo al utilizar gzip, y el sufijo
.lz4 se añade al utilizar lz4.
Las siguientes opciones de línea de comandos controlan los parámetros de conexión a la base de datos.
-d connstr--dbname=connstrEspecifica los parámetros utilizados para conectarse al servidor, en forma de cadena de conexión; estos anularán cualquier opción de línea de comandos en conflicto.
Esta opción se llama --dbname por consistencia con otras
aplicaciones cliente, pero dado que pg_receivewal
no se conecta a ninguna base de datos en particular en el clúster, cualquier nombre de base
de datos incluido en la cadena de conexión será ignorado por el servidor.
Sin embargo, un nombre de base de datos proporcionado de esa manera anula el nombre de
base de datos predeterminado (replication) para fines de búsqueda de
la contraseña de la conexión de replicación
en ~/.pgpass. De manera similar, los intermediarios (middleware)
o proxies utilizados para conectarse a PostgreSQL podrían
utilizar el nombre para fines tales como el enrutamiento de conexiones.
-h host--host=host
Especifica el nombre de host de la máquina en la que se está
ejecutando el servidor. Si el valor comienza con una barra diagonal,
se utiliza como el directorio para el socket de dominio Unix. El
valor predeterminado se toma de la variable de entorno PGHOST,
si está establecida; de lo contrario, se intenta una conexión por socket de dominio Unix.
-p port--port=port
Especifica el puerto TCP o la extensión del archivo de socket de
dominio Unix local en el que el servidor está escuchando conexiones.
El valor por defecto es el de la variable de entorno PGPORT, si está
establecida, o un valor predeterminado en tiempo de compilación.
-U username--username=usernameNombre de usuario con el que conectarse.
-w--no-password
Nunca solicita una contraseña. Si el servidor requiere
autenticación por contraseña y no hay una contraseña disponible por
otros medios, como un archivo .pgpass, el
intento de conexión fallará. Esta opción puede ser útil en
tareas por lotes (batch) y scripts donde no hay ningún usuario
presente para introducir una contraseña.
-W--passwordFuerza a pg_receivewal a solicitar una contraseña antes de conectarse a una base de datos.
Esta opción nunca es imprescindible, ya que
pg_receivewal solicitará automáticamente una
contraseña si el servidor exige autenticación por contraseña.
Sin embargo, pg_receivewal desperdiciará un
intento de conexión para descubrir que el servidor requiere una contraseña.
En algunos casos, vale la pena escribir -W para evitar el
intento de conexión adicional.
pg_receivewal puede realizar una de las dos acciones siguientes para controlar las ranuras (slots) de replicación física:
--create-slot
Crea una nueva ranura (slot) de replicación física con el nombre especificado en
--slot, luego termina.
--drop-slot
Elimina la ranura (slot) de replicación con el nombre especificado en
--slot, luego termina.
También están disponibles otras opciones:
-V--versionMuestra la versión de pg_receivewal y termina.
-?--helpMuestra la ayuda sobre los argumentos de línea de comandos de pg_receivewal y termina.
pg_receivewal terminará con el estado 0 cuando sea finalizado por la señal SIGINT o SIGTERM. (Esa es la forma normal de terminarlo. Por lo tanto, no es un error). Para errores fatales u otras señales, el estado de salida será distinto de cero.
Esta utilidad, al igual que la mayoría de las otras utilidades de PostgreSQL, utiliza las variables de entorno admitidas por libpq (véase Section 32.15).
La variable de entorno PG_COLOR especifica si se debe usar
color en los mensajes de diagnóstico. Los valores posibles son
always, auto y
never.
Cuando se utiliza pg_receivewal en lugar de archive_command o archive_library como método principal de copia de seguridad de WAL, se recomienda encarecidamente utilizar ranuras de replicación. De lo contrario, el servidor es libre de reciclar o eliminar archivos de registro de escritura anticipada antes de que se realice la copia de seguridad, porque no tiene ninguna información, ya sea de archive_command o de archive_library o de las ranuras de replicación, sobre hasta dónde se ha archivado la transmisión en flujo de WAL. Ten en cuenta, sin embargo, que una ranura de replicación llenará el espacio de disco del servidor si el receptor no se mantiene al día con la obtención de los datos WAL.
pg_receivewal conservará los permisos de grupo en los archivos WAL recibidos si los permisos de grupo están habilitados en el clúster de origen.
Para transmitir en flujo el registro de escritura anticipada desde el servidor en
mydbserver y almacenarlo en el directorio local
/usr/local/pgsql/archive:
$pg_receivewal -h mydbserver -D /usr/local/pgsql/archive