PostgreSQLLa base de données la plus sophistiquée au monde.
Documentation PostgreSQL 15.1 » Référence » Commandes SQL » CREATE SUBSCRIPTION

CREATE SUBSCRIPTION

CREATE SUBSCRIPTION — définir une nouvelle souscription

Synopsis

CREATE SUBSCRIPTION nom_souscription
    CONNECTION 'conninfo'
    PUBLICATION nom_publication [, ...]
    [ WITH ( param_souscription [= valeur] [, ... ] ) ]
  

Description

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.

Paramètres

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 manquante, les données seront renvoyée par le serveur publiant les données.

Un paramétrage différent pourrait être appropriée lorsque la réplication logique est utilisée. Les workers de réplication logique rapportent la position d'écriture et de synchronisation au serveur publiant les données, et lorsque la réplication synchrone est utilisée, le serveur publiant les données attendra la synchronisation. Cela veut dire que positionner synchronous_commit pour le souscripteur à off quand la souscription est utilisée pour de la réplication synchrone pourrait 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.

Notes

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.

Exemples

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);
   

Compatibilité

CREATE SUBSCRIPTION est une extension PostgreSQL au standard SQL.