begriffs open source - ai-pg/blob - full-docs/txt/sql-createsubscription.txt

   1
   2 CREATE SUBSCRIPTION
   3
   4    CREATE SUBSCRIPTION — define a new subscription
   5
   6 Synopsis
   7
   8 CREATE SUBSCRIPTION subscription_name
   9     CONNECTION 'conninfo'
  10     PUBLICATION publication_name [, ...]
  11     [ WITH ( subscription_parameter [= value] [, ... ] ) ]
  12
  13 Description
  14
  15    CREATE SUBSCRIPTION adds a new logical-replication subscription. The
  16    user that creates a subscription becomes the owner of the subscription.
  17    The subscription name must be distinct from the name of any existing
  18    subscription in the current database.
  19
  20    A subscription represents a replication connection to the publisher.
  21    Hence, in addition to adding definitions in the local catalogs, this
  22    command normally creates a replication slot on the publisher.
  23
  24    A logical replication worker will be started to replicate data for the
  25    new subscription at the commit of the transaction where this command is
  26    run, unless the subscription is initially disabled.
  27
  28    To be able to create a subscription, you must have the privileges of
  29    the pg_create_subscription role, as well as CREATE privileges on the
  30    current database.
  31
  32    Additional information about subscriptions and logical replication as a
  33    whole is available at Section 29.2 and Chapter 29.
  34
  35 Parameters
  36
  37    subscription_name #
  38           The name of the new subscription.
  39
  40    CONNECTION 'conninfo' #
  41           The libpq connection string defining how to connect to the
  42           publisher database. For details see Section 32.1.1.
  43
  44    PUBLICATION publication_name [, ...] #
  45           Names of the publications on the publisher to subscribe to.
  46
  47    WITH ( subscription_parameter [= value] [, ... ] ) #
  48           This clause specifies optional parameters for a subscription.
  49
  50           The following parameters control what happens during
  51           subscription creation:
  52
  53         connect (boolean) #
  54                 Specifies whether the CREATE SUBSCRIPTION command should
  55                 connect to the publisher at all. The default is true.
  56                 Setting this to false will force the values of
  57                 create_slot, enabled and copy_data to false. (You cannot
  58                 combine setting connect to false with setting create_slot,
  59                 enabled, or copy_data to true.)
  60
  61                 Since no connection is made when this option is false, no
  62                 tables are subscribed. To initiate replication, you must
  63                 manually create the replication slot, enable the failover
  64                 if required, enable the subscription, and refresh the
  65                 subscription. See Section 29.2.3 for examples.
  66
  67         create_slot (boolean) #
  68                 Specifies whether the command should create the
  69                 replication slot on the publisher. The default is true.
  70
  71                 If set to false, you are responsible for creating the
  72                 publisher's slot in some other way. See Section 29.2.3 for
  73                 examples.
  74
  75         enabled (boolean) #
  76                 Specifies whether the subscription should be actively
  77                 replicating or whether it should just be set up but not
  78                 started yet. The default is true.
  79
  80         slot_name (string) #
  81                 Name of the publisher's replication slot to use. The
  82                 default is to use the name of the subscription for the
  83                 slot name.
  84
  85                 Setting slot_name to NONE means there will be no
  86                 replication slot associated with the subscription. Such
  87                 subscriptions must also have both enabled and create_slot
  88                 set to false. Use this when you will be creating the
  89                 replication slot later manually. See Section 29.2.3 for
  90                 examples.
  91
  92                 When setting slot_name to a valid name and create_slot to
  93                 false, the failover property value of the named slot may
  94                 differ from the counterpart failover parameter specified
  95                 in the subscription. Always ensure the slot property
  96                 failover matches the counterpart parameter of the
  97                 subscription and vice versa. Otherwise, the slot on the
  98                 publisher may behave differently from what these
  99                 subscription options say: for example, the slot on the
 100                 publisher could either be synced to the standbys even when
 101                 the subscription's failover option is disabled or could be
 102                 disabled for sync even when the subscription's failover
 103                 option is enabled.
 104
 105           The following parameters control the subscription's replication
 106           behavior after it has been created:
 107
 108         binary (boolean) #
 109                 Specifies whether the subscription will request the
 110                 publisher to send the data in binary format (as opposed to
 111                 text). The default is false. Any initial table
 112                 synchronization copy (see copy_data) also uses the same
 113                 format. Binary format can be faster than the text format,
 114                 but it is less portable across machine architectures and
 115                 PostgreSQL versions. Binary format is very data type
 116                 specific; for example, it will not allow copying from a
 117                 smallint column to an integer column, even though that
 118                 would work fine in text format. Even when this option is
 119                 enabled, only data types having binary send and receive
 120                 functions will be transferred in binary. Note that the
 121                 initial synchronization requires all data types to have
 122                 binary send and receive functions, otherwise the
 123                 synchronization will fail (see CREATE TYPE for more about
 124                 send/receive functions).
 125
 126                 When doing cross-version replication, it could be that the
 127                 publisher has a binary send function for some data type,
 128                 but the subscriber lacks a binary receive function for
 129                 that type. In such a case, data transfer will fail, and
 130                 the binary option cannot be used.
 131
 132                 If the publisher is a PostgreSQL version before 16, then
 133                 any initial table synchronization will use text format
 134                 even if binary = true.
 135
 136         copy_data (boolean) #
 137                 Specifies whether to copy pre-existing data in the
 138                 publications that are being subscribed to when the
 139                 replication starts. The default is true.
 140
 141                 If the publications contain WHERE clauses, it will affect
 142                 what data is copied. Refer to the Notes for details.
 143
 144                 See Notes for details of how copy_data = true can interact
 145                 with the origin parameter.
 146
 147         streaming (enum) #
 148                 Specifies whether to enable streaming of in-progress
 149                 transactions for this subscription. The default value is
 150                 parallel, meaning incoming changes are directly applied
 151                 via one of the parallel apply workers, if available. If no
 152                 parallel apply worker is free to handle streaming
 153                 transactions then the changes are written to temporary
 154                 files and applied after the transaction is committed. Note
 155                 that if an error happens in a parallel apply worker, the
 156                 finish LSN of the remote transaction might not be reported
 157                 in the server log.
 158
 159 Caution
 160
 161                 There is a risk of deadlock when the schemas of the
 162                 publisher and subscriber differ, although such cases are
 163                 rare. The apply worker is equipped to retry these
 164                 transactions automatically.
 165
 166                 If set to on, the incoming changes are written to
 167                 temporary files and then applied only after the
 168                 transaction is committed on the publisher and received by
 169                 the subscriber.
 170
 171                 If set to off, all transactions are fully decoded on the
 172                 publisher and only then sent to the subscriber as a whole.
 173
 174         synchronous_commit (enum) #
 175                 The value of this parameter overrides the
 176                 synchronous_commit setting within this subscription's
 177                 apply worker processes. The default value is off.
 178
 179                 It is safe to use off for logical replication: If the
 180                 subscriber loses transactions because of missing
 181                 synchronization, the data will be sent again from the
 182                 publisher.
 183
 184                 A different setting might be appropriate when doing
 185                 synchronous logical replication. The logical replication
 186                 workers report the positions of writes and flushes to the
 187                 publisher, and when using synchronous replication, the
 188                 publisher will wait for the actual flush. This means that
 189                 setting synchronous_commit for the subscriber to off when
 190                 the subscription is used for synchronous replication might
 191                 increase the latency for COMMIT on the publisher. In this
 192                 scenario, it can be advantageous to set synchronous_commit
 193                 to local or higher.
 194
 195         two_phase (boolean) #
 196                 Specifies whether two-phase commit is enabled for this
 197                 subscription. The default is false.
 198
 199                 When two-phase commit is enabled, prepared transactions
 200                 are sent to the subscriber at the time of PREPARE
 201                 TRANSACTION, and are processed as two-phase transactions
 202                 on the subscriber too. Otherwise, prepared transactions
 203                 are sent to the subscriber only when committed, and are
 204                 then processed immediately by the subscriber.
 205
 206                 The implementation of two-phase commit requires that
 207                 replication has successfully finished the initial table
 208                 synchronization phase. So even when two_phase is enabled
 209                 for a subscription, the internal two-phase state remains
 210                 temporarily “pending” until the initialization phase
 211                 completes. See column subtwophasestate of pg_subscription
 212                 to know the actual two-phase state.
 213
 214         disable_on_error (boolean) #
 215                 Specifies whether the subscription should be automatically
 216                 disabled if any errors are detected by subscription
 217                 workers during data replication from the publisher. The
 218                 default is false.
 219
 220         password_required (boolean) #
 221                 If set to true, connections to the publisher made as a
 222                 result of this subscription must use password
 223                 authentication and the password must be specified as a
 224                 part of the connection string. This setting is ignored
 225                 when the subscription is owned by a superuser. The default
 226                 is true. Only superusers can set this value to false.
 227
 228         run_as_owner (boolean) #
 229                 If true, all replication actions are performed as the
 230                 subscription owner. If false, replication workers will
 231                 perform actions on each table as the owner of that table.
 232                 The latter configuration is generally much more secure;
 233                 for details, see Section 29.11. The default is false.
 234
 235         origin (string) #
 236                 Specifies whether the subscription will request the
 237                 publisher to only send changes that don't have an origin
 238                 or send changes regardless of origin. Setting origin to
 239                 none means that the subscription will request the
 240                 publisher to only send changes that don't have an origin.
 241                 Setting origin to any means that the publisher sends
 242                 changes regardless of their origin. The default is any.
 243
 244                 See Notes for details of how copy_data = true can interact
 245                 with the origin parameter.
 246
 247         failover (boolean) #
 248                 Specifies whether the replication slots associated with
 249                 the subscription are enabled to be synced to the standbys
 250                 so that logical replication can be resumed from the new
 251                 primary after failover. The default is false.
 252
 253    When specifying a parameter of type boolean, the = value part can be
 254    omitted, which is equivalent to specifying TRUE.
 255
 256 Notes
 257
 258    See Section 29.11 for details on how to configure access control
 259    between the subscription and the publication instance.
 260
 261    When creating a replication slot (the default behavior), CREATE
 262    SUBSCRIPTION cannot be executed inside a transaction block.
 263
 264    Creating a subscription that connects to the same database cluster (for
 265    example, to replicate between databases in the same cluster or to
 266    replicate within the same database) will only succeed if the
 267    replication slot is not created as part of the same command. Otherwise,
 268    the CREATE SUBSCRIPTION call will hang. To make this work, create the
 269    replication slot separately (using the function
 270    pg_create_logical_replication_slot with the plugin name pgoutput) and
 271    create the subscription using the parameter create_slot = false. See
 272    Section 29.2.3 for examples. This is an implementation restriction that
 273    might be lifted in a future release.
 274
 275    If any table in the publication has a WHERE clause, rows for which the
 276    expression evaluates to false or NULL will not be published. If the
 277    subscription has several publications in which the same table has been
 278    published with different WHERE clauses, a row will be published if any
 279    of the expressions (referring to that publish operation) are satisfied.
 280    In the case of different WHERE clauses, if one of the publications has
 281    no WHERE clause (referring to that publish operation) or the
 282    publication is declared as FOR ALL TABLES or FOR TABLES IN SCHEMA, rows
 283    are always published regardless of the definition of the other
 284    expressions. If the subscriber is a PostgreSQL version before 15, then
 285    any row filtering is ignored during the initial data synchronization
 286    phase. For this case, the user might want to consider deleting any
 287    initially copied data that would be incompatible with subsequent
 288    filtering. Because initial data synchronization does not take into
 289    account the publication publish parameter when copying existing table
 290    data, some rows may be copied that would not be replicated using DML.
 291    See Section 29.2.2 for examples.
 292
 293    Subscriptions having several publications in which the same table has
 294    been published with different column lists are not supported.
 295
 296    We allow non-existent publications to be specified so that users can
 297    add those later. This means pg_subscription can have non-existent
 298    publications.
 299
 300    When using a subscription parameter combination of copy_data = true and
 301    origin = NONE, the initial sync table data is copied directly from the
 302    publisher, meaning that knowledge of the true origin of that data is
 303    not possible. If the publisher also has subscriptions then the copied
 304    table data might have originated from further upstream. This scenario
 305    is detected and a WARNING is logged to the user, but the warning is
 306    only an indication of a potential problem; it is the user's
 307    responsibility to make the necessary checks to ensure the copied data
 308    origins are really as wanted or not.
 309
 310    To find which tables might potentially include non-local origins (due
 311    to other subscriptions created on the publisher) try this SQL query:
 312 # substitute <pub-names> below with your publication name(s) to be queried
 313 SELECT DISTINCT PT.schemaname, PT.tablename
 314 FROM pg_publication_tables PT
 315      JOIN pg_class C ON (C.relname = PT.tablename)
 316      JOIN pg_namespace N ON (N.nspname = PT.schemaname),
 317      pg_subscription_rel PS
 318 WHERE C.relnamespace = N.oid AND
 319       (PS.srrelid = C.oid OR
 320       C.oid IN (SELECT relid FROM pg_partition_ancestors(PS.srrelid) UNION
 321                 SELECT relid FROM pg_partition_tree(PS.srrelid))) AND
 322       PT.pubname IN (<pub-names>);
 323
 324 Examples
 325
 326    Create a subscription to a remote server that replicates tables in the
 327    publications mypublication and insert_only and starts replicating
 328    immediately on commit:
 329 CREATE SUBSCRIPTION mysub
 330          CONNECTION 'host=192.168.1.50 port=5432 user=foo dbname=foodb'
 331         PUBLICATION mypublication, insert_only;
 332
 333    Create a subscription to a remote server that replicates tables in the
 334    insert_only publication and does not start replicating until enabled at
 335    a later time.
 336 CREATE SUBSCRIPTION mysub
 337          CONNECTION 'host=192.168.1.50 port=5432 user=foo dbname=foodb'
 338         PUBLICATION insert_only
 339                WITH (enabled = false);
 340
 341 Compatibility
 342
 343    CREATE SUBSCRIPTION is a PostgreSQL extension.
 344
 345 See Also
 346
 347    ALTER SUBSCRIPTION, DROP SUBSCRIPTION, CREATE PUBLICATION, ALTER
 348    PUBLICATION