Para iniciar la replicación en flujo, el cliente (frontend) envía el
parámetro replication en el mensaje de inicio (startup message). Un
valor booleano de true (o on,
yes, 1) le indica al servidor (backend) que entre en
modo walsender de replicación física, en el cual se puede ejecutar un pequeño conjunto
de comandos de replicación, mostrados a continuación, en lugar de sentencias SQL.
Pasar database como valor para el
parámetro replication le indica al servidor que entre en
modo walsender de replicación lógica, conectándose a la base de datos especificada en
el parámetro dbname. En el modo walsender de replicación lógica,
se pueden emitir tanto los comandos de replicación mostrados a continuación como comandos SQL normales.
Tanto en el modo de replicación física como en el de replicación lógica walsender, solo se puede utilizar el protocolo de consulta simple (simple query).
Con el fin de probar los comandos de replicación, puedes realizar una conexión
de replicación a través de psql o cualquier otra
herramienta que utilice libpq con una cadena de conexión que incluya
la opción replication,
por ejemplo:
psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
Sin embargo, a menudo es más útil usar pg_receivewal (para replicación física) o pg_recvlogical (para replicación lógica).
Los comandos de replicación se registran en el log del servidor cuando log_replication_commands está habilitado.
Los comandos aceptados en el modo de replicación son:
IDENTIFY_SYSTEM
#Solicita al servidor que se identifique a sí mismo. El servidor responde con un conjunto de resultados de una sola fila, que contiene cuatro campos:
systemid (text)El identificador de sistema único que identifica al clúster. Esto se puede usar para verificar que el respaldo base (base backup) utilizado para inicializar el standby provenga del mismo clúster.
timeline (int8)ID de la línea de tiempo (timeline) actual. También es útil para verificar que el standby sea consistente con el primario.
xlogpos (text)Ubicación actual de la descarga (flush) de WAL. Útil para obtener una ubicación conocida en el registro de escritura anticipada (write-ahead log) donde pueda comenzar la transmisión.
dbname (text)Base de datos a la que está conectado o nulo.
SHOW name
#Solicita al servidor que envíe la configuración actual de un parámetro de tiempo de ejecución. Esto es similar al comando SQL SHOW.
nameEl nombre de un parámetro de tiempo de ejecución. Los parámetros disponibles están documentados en Chapter 19.
TIMELINE_HISTORY tli
#
Solicita al servidor que envíe el archivo de historial de línea de tiempo para la línea de tiempo
tli. El servidor responde con un
conjunto de resultados de una sola fila, que contiene dos campos. Aunque los campos
están etiquetados como text, devuelven efectivamente bytes en bruto,
sin conversión de codificación:
filename (text)
Nombre de archivo del archivo de historial de línea de tiempo, p. ej., 00000002.history.
content (text)Contenido del archivo de historial de línea de tiempo.
CREATE_REPLICATION_SLOT slot_name [ TEMPORARY ] { PHYSICAL | LOGICAL output_plugin } [ ( option [, ...] ) ]
#Crea un slot (ranura) de replicación físico o lógico. Consulta Section 26.2.6 para obtener más información sobre los slots de replicación.
slot_nameEl nombre del slot a crear. Debe ser un nombre de slot de replicación válido (consulta Section 26.2.6.1).
output_pluginEl nombre del plugin de salida utilizado para la decodificación lógica (consulta Section 47.6).
TEMPORARYEspecifica que este slot de replicación es temporal. Los slots temporales no se guardan en el disco y se eliminan automáticamente en caso de error o cuando la sesión finaliza.
Se soportan las siguientes opciones:
TWO_PHASE [ boolean ]
Si es true, este slot de replicación lógica soporta la decodificación de confirmaciones en dos fases (two-phase commit).
Con esta opción, los comandos relacionados con la confirmación en dos fases como
PREPARE TRANSACTION, COMMIT PREPARED
y ROLLBACK PREPARED se decodifican y se transmiten.
La transacción se decodificará y se transmitirá en el momento de
PREPARE TRANSACTION.
El valor por defecto es false.
RESERVE_WAL [ boolean ]Si es true, este slot de replicación física reserva WAL inmediatamente. De lo contrario, el WAL solo se reserva al conectarse un cliente de replicación en flujo. El valor por defecto es false.
SNAPSHOT { 'export' | 'use' | 'nothing' }
Decide qué hacer con la instantánea (snapshot) creada durante la inicialización del slot lógico.
'export', que es el valor por defecto,
exportará la instantánea para su uso en otras sesiones. Esta opción no se puede
usar dentro de una transacción. 'use' utilizará la
instantánea para la transacción actual que ejecuta el comando. Esta
opción debe utilizarse dentro de una transacción, y
CREATE_REPLICATION_SLOT debe ser el primer comando
ejecutado en esa transacción. Finalmente, 'nothing' solo
utilizará la instantánea para la decodificación lógica de forma normal pero no hará
nada más con ella.
FAILOVER [ boolean ]Si es true, el slot se habilita para sincronizarse con los standbys de modo que la replicación lógica pueda reanudarse después de una conmutación por error (failover). El valor por defecto es false.
En respuesta a este comando, el servidor enviará un conjunto de resultados de una sola fila que contiene los siguientes campos:
slot_name (text)El nombre del slot de replicación recién creado.
consistent_point (text)La ubicación de WAL en la que el slot se volvió consistente. Esta es la ubicación más temprana desde la cual puede comenzar la transmisión en este slot de replicación.
snapshot_name (text)El identificador de la instantánea exportada por el comando. La instantánea es válida hasta que se ejecute un nuevo comando en esta conexión o se cierre la conexión de replicación. Nulo si el slot creado es físico.
output_plugin (text)El nombre del plugin de salida utilizado por el slot de replicación recién creado. Nulo si el slot creado es físico.
CREATE_REPLICATION_SLOT slot_name [ TEMPORARY ] { PHYSICAL [ RESERVE_WAL ] | LOGICAL output_plugin [ EXPORT_SNAPSHOT | NOEXPORT_SNAPSHOT | USE_SNAPSHOT | TWO_PHASE ] }
#
Por compatibilidad con versiones anteriores, aún se admite esta sintaxis alternativa para
el comando CREATE_REPLICATION_SLOT.
ALTER_REPLICATION_SLOT slot_name ( option [, ...] )
#Modifica la definición de un slot de replicación. Consulta Section 26.2.6 para obtener más información sobre los slots de replicación. Actualmente, este comando solo se admite para slots de replicación lógica.
slot_nameEl nombre del slot a modificar. Debe ser un nombre de slot de replicación válido (consulta Section 26.2.6.1).
Se soportan las siguientes opciones:
TWO_PHASE [ boolean ]
Si es true, este slot de replicación lógica admite la decodificación de confirmaciones en dos fases (two-phase commit).
Con esta opción, los comandos relacionados con la confirmación en dos fases como
PREPARE TRANSACTION, COMMIT PREPARED
y ROLLBACK PREPARED se decodifican y se transmiten.
La transacción se decodificará y se transmitirá en el momento de
PREPARE TRANSACTION.
FAILOVER [ boolean ]Si es true, el slot se habilita para sincronizarse con los standbys de modo que la replicación lógica pueda reanudarse después de una conmutación por error (failover).
READ_REPLICATION_SLOT slot_name
#
Lee cierta información asociada con un slot de replicación. Devuelve una tupla
con valores NULL si el slot de replicación no
existe. Actualmente, este comando solo se admite para slots de replicación
física.
En respuesta a este comando, el servidor devolverá un conjunto de resultados de una sola fila, que contiene los siguientes campos:
slot_type (text)
El tipo del slot de replicación, ya sea physical o
NULL.
restart_lsn (text)
El restart_lsn del slot de replicación.
restart_tli (int8)
El ID de la línea de tiempo asociado con restart_lsn,
siguiendo el historial de la línea de tiempo actual.
START_REPLICATION [ SLOT slot_name ] [ PHYSICAL ] XXX/XXX [ TIMELINE tli ]
#
Indica al servidor que comience a transmitir WAL, empezando en la
ubicación de WAL XXX/XXX.
Si se especifica la opción TIMELINE,
la transmisión comienza en la línea de tiempo tli;
de lo contrario, se selecciona la línea de tiempo actual del servidor. El servidor puede
responder con un error, por ejemplo, si la sección solicitada de WAL ya ha
sido reciclada. En caso de éxito, el servidor responde con un mensaje CopyBothResponse
y luego comienza a transmitir WAL al cliente.
Si se proporciona el nombre de un slot
a través de slot_name, este se actualizará
a medida que avance la replicación para que el servidor sepa qué segmentos de WAL,
y si hot_standby_feedback está activado qué transacciones,
siguen siendo necesarios para el standby.
Si el cliente solicita una línea de tiempo que no es la última pero forma parte de la historia del servidor, el servidor transmitirá todo el WAL en esa línea de tiempo comenzando desde el punto de inicio solicitado hasta el punto en que el servidor cambió a otra línea de tiempo. Si el cliente solicita la transmisión exactamente al final de una línea de tiempo antigua, el servidor omite el modo COPY por completo.
Después de transmitir todo el WAL de una línea de tiempo que no es la última,
el servidor finalizará la transmisión saliendo del modo COPY. Cuando el cliente
reconoce esto saliendo también del modo COPY, el servidor envía un conjunto de resultados
con una fila y dos columnas, indicando la siguiente línea de tiempo en el historial
de este servidor. La primera columna es el ID de la siguiente línea de tiempo (tipo int8), y la
segunda columna es la ubicación de WAL donde ocurrió el cambio (tipo text). Normalmente,
la posición del cambio es el final del WAL que se transmitió, pero hay
casos extremos en los que el servidor puede enviar algún WAL de la línea de tiempo antigua
que no ha reproducido por sí mismo antes de la promoción. Finalmente, el
servidor envía dos mensajes CommandComplete (uno que finaliza el CopyData
y el otro finaliza el propio START_REPLICATION), y
queda listo para aceptar un nuevo comando.
Los datos de WAL se envían como una serie de mensajes CopyData; consulta Section 54.6 y Section 54.7 para obtener más detalles. (Esto permite mezclar otra información; en particular, el servidor puede enviar un mensaje ErrorResponse si encuentra un fallo después de comenzar a transmitir). El contenido de cada mensaje CopyData del servidor al cliente contiene un mensaje con uno de los siguientes formatos:
Identifica el mensaje como datos de WAL.
El punto de inicio de los datos de WAL en este mensaje.
El final actual del WAL en el servidor.
El reloj del sistema del servidor en el momento de la transmisión, expresado en microsegundos desde la medianoche del 2000-01-01.
nUna sección del flujo de datos de WAL.
Un único registro de WAL nunca se divide entre dos mensajes XLogData. Cuando un registro de WAL cruza un límite de página de WAL y, por lo tanto, ya está dividido utilizando registros de continuación, se puede dividir en el límite de la página. In other words, the first main WAL record and its continuation records can be sent in different XLogData messages.
Identifica el mensaje como una señal de mantenimiento de actividad (keepalive) del emisor.
El final actual del WAL en el servidor.
El reloj del sistema del servidor en el momento de la transmisión, expresado en microsegundos desde la medianoche del 2000-01-01.
1 significa que el cliente debe responder a este mensaje lo antes posible para evitar una desconexión por tiempo de espera. 0 en caso contrario.
El proceso receptor puede enviar respuestas de vuelta al emisor en cualquier momento, utilizando uno de los siguientes formatos de mensaje (también en la carga útil de un mensaje CopyData):
Identifica el mensaje como una actualización de estado del receptor.
La ubicación del último byte de WAL + 1 recibido y escrito en el disco en el standby.
La ubicación del último byte de WAL + 1 descargado (flushed) en el disco en el standby.
La ubicación del último byte de WAL + 1 aplicado en el standby.
El reloj del sistema del cliente en el momento de la transmisión, expresado en microsegundos desde la medianoche del 2000-01-01.
Si es 1, el cliente solicita al servidor que responda a este mensaje inmediatamente. Esto se puede usar para hacer ping al servidor y verificar si la conexión sigue activa.
Identifica el mensaje como un mensaje de retroalimentación de hot standby.
El reloj del sistema del cliente en el momento de la transmisión, expresado en microsegundos desde la medianoche del 2000-01-01.
El xmin global actual del standby, excluyendo el
catalog_xmin de cualquier slot de replicación. Si tanto
este valor como el siguiente catalog_xmin
son 0, esto se trata como una notificación de que ya no se enviará retroalimentación
de hot standby en esta conexión. Mensajes posteriores no nulos
pueden reiniciar el mecanismo de retroalimentación.
La época del xid xmin global en el standby.
El catalog_xmin más bajo de cualquier slot de replicación
en el standby. Se establece en 0 si no existe ningún catalog_xmin
en el standby o si se está desactivando la retroalimentación de hot standby.
La época del xid catalog_xmin en el standby.
START_REPLICATION SLOT slot_name LOGICAL XXX/XXX [ ( option_name [ option_value ] [, ...] ) ] #
Indica al servidor que comience a transmitir WAL para la replicación lógica,
empezando ya sea en la ubicación de WAL XXX/XXX o
en el confirmed_flush_lsn del slot (ver Section 53.20), lo que sea mayor. Este
comportamiento facilita a los clientes evitar la actualización de su estado LSN local
cuando no hay datos para procesar. Sin embargo, comenzar en un LSN diferente
al solicitado podría no detectar ciertos tipos de errores del cliente; por lo que el
cliente podría querer verificar que confirmed_flush_lsn
coincida con sus expectativas antes de emitir START_REPLICATION.
El servidor puede responder con un error, por ejemplo, si el slot no existe. En caso de éxito, el servidor responde con un mensaje CopyBothResponse y luego comienza a transmitir WAL al cliente.
Los mensajes dentro de los mensajes CopyBothResponse tienen el mismo formato
documentado para START_REPLICATION ... PHYSICAL, incluyendo
dos mensajes CommandComplete.
El plugin de salida asociado con el slot seleccionado se utiliza para procesar la salida para la transmisión.
SLOT slot_name
El nombre del slot del cual transmitir los cambios. Este parámetro es obligatorio
y debe corresponder a un slot de replicación lógica existente creado con
CREATE_REPLICATION_SLOT en modo LOGICAL.
XXX/XXXLa ubicación de WAL donde comenzar la transmisión.
option_name
El nombre de una opción pasada al plugin de salida de decodificación lógica
del slot. Consulta Section 54.5 para conocer las
opciones aceptadas por el plugin estándar (pgoutput).
option_valueValor opcional, en forma de constante de cadena, asociado con la opción especificada.
DROP_REPLICATION_SLOT slot_name [ WAIT ]
#Elimina un slot de replicación, liberando cualquier recurso reservado en el lado del servidor.
slot_nameEl nombre del slot a eliminar.
WAITEsta opción hace que el comando espere si el slot está activo hasta que pase a estar inactivo, en lugar del comportamiento por defecto de lanzar un error.
UPLOAD_MANIFEST
#Sube un manifiesto de respaldo en preparación para realizar un respaldo incremental.
BASE_BACKUP [ ( option [, ...] ) ]
#Indica al servidor que comience a transmitir un respaldo base (base backup). El sistema se pondrá automáticamente en modo de respaldo antes de que comience el respaldo, y saldrá de él cuando el respaldo se complete. Se aceptan las siguientes opciones:
LABEL 'label'
Establece la etiqueta del respaldo. Si no se especifica ninguna, se utilizará la etiqueta de respaldo
base backup. Las reglas de entrecomillado
para la etiqueta son las mismas que para una cadena SQL estándar con
standard_conforming_strings activado.
TARGET 'target'
Le indica al servidor a dónde enviar el respaldo. Si el objetivo es
client, que es el valor por defecto, los datos del respaldo se
envían al cliente. Si es server, los datos del respaldo
se escriben en el servidor en la ruta especificada por la opción
TARGET_DETAIL. Si es
blackhole, los datos del respaldo no se envían a
ninguna parte; simplemente se descartan.
El objetivo server requiere privilegios de superusuario o
que se le haya concedido el rol pg_write_server_files.
TARGET_DETAIL 'detail'Proporciona información adicional sobre el objetivo del respaldo.
Actualmente, esta opción solo se puede usar cuando el objetivo del respaldo es
server. Especifica el directorio del servidor
en el cual se debe escribir el respaldo.
PROGRESS [ boolean ]Si se establece en true, solicita la información necesaria para generar un informe de progreso. Esto enviará de vuelta un tamaño aproximado en la cabecera de cada tablespace, que se puede utilizar para calcular el avance de la transmisión. Esto se calcula enumerando todos los tamaños de archivo una vez antes de que comience la transferencia, y como tal, podría tener un impacto negativo en el rendimiento. En particular, podría tomar más tiempo antes de que se transmitan los primeros datos. Dado que los archivos de la base de datos pueden cambiar durante el respaldo, el tamaño es solo aproximado y podría tanto aumentar como disminuir entre el momento de la aproximación y el envío de los archivos reales. El valor por defecto es false.
CHECKPOINT { 'fast' | 'spread' }
Establece el tipo de punto de control (checkpoint) a realizar al principio del
respaldo base. El valor por defecto es spread.
WAL [ boolean ]
Si se establece en true, incluye los segmentos de WAL necesarios en el respaldo.
Esto incluirá todos los archivos entre el inicio y fin del respaldo en el
directorio pg_wal del archivo tar del directorio base.
El valor por defecto es false.
WAIT [ boolean ]Si se establece en true, el respaldo esperará hasta que el último segmento de WAL requerido haya sido archivado, o emitirá una advertencia si el archivado de WAL no está habilitado. Si es false, el respaldo no esperará ni advertirá, dejando al cliente la responsabilidad de asegurar que el registro requerido esté disponible. El valor por defecto es true.
COMPRESSION 'method'
Indica al servidor que comprima el respaldo utilizando el método especificado.
Actualmente, los métodos soportados son gzip,
lz4 y zstd.
COMPRESSION_DETAIL detail
Especifica detalles para el método de compresión elegido. Esto solo debe
usarse junto con la opción COMPRESSION.
Si el valor 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, las palabras clave
soportadas son level, long y
workers.
La palabra clave level establece el nivel de compresión.
Para gzip, el nivel de compresión debe ser un entero
entre 1 y 9
(por defecto Z_DEFAULT_COMPRESSION o
-1), para lz4 un entero
entre 1 y 12 (por defecto 0 para el modo de compresión rápido),
y para zstd un entero entre
ZSTD_minCLevel() (usualmente -131072)
y ZSTD_maxCLevel() (usualmente 22),
(por defecto ZSTD_CLEVEL_DEFAULT or
3).
La palabra clave long habilita el modo de coincidencia a larga distancia (long-distance matching)
para mejorar la tasa de compresión, a expensas de un mayor uso de memoria.
El modo a larga distancia solo está soportado para zstd.
La palabra clave workers establece el número de hilos (threads)
que se deben usar para la compresión paralela. La compresión paralela
solo está soportada para zstd.
MAX_RATE rateLimita la cantidad máxima de datos transferidos desde el servidor al cliente por unidad de tiempo. La unidad esperada es kilobytes por segundo. Si se especifica esta opción, el valor debe ser igual a cero o debe estar dentro del rango de 32 kB a 1 GB (inclusive). Si se pasa cero o no se especifica la opción, no se impone ninguna restricción a la transferencia.
TABLESPACE_MAP [ boolean ]
Si es true, incluye información sobre los enlaces simbólicos presentes en el
directorio pg_tblspc en un archivo llamado
tablespace_map. El archivo tablespace map incluye
cada nombre de enlace simbólico tal como existe en el directorio
pg_tblspc/ y la ruta completa de ese enlace simbólico.
El valor por defecto es false.
VERIFY_CHECKSUMS [ boolean ]Si es true, las sumas de comprobación (checksums) se verifican durante un respaldo base si están habilitadas. Si es false, esto se omite. El valor por defecto es true.
MANIFEST manifest_option
Cuando esta opción se especifica con un valor de yes
o force-encode, se crea un manifiesto de respaldo
y se envía junto con el respaldo. El manifiesto es una lista de cada
archivo presente en el respaldo, con la excepción de cualquier archivo WAL que
pueda estar incluido. También almacena el tamaño, la fecha de última modificación y
opcionalmente una suma de comprobación para cada archivo.
Un valor de force-encode obliga a que todos los nombres de archivo
se codifiquen en hexadecimal; de lo contrario, este tipo de codificación se realiza solo
para archivos cuyos nombres son secuencias de octetos no UTF-8.
force-encode está destinado principalmente a fines de prueba,
para asegurar que los clientes que leen el manifiesto de respaldo
puedan manejar este caso. Por compatibilidad con versiones anteriores,
el valor por defecto es MANIFEST 'no'.
MANIFEST_CHECKSUMS checksum_algorithm
Especifica el algoritmo de suma de comprobación que se debe aplicar a cada archivo incluido
en el manifiesto de respaldo. Actualmente, los algoritmos disponibles
son NONE, CRC32C,
SHA224, SHA256,
SHA384 y SHA512.
El valor por defecto es CRC32C.
INCREMENTAL
Solicita un respaldo incremental. El comando
UPLOAD_MANIFEST debe ejecutarse
antes de ejecutar un respaldo base con esta opción.
Cuando se inicia el respaldo, el servidor enviará primero dos conjuntos de resultados normales, seguidos de uno o más resultados CopyOutResponse.
El primer conjunto de resultados normal contiene la posición de inicio del respaldo, en una sola fila con dos columnas. La primera columna contiene la posición de inicio dada en formato XLogRecPtr, y la segunda columna contiene el ID de la línea de tiempo correspondiente.
El segundo conjunto de resultados normal tiene una fila para cada tablespace. Los campos de esta fila son:
spcoid (oid)El OID del tablespace, o nulo si es el directorio base.
spclocation (text)La ruta completa del directorio del tablespace, o nulo si es el directorio base.
size (int8)El tamaño aproximado del tablespace, en kilobytes (1024 bytes), si se ha solicitado el informe de progreso; de lo contrario, es nulo.
Después del segundo conjunto de resultados normal, se enviará una respuesta CopyOutResponse. La carga útil de cada mensaje CopyData contendrá un mensaje en uno de los siguientes formatos:
Identifica el mensaje como el inicio de un nuevo archivo. Habrá un archivo para el directorio de datos principal y uno para cada tablespace adicional; cada uno utilizará el formato tar (siguiendo el “formato de intercambio ustar” especificado en el estándar POSIX 1003.1-2008).
El nombre de archivo para este archivo.
Para el directorio de datos principal, una cadena vacía. Para otros tablespaces, la ruta completa al directorio a partir del cual se creó este archivo.
Identifica el mensaje como el inicio del manifiesto de respaldo.
Identifica el mensaje como contenedor de datos de archivo o de manifiesto.
nBytes de datos.
Identifica el mensaje como un informe de progreso.
El número de bytes del tablespace actual cuyo procesamiento se ha completado.
Después de que se hayan enviado la o todas las respuestas CopyOutResponse, se enviará un conjunto de resultados normal final, que contendrá la posición final de WAL del respaldo, en el mismo formato que la posición de inicio.
El archivo tar para el directorio de datos y cada tablespace contendrá todos los archivos de los directorios, independientemente de si son archivos de PostgreSQL u otros archivos agregados al mismo directorio. Los únicos archivos excluidos son:
postmaster.pid
postmaster.opts
pg_internal.init (encontrado en múltiples directorios)
Varios archivos y directorios temporales creados durante la operación
del servidor PostgreSQL, como cualquier archivo o directorio que comience
con pgsql_tmp y relaciones temporales.
Relaciones no registradas (unlogged relations), excepto por la bifurcación de inicialización (init fork), que es necesaria para recrear la relación no registrada (vacía) al recuperarse.
pg_wal, incluyendo subdirectorios. Si el respaldo se ejecuta
con los archivos WAL incluidos, se incluirá una versión sintetizada de pg_wal,
pero solo contendrá los archivos necesarios para que funcione el respaldo,
no el resto del contenido.
pg_dynshmem, pg_notify,
pg_replslot, pg_serial,
pg_snapshots, pg_stat_tmp y
pg_subtrans se copian como directorios vacíos (incluso si
son enlaces simbólicos).
Se omiten los archivos que no sean archivos y directorios regulares, como enlaces
simbólicos (distintos de los directorios enumerados anteriormente) y archivos de
dispositivos especiales y del sistema operativo. (Se mantienen los enlaces simbólicos
en pg_tblspc).
El propietario, el grupo y el modo de archivo se establecen si el sistema de archivos subyacente del servidor lo admite.
En todos los comandos anteriores,
al especificar un parámetro de tipo boolean, se puede omitir la parte
del value, lo que equivale a
especificar TRUE.