CREATE SUBSCRIPTION — définir une nouvelle souscription
CREATE SUBSCRIPTIONnom_souscriptionCONNECTION 'information_connexion' PUBLICATIONnom_publication[, ...] [ WITH (param_souscription[=valeur] [, ... ] ) ]
CREATE SUBSCRIPTION ajoute une nouvelle souscription de
réplication logique. L'utilisateur qui crée une souscription devient le
propriétaire de la souscription. Le nom de la souscription doit être différent
du nom de toutes les autres souscriptions existantes 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 commande 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ée à sa création.
Pour créer une souscription, vous devez avoir les droits du rôle
pg_create_subscription, ainsi que le droit
CREATE sur la base de données où vous êtes connecté.
Des informations supplémentaires sur la souscription et la réplication logique dans son ensemble sont également disponibles sur Section 29.2 et Chapitre 29.
nom_souscription #Le nom de la nouvelle souscription.
CONNECTION 'information_connexion' #La chaîne de connexion libpq définissant la façon de se connecter à la base publieur. Pour plus de détails voir Section 32.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. Pour initier
une réplication, vous devez créer manuellement le slot de réplication,
activer le failover si nécessaire, activer la souscription, et rafraichir
la souscription. Voir
Section 29.2.3
pour des exemples.
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.
Si configuré à false, vous êtes responsable de la
création du slot du publieur. Voir
Section 29.2.3
pour des exemples.
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é avec la
souscription. De telles souscriptions doivent aussi avoir à la fois
enabled et create_slot
configurés à false. Utilisez-le quand vous créerez
le slot de réplication manuellement après coup. Voir
Section 29.2.3
pour des exemples.
Lors de l'initialisation de slot_name à un nom
valide et de create_slot à false, la valeur de
la propriété failover d'un slot nommé pourrait
différent du paramètre failover indiqué dans la
souscription. Assurez-vous toujours que la propriété
failover du slot corresponde au paramètre de la
souscription et vice versa. Sinon, le slot du publieur pourrait se
comporter différemment de ce que les options de la souscription indiquent : par exemple, le slot du publieur pourrait être
synchronisé vers les secondaires même si l'option
failover de la souscription est désactivé ou
pourrait être désactivé pour la synchronisation même si l'option
failover de la souscription est activé.
Les paramètres suivants contrôlent le comportement de la réplication pour la souscription après sa création :
binary (boolean) #
Indique si la souscription réclamera au publieur d'envoyer les données
au format binaire (en opposition à texte). La valeur par défaut est
false. Toute copie pour la synchronisation initiale
de table (voir copy_data) utilise aussi le même
format. Le format binaire peut être plus rapide que le format texte,
mais il est moins portable entre différentes architectures machines et
différentes versions de PostgreSQL. Le
format binaire est très spécifique au type de données ; par
exemple, il n'autorisera pas la copie d'une colonne
smallint vers une colonne integer, même
si cela fonctionne bien dans le format texte. Même quand cette option
est activée, seules les types de données ayant les fonctions
d'envoi et de réception binaires transféreront en binaire. Notez que
la synchronisation initiale requiert que tous les types de données
aient les fonctions d'envoi et de réception en binaire. Sinon, la
synchronisation échouera (voir CREATE TYPE pour
plus d'informations les fonctions d'envoi et de réception).
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.
Si le publieur est sur une version de
PostgreSQL antérieure à la 16, alors
toute synchronisation initale de table utilisera le format texte,
même si binary = true.
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.
Voir Notes pour des détails
sur comment copy_data = true peut interagir avec
le paramètre origin.
streaming (enum) #
Spécifie l'activation du flux de transactions en cours pour cette
souscription. The default value is off,
meaning all transactions are fully decoded on the publisher and only
then sent to the subscriber as a whole.
Si configuré à on, les modifications arrivant sont
écrites dans des fichiers temporaires, puis appliquées seulement après
la validation de la transaction sur le publieur et la réception par
l'abonné.
Si configuré à parallel, les modifications arrivant
sont directement appliquées vie un des workers d'application en
parallèle, si disponible. Si aucun worker n'est disponible pour gérer
les transactions en flux, alors les modifications sont écrites dans
des fichiers temporaires et appliquées une fois la transaction validée.
Notez que si une erreur survient dans un worker, le LSN de fin de la
transaction distante pourrait ne pas être indiqué dans les traces.
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.
password_required (boolean) #
Si configuré à true, les connexions au publieur
faite comme résultat de l'abonnement doivent utiliser
l'authentification par mot de passe et le mot de passe doit être
indiqué dans la chaîne de connexion. Ce paramètre est ignoré quant
l'abonnement est la propriété d'un superutilisateur. La valeur par
défaut est true. Seuls les superutilisateurs
peuvent configurer cette valeur à false.
run_as_owner (boolean) #
Si true, toutes les actions de réplication sont réalisées en tant que
le propriétaire de la souscription. Si false, les workers de
réplication réalisent les actions sur chaque table en tant que
propriétaire de la table. Cette dernière configuration est
généralement plus sécurisée, voir
Section 29.10.
La valeur par défaut est false.
origin (string) #
Indique si la souscription réclamera au publieur d'envoyer seulement
les modifications qui n'ont pas d'origine ou d'envoyer les
changements quelque soit l'origine. Configurer
origin à none signifie que la
souscription demandera au publieur d'envoyer uniquement les
changements qui n'ont pas d'origine. Configurer origin
à any signifie que le publieur envoie les changements
quelque soit leur origine. La valeur par défaut est
any.
Voir Notes pour des détails
sur comment copy_data = true peut interagir avec
le paramètre origin.
failover (boolean) #
Indique si les slots de réplication associés avec la souscription
sont activés pour être synchronisés avec les serveurs secondaires
pour que la réplication logique puisse être relancée à partir du
nouveau primaire après une bascule. La valeur par défaut est
false.
Lors de la spécification d'un paramètre de type boolean,
la partie = valeur
peut être omise, ce qui est équivalent à indiquer TRUE.
Voir Section 29.10 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. Voir
Section 29.2.3
pour des exemples. 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 29.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.
Lors de l'utilisation de la combinaison de paramètres de souscription
copy_data = true et origin = NONE,
les données de table de la synchronisation initiale sont copiées directement
à partir du publieur, ce qui signifie que la connaissance de la vraie origine
de cette donnée n'est pas possible. Si le publieur a aussi des souscriptions,
alors les données de table copiées pourraient avoir pour origine un flux plus
lointain. Ce scénario est détecté et un message d'avertissement est tracée
pour l'utilisateur, mais cet avertissement est seulement une indication
d'un problème potentiel ; c'est de la responsabilité de l'utilisateur de
faire les vérifications nécessaires pour s'assurer que l'origine des
données copiées sont bien celles souhaitées.
Pour trouver les tables incluant potentiellement des origines non locales (à cause d'autres souscriptions créées sur le publieur), essayez cette requête SQL :
# substitute <pub-names> below with your publication name(s) to be queried
SELECT DISTINCT PT.schemaname, PT.tablename
FROM pg_publication_tables PT,
pg_subscription_rel PS
JOIN pg_class C ON (C.oid = PS.srrelid)
JOIN pg_namespace N ON (N.oid = C.relnamespace)
WHERE N.nspname = PT.schemaname AND
C.relname = PT.tablename AND
PT.pubname IN (<pub-names>);
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.