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

   1
   2 CREATE PUBLICATION
   3
   4    CREATE PUBLICATION — define a new publication
   5
   6 Synopsis
   7
   8 CREATE PUBLICATION name
   9     [ FOR ALL TABLES
  10       | FOR publication_object [, ... ] ]
  11     [ WITH ( publication_parameter [= value] [, ... ] ) ]
  12
  13 where publication_object is one of:
  14
  15     TABLE [ ONLY ] table_name [ * ] [ ( column_name [, ... ] ) ] [ WHERE ( expre
  16 ssion ) ] [, ... ]
  17     TABLES IN SCHEMA { schema_name | CURRENT_SCHEMA } [, ... ]
  18
  19 Description
  20
  21    CREATE PUBLICATION adds a new publication into the current database.
  22    The publication name must be distinct from the name of any existing
  23    publication in the current database.
  24
  25    A publication is essentially a group of tables whose data changes are
  26    intended to be replicated through logical replication. See Section 29.1
  27    for details about how publications fit into the logical replication
  28    setup.
  29
  30 Parameters
  31
  32    name #
  33           The name of the new publication.
  34
  35    FOR TABLE #
  36           Specifies a list of tables to add to the publication. If ONLY is
  37           specified before the table name, only that table is added to the
  38           publication. If ONLY is not specified, the table and all its
  39           descendant tables (if any) are added. Optionally, * can be
  40           specified after the table name to explicitly indicate that
  41           descendant tables are included. This does not apply to a
  42           partitioned table, however. The partitions of a partitioned
  43           table are always implicitly considered part of the publication,
  44           so they are never explicitly added to the publication.
  45
  46           If the optional WHERE clause is specified, it defines a row
  47           filter expression. Rows for which the expression evaluates to
  48           false or null will not be published. Note that parentheses are
  49           required around the expression. It has no effect on TRUNCATE
  50           commands.
  51
  52           When a column list is specified, only the named columns are
  53           replicated. The column list can contain stored generated columns
  54           as well. If the column list is omitted, the publication will
  55           replicate all non-generated columns (including any added in the
  56           future) by default. Stored generated columns can also be
  57           replicated if publish_generated_columns is set to stored.
  58           Specifying a column list has no effect on TRUNCATE commands. See
  59           Section 29.5 for details about column lists.
  60
  61           Only persistent base tables and partitioned tables can be part
  62           of a publication. Temporary tables, unlogged tables, foreign
  63           tables, materialized views, and regular views cannot be part of
  64           a publication.
  65
  66           Specifying a column list when the publication also publishes FOR
  67           TABLES IN SCHEMA is not supported.
  68
  69           When a partitioned table is added to a publication, all of its
  70           existing and future partitions are implicitly considered to be
  71           part of the publication. So, even operations that are performed
  72           directly on a partition are also published via publications that
  73           its ancestors are part of.
  74
  75    FOR ALL TABLES #
  76           Marks the publication as one that replicates changes for all
  77           tables in the database, including tables created in the future.
  78
  79    FOR TABLES IN SCHEMA #
  80           Marks the publication as one that replicates changes for all
  81           tables in the specified list of schemas, including tables
  82           created in the future.
  83
  84           Specifying a schema when the publication also publishes a table
  85           with a column list is not supported.
  86
  87           Only persistent base tables and partitioned tables present in
  88           the schema will be included as part of the publication.
  89           Temporary tables, unlogged tables, foreign tables, materialized
  90           views, and regular views from the schema will not be part of the
  91           publication.
  92
  93           When a partitioned table is published via schema level
  94           publication, all of its existing and future partitions are
  95           implicitly considered to be part of the publication, regardless
  96           of whether they are from the publication schema or not. So, even
  97           operations that are performed directly on a partition are also
  98           published via publications that its ancestors are part of.
  99
 100    WITH ( publication_parameter [= value] [, ... ] ) #
 101           This clause specifies optional parameters for a publication. The
 102           following parameters are supported:
 103
 104         publish (string) #
 105                 This parameter determines which DML operations will be
 106                 published by the new publication to the subscribers. The
 107                 value is comma-separated list of operations. The allowed
 108                 operations are insert, update, delete, and truncate. The
 109                 default is to publish all actions, and so the default
 110                 value for this option is 'insert, update, delete,
 111                 truncate'.
 112
 113                 This parameter only affects DML operations. In particular,
 114                 the initial data synchronization (see Section 29.9.1) for
 115                 logical replication does not take this parameter into
 116                 account when copying existing table data.
 117
 118         publish_generated_columns (enum) #
 119                 Specifies whether the generated columns present in the
 120                 tables associated with the publication should be
 121                 replicated. Possible values are none and stored.
 122
 123                 The default is none meaning the generated columns present
 124                 in the tables associated with publication will not be
 125                 replicated.
 126
 127                 If set to stored, the stored generated columns present in
 128                 the tables associated with publication will be replicated.
 129
 130 Note
 131
 132                 If the subscriber is from a release prior to 18, then
 133                 initial table synchronization won't copy generated columns
 134                 even if parameter publish_generated_columns is stored in
 135                 the publisher.
 136
 137                 See Section 29.6 for more details about logical
 138                 replication of generated columns.
 139
 140         publish_via_partition_root (boolean) #
 141                 This parameter determines whether changes in a partitioned
 142                 table (or on its partitions) contained in the publication
 143                 will be published using the identity and schema of the
 144                 partitioned table rather than that of the individual
 145                 partitions that are actually changed; the latter is the
 146                 default. Enabling this allows the changes to be replicated
 147                 into a non-partitioned table or a partitioned table
 148                 consisting of a different set of partitions.
 149
 150                 There can be a case where a subscription combines multiple
 151                 publications. If a partitioned table is published by any
 152                 subscribed publications which set
 153                 publish_via_partition_root = true, changes on this
 154                 partitioned table (or on its partitions) will be published
 155                 using the identity and schema of this partitioned table
 156                 rather than that of the individual partitions.
 157
 158                 This parameter also affects how row filters and column
 159                 lists are chosen for partitions; see below for details.
 160
 161                 If this is enabled, TRUNCATE operations performed directly
 162                 on partitions are not replicated.
 163
 164    When specifying a parameter of type boolean, the = value part can be
 165    omitted, which is equivalent to specifying TRUE.
 166
 167 Notes
 168
 169    If FOR TABLE, FOR ALL TABLES or FOR TABLES IN SCHEMA are not specified,
 170    then the publication starts out with an empty set of tables. That is
 171    useful if tables or schemas are to be added later.
 172
 173    The creation of a publication does not start replication. It only
 174    defines a grouping and filtering logic for future subscribers.
 175
 176    To create a publication, the invoking user must have the CREATE
 177    privilege for the current database. (Of course, superusers bypass this
 178    check.)
 179
 180    To add a table to a publication, the invoking user must have ownership
 181    rights on the table. The FOR ALL TABLES and FOR TABLES IN SCHEMA
 182    clauses require the invoking user to be a superuser.
 183
 184    The tables added to a publication that publishes UPDATE and/or DELETE
 185    operations must have REPLICA IDENTITY defined. Otherwise those
 186    operations will be disallowed on those tables.
 187
 188    Any column list must include the REPLICA IDENTITY columns in order for
 189    UPDATE or DELETE operations to be published. There are no column list
 190    restrictions if the publication publishes only INSERT operations.
 191
 192    A row filter expression (i.e., the WHERE clause) must contain only
 193    columns that are covered by the REPLICA IDENTITY, in order for UPDATE
 194    and DELETE operations to be published. For publication of INSERT
 195    operations, any column may be used in the WHERE expression. The row
 196    filter allows simple expressions that don't have user-defined
 197    functions, user-defined operators, user-defined types, user-defined
 198    collations, non-immutable built-in functions, or references to system
 199    columns.
 200
 201    The generated columns that are part of REPLICA IDENTITY must be
 202    published explicitly either by listing them in the column list or by
 203    enabling the publish_generated_columns option, in order for UPDATE and
 204    DELETE operations to be published.
 205
 206    The row filter on a table becomes redundant if FOR TABLES IN SCHEMA is
 207    specified and the table belongs to the referred schema.
 208
 209    For published partitioned tables, the row filter for each partition is
 210    taken from the published partitioned table if the publication parameter
 211    publish_via_partition_root is true, or from the partition itself if it
 212    is false (the default). See Section 29.4 for details about row filters.
 213    Similarly, for published partitioned tables, the column list for each
 214    partition is taken from the published partitioned table if the
 215    publication parameter publish_via_partition_root is true, or from the
 216    partition itself if it is false.
 217
 218    For an INSERT ... ON CONFLICT command, the publication will publish the
 219    operation that results from the command. Depending on the outcome, it
 220    may be published as either INSERT or UPDATE, or it may not be published
 221    at all.
 222
 223    For a MERGE command, the publication will publish an INSERT, UPDATE, or
 224    DELETE for each row inserted, updated, or deleted.
 225
 226    ATTACHing a table into a partition tree whose root is published using a
 227    publication with publish_via_partition_root set to true does not result
 228    in the table's existing contents being replicated.
 229
 230    COPY ... FROM commands are published as INSERT operations.
 231
 232    DDL operations are not published.
 233
 234    The WHERE clause expression is executed with the role used for the
 235    replication connection.
 236
 237 Examples
 238
 239    Create a publication that publishes all changes in two tables:
 240 CREATE PUBLICATION mypublication FOR TABLE users, departments;
 241
 242    Create a publication that publishes all changes from active
 243    departments:
 244 CREATE PUBLICATION active_departments FOR TABLE departments WHERE (active IS TRU
 245 E);
 246
 247    Create a publication that publishes all changes in all tables:
 248 CREATE PUBLICATION alltables FOR ALL TABLES;
 249
 250    Create a publication that only publishes INSERT operations in one
 251    table:
 252 CREATE PUBLICATION insert_only FOR TABLE mydata
 253     WITH (publish = 'insert');
 254
 255    Create a publication that publishes all changes for tables users,
 256    departments and all changes for all the tables present in the schema
 257    production:
 258 CREATE PUBLICATION production_publication FOR TABLE users, departments, TABLES I
 259 N SCHEMA production;
 260
 261    Create a publication that publishes all changes for all the tables
 262    present in the schemas marketing and sales:
 263 CREATE PUBLICATION sales_publication FOR TABLES IN SCHEMA marketing, sales;
 264
 265    Create a publication that publishes all changes for table users, but
 266    replicates only columns user_id and firstname:
 267 CREATE PUBLICATION users_filtered FOR TABLE users (user_id, firstname);
 268
 269 Compatibility
 270
 271    CREATE PUBLICATION is a PostgreSQL extension.
 272
 273 See Also
 274
 275    ALTER PUBLICATION, DROP PUBLICATION, CREATE SUBSCRIPTION, ALTER
 276    SUBSCRIPTION