CREATE SUBSCRIPTION — définir une nouvelle souscription
CREATE SUBSCRIPTIONnom_souscription
CONNECTION 'conninfo
' PUBLICATIONnom_publication
[, ...] [ WITH (param_souscription
[=valeur
] [, ... ] ) ]
CREATE SUBSCRIPTION
ajoute une nouvelle souscription de
réplication logique. Le nom de la souscription doit être différent
du nom de toutes les autres souscriptions existantee dans la base.
Une souscription représente une connexion de réplication vers un serveur publiant des données. De ce fait, en plus d'ajouter les définitions dans les catalogues locaux, cette commence crée normalement un slot de réplication sur le publieur.
Un worker de réplication logique sera démarré pour répliquer les données pour la nouvelle souscription à la validation de la transaction dans laquelle cette commande est lancée, sauf si la souscription est désactivé à sa création.
Des informations supplémentaires sur la souscription et la réplication logique dans son ensemble sont également disponible sur Section 31.2 et Chapitre 31.
nom_souscription
Le nom de la nouvelle souscriptions.
CONNECTION 'conninfo
'
La chaîne de connexion libpq définissant la façon de se connecter à la base publieur. Pour plus de détails voir Section 34.1.1.
PUBLICATION publication_name
[, ...]
Nom des publications sur le serveur publiant les données auxquelles souscrire.
WITH ( param_souscription
[= valeur
] [, ... ] )
Cette clause indique les paramètres optionnelles pour une souscription.
Les paramètres suivants contrôlent ce qui arrive lors de la création de la souscription :
connect
(boolean
)
Indique si la commande CREATE SUBSCRIPTION
doit se
connecter au publieur. La valeur par défaut est
true
. Configuré à false
, cela
forcera les valeurs de create_slot
,
enabled
et copy_data
à
false
. (Vous ne pouvez pas combiner
connect
à false
avec
create_slot
, enabled
et/ou
copy_data
à true
.)
Comme aucune connexion n'a lieu quand cette option vaut
false
, aucune table n'est souscrite et,
de ce fait, une fois la souscription activée, rien ne sera
répliqué. Vous devrez alors exécuter
ALTER SUBSCRIPTION ... REFRESH PUBLICATION
pour que les tables soient prises en compte.
create_slot
(boolean
)
Spécifie si la commande devrait créer le slot de réplication sur le
serveur publiant les données. La valeur par défaut est
true
.
If set to false
, you are responsible for
creating the publisher's slot in some other way.
enabled
(boolean
)
Spécifie si la souscription devrait répliquer activement, ou si elle
devrait uniquement configurée mais pas démarrée. La valeur par
défaut est true
.
slot_name
(string
)Nom du slot de réplication à utiliser. Par défaut, le nom de la souscription est utilisé comme nom du slot.
Configurer slot_name
à NONE
signifie qu'il n'y aura pas de slot de réplication associé à la
souscription. Utiliser cela quand vous créerez le slot de réplication
manuellement plus tard. Une telle souscription doit également avoir à
la fois enabled
et create_slot
positionnés à false
.
Les paramètres suivants contrôlent le comportement de la réplication pour la souscription après sa création :
binary
(boolean
)
Spécifie si la souscription réclamera au publieur d'envoyer les
données au format binaire (contrairement au texte). La valeur par
défaut est false
. Même quand cette option est
activée, seuls les types de données qui ont les fonctions d'envoi et
de réception binaire seront transférés en binaire.
Lors d'une réplication entre versions différentes, le publieur
pourrait avoir une fonction d'envoi binaire pour certains types de
données mais que le souscripteur n'ait pas de fonction de réception
binaire pour ce type. Dans ce cas, le transfert de données échouera
et l'option binary
ne pourra pas être utilisée.
copy_data
(boolean
)
Spécifie si les données existantes dans les publications qui sont
en train d'être souscrites devraient être copiées une fois la
réplication démarrée. La valeur par défaut est
true
.
Si les publications contiennent des clauses WHERE
,
elles affecteront les données copiées. Référez-vous à Notes pour les détails.
streaming
(boolean
)Spécifie l'activation du flux de transactions en cours pour cette souscription. Par défaut, toutes les transactions sont entièrement décodées sur le publieur, puis envoyées entièrement au souscripteur.
synchronous_commit
(enum
)
La valeur de ce paramètre surcharge le paramètre synchronous_commit pour les processus workers
d'application de cette souscription. La valeur par défaut est
off
.
Il est sans danger d'utiliser off
pour la
réplication logique : si le souscripteur perd des transactions à
cause d'une synchronisation manquée, les données seront renvoyées par
le serveur publiant les données.
Un paramétrage différent peut être appropriée si l'on utilise une
réplication logique synchrone. Les workers de réplication logique
rapportent les positions d'écriture et de synchronisation au serveur
publiant les données, et, en réplication synchrone,
ce dernier attendra que la synchronisation ait lieu.
Cela veut dire que laisser synchronous_commit
à off
sur une souscription
en réplication synchrone peut augmenter la
latence des COMMIT
sur le serveur publiant les
données. Dans ce scénario, il peut être avantageux de positionner
synchronous_commit
à local
ou
au-dessus.
two_phase
(boolean
)
Spécifie si la validation en deux phases est activée pour cette
souscription. La valeur par défaut est false
.
Quand la validation en deux phases est activée, les transactions
préparées sont envoyés au souscripteur au moment du PREPARE
TRANSACTION
, et sont traitées comme des transactions en deux
phases, y compris sur le souscripteur. Sinon, les requêtes préparées
sont envoyés au souscripteur uniquement quand elles sont validées, et
elles sont traitées immédiatement après par le souscripteur.
L'implémentation de la validation en deux phases requiert que la
réplication ait terminée avec succès la synchronisation initiale des
tables. Donc même si two_phase
est activé pour une
souscription, l'état interne de la validation en deux phases reste en
attente temporaire jusqu'à ce que la phase d'initialisation se
termine. Voir la colonne subtwophasestate
de pg_subscription
pour connaître l'état actuel de two-phase.
disable_on_error
(boolean
)
Spécifie si la souscription doit être désactivée automatiquement si
des erreurs sont détectées par les workers de la souscription lors de
la réplication des données du publieur. La valeur par défaut est
false
.
Voir Section 31.9 pour plus de détail sur comment configurer le contrôle d'accès entre la souscription et l'instance de publication.
Lors de la création d'un slot de réplication (comportement par défaut),
CREATE SUBSCRIPTION
ne peut pas être exécuté à
l'intérieur d'un bloc de transaction.
Créer une souscription qui connecte la même instance (par exemple, pour
répliquer entre des bases de données de la même instance ou pour répliquer
dans la même base de données) réussira seulement si le slot de réplication
n'est pas créé dans la même commande. Sinon, l'appel à CREATE
SUBSCRIPTION
va pauser. Pour le faire fonctionner, créer le slot
de réplication séparément (en utilisant la fonction
pg_create_logical_replication_slot
avec le nom de
plugin pgoutput
) et créer la souscription en utilisant
le paramètre create_slot = false
. C'est une restriction
d'implémentation qui pourrait être supprimé dans une prochaine version.
Si une table dans la publication a une clause WHERE
, les
lignes pour lesquelles l'expression
s'évalue à false ou null ne seront
pas publiées. Si la souscription a plusieurs publications dans lesquelles la
même table a été publiée avec des clauses WHERE
différentes, une ligne sera publiée si une des expressions (référant à cette
opération de publication) sera publiée si une des expressions (référant à
cette opération de publication) sont satisfaites. Dans le cas où différentes
clauses WHERE
, si une des publications n'a pas de clause
WHERE
(référant à cette opération de publication) ou si la
publication est déclarée FOR ALL TABLES
ou FOR
TABLES IN SCHEMA
, les lignes sont toujours publiées quelque
soit la définition des autres expressions. Si le souscripteur est une
version PostgreSQL avant la 15, puis toute ligne
filtrante est ignorée lors de la phase de synchronisation initiale des
données. Pour ce cas, l'utilisateur pourrait vouloir considérer la
suppression des données copiées initialement qui serait incompatible avec un
filtrage précédent. Comme la synchronisation des données ne prend pas en
compte le paramètre de publication publish
lors de la
copie des tables existantes, certaines lignes pourraient être copiées sans
être répliquées en utilisant DML. Voir Section 31.2.2 pour des exemples.
Les souscriptions ayant plusieurs publications pour lesquels la même table a été publiée avec des listes de colonnes différentes ne sont pas supportées.
Nous autorisons que des publications inexistantes soient indiquées pour que
les utilisateurs puissent les ajouter après coup. Ceci signifie que pg_subscription
peut avoir des publications inexistantes.
Créer une souscription à un serveur distant qui réplique les tables dans la
publication mypublication
et
insert_only
et démarre la réplication immédiatement après
le commit :
CREATE SUBSCRIPTION mysub CONNECTION 'host=192.168.1.50 port=5432 user=foo dbname=foodb' PUBLICATION mypublication, insert_only;
Crée une souscription vers un serveur distant qui réplique les tables
dans la publication insert_only
et ne commence pas
la réplication jusqu'à ce qu'elle soit activée plus tard.
CREATE SUBSCRIPTION mysub CONNECTION 'host=192.168.1.50 port=5432 user=foo dbname=foodb' PUBLICATION insert_only WITH (enabled = false);
CREATE SUBSCRIPTION
est une extension
PostgreSQL au standard SQL.