CREATE SUBSCRIPTION — define una nueva suscripción
CREATE SUBSCRIPTIONnombre_suscripciónCONNECTION 'conninfo' PUBLICATIONnombre_publicación[, ...] [ WITH (parámetro_suscripción[=valor] [, ... ] ) ]
CREATE SUBSCRIPTION añade una nueva suscripción de
replicación lógica. El usuario que crea una suscripción se convierte en el propietario
de la misma. El nombre de la suscripción debe ser distinto del nombre de cualquier
suscripción existente en la base de datos actual.
Una suscripción representa una conexión de replicación con el publicador. Por lo tanto, además de añadir definiciones en los catálogos locales, este comando normalmente crea un slot de replicación en el publicador.
Se iniciará un proceso de replicación lógica (worker) para replicar los datos de la nueva suscripción al confirmarse (commit) la transacción en la que se ejecuta este comando, a menos que la suscripción esté inicialmente desactivada.
Para poder crear una suscripción, debes tener los privilegios del
rol pg_create_subscription, así como
privilegios CREATE en la base de datos actual.
Tienes disponible información adicional sobre las suscripciones y la replicación lógica en general en Section 29.2 y Chapter 29.
nombre_suscripción #El nombre de la nueva suscripción.
CONNECTION 'conninfo' #La cadena de conexión de libpq que define cómo conectarse a la base de datos del publicador. Para obtener más detalles, consulta Section 32.1.1.
PUBLICATION nombre_publicación [, ...] #Nombres de las publicaciones en el publicador a las que suscribirse.
WITH ( parámetro_suscripción [= valor] [, ... ] ) #Esta cláusula especifica parámetros opcionales para una suscripción.
Los siguientes parámetros controlan lo que ocurre durante la creación de la suscripción:
connect (boolean) #
Especifica si el comando CREATE SUBSCRIPTION
debe conectarse en absoluto al publicador. El valor por defecto
es true. Establecer esto en
false forzará los valores de
create_slot, enabled y
copy_data a false.
(No puedes combinar la configuración de connect
en false con la configuración de create_slot,
enabled o copy_data en true.)
Dado que no se realiza ninguna conexión cuando esta opción es
false, no se suscribe ninguna tabla. Para iniciar
la replicación, debes crear manualmente el slot de replicación, activar
el failover si es necesario, activar la suscripción y refrescar la
suscripción. Consulta
Section 29.2.3
para ver ejemplos.
create_slot (boolean) #
Especifica si el comando debe crear el slot de replicación en
el publicador. El valor por defecto es true.
Si se establece en false, eres responsable de
crear el slot del publicador de alguna otra manera. Consulta
Section 29.2.3
para ver ejemplos.
enabled (boolean) #
Especifica si la suscripción debe estar replicando activamente
o si solo debe configurarse pero no iniciarse aún. El valor por defecto
es true.
slot_name (string) #Nombre del slot de replicación del publicador que se va a utilizar. El valor por defecto es utilizar el nombre de la suscripción como nombre del slot.
Establecer slot_name en NONE
significa que no habrá ningún slot de replicación asociado con la
suscripción. Dichas suscripciones también deben tener tanto
enabled como create_slot establecidos en
false. Usa esto cuando vayas a crear el slot de
replicación manualmente más adelante. Consulta
Section 29.2.3
para ver ejemplos.
Al establecer slot_name con un nombre válido y
create_slot en false, el valor
de la propiedad failover del slot especificado puede
diferir del parámetro failover correspondiente
especificado en la suscripción. Asegúrate siempre de que la propiedad del slot
failover coincida con el parámetro homólogo de la
suscripción y viceversa. De lo contrario, el slot en el publicador puede
comportarse de forma diferente a lo que indican estas opciones de suscripción: por
ejemplo, el slot en el publicador podría sincronizarse con los servidores
en espera (standbys) incluso cuando la opción failover de la
suscripción esté desactivada o podría desactivarse para la sincronización incluso cuando la
opción failover de la suscripción esté activada.
Los siguientes parámetros controlan el comportamiento de replicación de la suscripción después de haber sido creada:
binary (boolean) #
Especifica si la suscripción solicitará al publicador que envíe
los datos en formato binario (en lugar de texto). El valor por defecto es
false. Cualquier copia de sincronización inicial de tablas
(consulta copy_data) también utiliza el mismo formato. El formato
binario puede ser más rápido que el formato de texto, pero es menos portable
entre arquitecturas de máquinas y versiones de PostgreSQL.
El formato binario es muy específico de los tipos de datos; por ejemplo, no
permitirá copiar de una columna smallint a una columna
integer, aunque eso funcionaría perfectamente en formato de
texto. Incluso cuando esta opción está activada, solo se transferirán en binario
aquellos tipos de datos que tengan funciones de envío y recepción binaria. Ten en cuenta que
la sincronización inicial requiere que todos los tipos de datos tengan funciones de envío
y recepción binaria, de lo contrario la sincronización fallará
(consulta CREATE TYPE para obtener más información sobre las
funciones de envío/recepción).
Al realizar una replicación entre versiones, podría darse el caso de que el
publicador tenga una función de envío binario para algún tipo de datos, pero el
suscriptor carezca de una función de recepción binaria para ese tipo. En
tal caso, la transferencia de datos fallará y la opción
binary no podrá utilizarse.
Si el publicador es de una versión de PostgreSQL anterior
a la 16, cualquier sincronización inicial de tablas utilizará el formato de texto
incluso si se establece binary = true.
copy_data (boolean) #
Especifica si se deben copiar los datos preexistentes en las publicaciones
a las que se suscribe cuando comienza la replicación.
El valor por defecto es true.
Si las publicaciones contienen cláusulas WHERE, esto
afectará a qué datos se copian. Consulta
Notas para obtener más detalles.
Consulta Notas para ver detalles sobre cómo
copy_data = true puede interactuar con el
parámetro origin.
streaming (enum) #
Especifica si se debe activar la transmisión (streaming) de transacciones en curso
para esta suscripción. El valor por defecto es parallel,
lo que significa que los cambios entrantes se aplican directamente a través de uno de los
procesos de aplicación paralela (parallel apply workers), si están disponibles. Si ningún proceso de
aplicación paralela está libre para manejar transacciones en transmisión, los cambios se escriben
en archivos temporales y se aplican después de que la transacción se confirme (commit). Ten en
cuenta que si ocurre un error en un proceso de aplicación paralela, es posible que el LSN de finalización
de la transacción remota no se reporte en el registro del servidor.
Existe el riesgo de un bloqueo mutuo (deadlock) cuando los esquemas del publicador y del suscriptor difieren, aunque tales casos son raros. El proceso de aplicación está preparado para reintentar estas transacciones automáticamente.
Si se establece en on, los cambios entrantes se escriben en
archivos temporales y se aplican únicamente después de que la transacción se confirme
en el publicador y sea recibida por el suscriptor.
Si se establece en off, todas las transacciones se decodifican por completo
en el publicador y solo entonces se envían al suscriptor como un todo.
synchronous_commit (enum) #
El valor de este parámetro anula la configuración de
synchronous_commit dentro de los procesos de aplicación (apply workers)
de esta suscripción. El valor por defecto es off.
Es seguro usar off para la replicación lógica:
si el suscriptor pierde transacciones debido a la falta de sincronización,
los datos se enviarán nuevamente desde el publicador.
Una configuración diferente podría ser apropiada al realizar replicación
lógica síncrona. Los procesos de replicación lógica reportan las posiciones
de escritura y vaciado (flush) al publicador, y al usar replicación
síncrona, el publicador esperará por el vaciado real. Esto significa que
establecer synchronous_commit para el suscriptor en
off cuando la suscripción se usa para replicación
síncrona podría aumentar la latencia para COMMIT en
el publicador. En este escenario, puede ser ventajoso establecer
synchronous_commit en local o superior.
two_phase (boolean) #
Especifica si la confirmación en dos fases (two-phase commit) está activada para esta suscripción.
El valor por defecto es false.
Cuando la confirmación en dos fases está activada, las transacciones preparadas se envían
al suscriptor en el momento de ejecutar PREPARE TRANSACTION, y se procesan
como transacciones en dos fases también en el suscriptor. De lo contrario, las transacciones
preparadas se envían al suscriptor solo cuando se confirman (commit), y se procesan inmediatamente
por el suscriptor.
La implementación de la confirmación en dos fases requiere que la replicación haya finalizado
con éxito la fase inicial de sincronización de tablas. Por lo tanto, incluso cuando two_phase
está activado para una suscripción, el estado interno de dos fases permanece temporalmente en
“pending” hasta que se completa la fase de inicialización. Consulta la columna
subtwophasestate de
pg_subscription para
conocer el estado real de dos fases.
disable_on_error (boolean) #
Especifica si la suscripción debe desactivarse automáticamente si
los procesos de suscripción detectan algún error durante la replicación
de datos desde el publicador. El valor por defecto es false.
password_required (boolean) #
Si se establece en true, las conexiones al publicador realizadas como
resultado de esta suscripción deben usar autenticación por contraseña y la contraseña
debe especificarse como parte de la cadena de conexión. Esta configuración se ignora cuando
la suscripción pertenece a un superusuario. El valor por defecto es true. Solo
los superusuarios pueden establecer este valor en false.
run_as_owner (boolean) #
Si es true, todas las acciones de replicación se ejecutan como el propietario de la
suscripción. Si es false, los procesos de replicación ejecutarán las acciones en cada
tabla como el propietario de dicha tabla. Esta última configuración es, por lo general,
mucho más segura; para ver detalles, consulta Section 29.11.
El valor por defecto es false.
origin (string) #
Especifica si la suscripción solicitará al publicador que envíe únicamente
los cambios que no tengan origen o que envíe los cambios independientemente
del origen. Establecer origin en none
significa que la suscripción solicitará al publicador enviar solo cambios sin
origen. Establecer origin en any significa
que el publicador enviará los cambios sin importar su origen. El valor por defecto
es any.
Consulta Notas para ver detalles sobre cómo
copy_data = true puede interactuar con el parámetro
origin.
failover (boolean) #
Especifica si los slots de replicación asociados con la suscripción están habilitados
para sincronizarse con los servidores en espera (standbys), de modo que la replicación lógica
pueda reanudarse desde el nuevo servidor primario tras un failover. El valor por defecto
es false.
Al especificar un parámetro de tipo boolean, se puede omitir la parte
= valor, lo cual equivale
a especificar TRUE.
Consulta Section 29.11 para obtener detalles sobre cómo configurar el control de acceso entre la instancia de suscripción y la de publicación.
Al crear un slot de replicación (el comportamiento por defecto), CREATE
SUBSCRIPTION no se puede ejecutar dentro de un bloque de transacción.
Crear una suscripción que se conecta al mismo clúster de base de datos (por ejemplo,
para replicar entre bases de datos en el mismo clúster o para replicar dentro de la misma
base de datos) solo tendrá éxito si el slot de replicación no se crea como parte de la
misma instrucción. De lo contrario, la llamada a CREATE SUBSCRIPTION
se colgará. Para que funcione, crea el slot de replicación por separado (usando la
función pg_create_logical_replication_slot con el nombre de plugin
pgoutput) y crea la suscripción utilizando el parámetro
create_slot = false. Consulta
Section 29.2.3 para ver ejemplos.
Esta es una restricción de la implementación que podría eliminarse en una versión futura.
Si alguna tabla de la publicación tiene una cláusula WHERE, las filas para
las cuales la expresión evalúe a
false o NULL no se publicarán. Si la suscripción tiene
varias publicaciones en las que la misma tabla se ha publicado con diferentes cláusulas
WHERE, una fila se publicará si se cumple alguna de las expresiones
(referidas a esa operación de publicación). En el caso de diferentes cláusulas
WHERE, si una de las publicaciones no tiene cláusula WHERE
(referida a esa operación de publicación) o la publicación se declara como
FOR ALL TABLES
o FOR TABLES IN SCHEMA,
las filas siempre se publican independientemente de la definición de las otras expresiones. Si
el suscriptor es de una versión de PostgreSQL anterior a la 15,
cualquier filtrado de filas se ignorará durante la fase inicial de sincronización de datos. En
este caso, el usuario podría considerar eliminar cualquier dato copiado inicialmente que sea
incompatible con el filtrado posterior. Debido a que la sincronización inicial de datos no tiene
en cuenta el parámetro publish
de la publicación al copiar los datos existentes de la tabla, se pueden copiar algunas filas
que no se replicarían usando DML. Consulta
Section 29.2.2 para ver ejemplos.
No se admiten suscripciones que tengan varias publicaciones en las que la misma tabla se haya publicado con diferentes listas de columnas.
Se permite especificar publicaciones que no existan para que los usuarios puedan añadirlas
más tarde. Esto significa que pg_subscription
puede contener publicaciones inexistentes.
Al usar una combinación de parámetros de suscripción de copy_data = true y
origin = NONE, los datos de la tabla de sincronización inicial se copian
directamente desde el publicador, lo que significa que no es posible conocer el verdadero origen
de esos datos. Si el publicador también tiene suscripciones, los datos de la tabla copiados
podrían haberse originado más arriba. Este escenario se detecta y se registra una advertencia
(WARNING) para el usuario, pero la advertencia es solo una indicación de un problema potencial; es
responsabilidad del usuario realizar las comprobaciones necesarias para garantizar que los orígenes
de los datos copiados sean realmente los deseados o no.
Para saber qué tablas podrían incluir potencialmente orígenes no locales (debido a otras suscripciones creadas en el publicador) intenta con esta consulta SQL:
# sustituye <nombres-pub> abajo con tus nombres de publicación a consultar
SELECT DISTINCT PT.schemaname, PT.tablename
FROM pg_publication_tables PT
JOIN pg_class C ON (C.relname = PT.tablename)
JOIN pg_namespace N ON (N.nspname = PT.schemaname),
pg_subscription_rel PS
WHERE C.relnamespace = N.oid AND
(PS.srrelid = C.oid OR
C.oid IN (SELECT relid FROM pg_partition_ancestors(PS.srrelid) UNION
SELECT relid FROM pg_partition_tree(PS.srrelid))) AND
PT.pubname IN (<nombres-pub>);
Crea una suscripción a un servidor remoto que replica las tablas de las
publicaciones mypublication e insert_only
y comienza a replicar inmediatamente al confirmar la transacción:
CREATE SUBSCRIPTION mysub
CONNECTION 'host=192.168.1.50 port=5432 user=foo dbname=foodb'
PUBLICATION mypublication, insert_only;
Crea una suscripción a un servidor remoto que replica las tablas de la
publicación insert_only y no comienza a replicar hasta
que se active en un momento posterior.
CREATE SUBSCRIPTION mysub
CONNECTION 'host=192.168.1.50 port=5432 user=foo dbname=foodb'
PUBLICATION insert_only
WITH (enabled = false);
CREATE SUBSCRIPTION es una extensión de
PostgreSQL.