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

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE PUBLICATION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createprocedure.html" title="CREATE PROCEDURE" /><link rel="next" href="sql-createrole.html" title="CREATE ROLE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE PUBLICATION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createprocedure.html" title="CREATE PROCEDURE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createrole.html" title="CREATE ROLE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATEPUBLICATION"><div class="titlepage"></div><a id="id-1.9.3.77.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE PUBLICATION</span></h2><p>CREATE PUBLICATION — define a new publication</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
   3 CREATE PUBLICATION <em class="replaceable"><code>name</code></em>
   4     [ FOR ALL TABLES
   5       | FOR <em class="replaceable"><code>publication_object</code></em> [, ... ] ]
   6     [ WITH ( <em class="replaceable"><code>publication_parameter</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] ) ]
   7
   8 <span class="phrase">where <em class="replaceable"><code>publication_object</code></em> is one of:</span>
   9
  10     TABLE [ ONLY ] <em class="replaceable"><code>table_name</code></em> [ * ] [ ( <em class="replaceable"><code>column_name</code></em> [, ... ] ) ] [ WHERE ( <em class="replaceable"><code>expression</code></em> ) ] [, ... ]
  11     TABLES IN SCHEMA { <em class="replaceable"><code>schema_name</code></em> | CURRENT_SCHEMA } [, ... ]
  12 </pre></div><div class="refsect1" id="id-1.9.3.77.5"><h2>Description</h2><p>
  13    <code class="command">CREATE PUBLICATION</code> adds a new publication
  14    into the current database.  The publication name must be distinct from
  15    the name of any existing publication in the current database.
  16   </p><p>
  17    A publication is essentially a group of tables whose data changes are
  18    intended to be replicated through logical replication.  See
  19    <a class="xref" href="logical-replication-publication.html" title="29.1. Publication">Section 29.1</a> for details about how
  20    publications fit into the logical replication setup.
  21    </p></div><div class="refsect1" id="id-1.9.3.77.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt id="SQL-CREATEPUBLICATION-PARAMS-NAME"><span class="term"><em class="replaceable"><code>name</code></em></span> <a href="#SQL-CREATEPUBLICATION-PARAMS-NAME" class="id_link">#</a></dt><dd><p>
  22       The name of the new publication.
  23      </p></dd><dt id="SQL-CREATEPUBLICATION-PARAMS-FOR-TABLE"><span class="term"><code class="literal">FOR TABLE</code></span> <a href="#SQL-CREATEPUBLICATION-PARAMS-FOR-TABLE" class="id_link">#</a></dt><dd><p>
  24       Specifies a list of tables to add to the publication.  If
  25       <code class="literal">ONLY</code> is specified before the table name, only
  26       that table is added to the publication.  If <code class="literal">ONLY</code> is not
  27       specified, the table and all its descendant tables (if any) are added.
  28       Optionally, <code class="literal">*</code> can be specified after the table name to
  29       explicitly indicate that descendant tables are included.
  30       This does not apply to a partitioned table, however.  The partitions of
  31       a partitioned table are always implicitly considered part of the
  32       publication, so they are never explicitly added to the publication.
  33      </p><p>
  34       If the optional <code class="literal">WHERE</code> clause is specified, it defines a
  35       <em class="firstterm">row filter</em> expression. Rows for
  36       which the <em class="replaceable"><code>expression</code></em>
  37       evaluates to false or null will not be published. Note that parentheses
  38       are required around the expression. It has no effect on
  39       <code class="literal">TRUNCATE</code> commands.
  40      </p><p>
  41       When a column list is specified, only the named columns are replicated.
  42       The column list can contain stored generated columns as well. If the
  43       column list is omitted, the publication will replicate all non-generated
  44       columns (including any added in the future) by default. Stored generated
  45       columns can also be replicated if <code class="literal">publish_generated_columns</code>
  46       is set to <code class="literal">stored</code>. Specifying a column list has no
  47       effect on <code class="literal">TRUNCATE</code> commands. See
  48       <a class="xref" href="logical-replication-col-lists.html" title="29.5. Column Lists">Section 29.5</a> for details about column
  49       lists.
  50      </p><p>
  51       Only persistent base tables and partitioned tables can be part of a
  52       publication.  Temporary tables, unlogged tables, foreign tables,
  53       materialized views, and regular views cannot be part of a publication.
  54      </p><p>
  55       Specifying a column list when the publication also publishes
  56       <code class="literal">FOR TABLES IN SCHEMA</code> is not supported.
  57      </p><p>
  58       When a partitioned table is added to a publication, all of its existing
  59       and future partitions are implicitly considered to be part of the
  60       publication.  So, even operations that are performed directly on a
  61       partition are also published via publications that its ancestors are
  62       part of.
  63      </p></dd><dt id="SQL-CREATEPUBLICATION-PARAMS-FOR-ALL-TABLES"><span class="term"><code class="literal">FOR ALL TABLES</code></span> <a href="#SQL-CREATEPUBLICATION-PARAMS-FOR-ALL-TABLES" class="id_link">#</a></dt><dd><p>
  64       Marks the publication as one that replicates changes for all tables in
  65       the database, including tables created in the future.
  66      </p></dd><dt id="SQL-CREATEPUBLICATION-PARAMS-FOR-TABLES-IN-SCHEMA"><span class="term"><code class="literal">FOR TABLES IN SCHEMA</code></span> <a href="#SQL-CREATEPUBLICATION-PARAMS-FOR-TABLES-IN-SCHEMA" class="id_link">#</a></dt><dd><p>
  67       Marks the publication as one that replicates changes for all tables in
  68       the specified list of schemas, including tables created in the future.
  69      </p><p>
  70       Specifying a schema when the publication also publishes a table with a
  71       column list is not supported.
  72      </p><p>
  73       Only persistent base tables and partitioned tables present in the schema
  74       will be included as part of the publication.  Temporary tables, unlogged
  75       tables, foreign tables, materialized views, and regular views from the
  76       schema will not be part of the publication.
  77      </p><p>
  78       When a partitioned table is published via schema level publication, all
  79       of its existing and future partitions are implicitly considered to be part of the
  80       publication, regardless of whether they are from the publication schema or not.
  81       So, even operations that are performed directly on a
  82       partition are also published via publications that its ancestors are
  83       part of.
  84      </p></dd><dt id="SQL-CREATEPUBLICATION-PARAMS-WITH"><span class="term"><code class="literal">WITH ( <em class="replaceable"><code>publication_parameter</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] )</code></span> <a href="#SQL-CREATEPUBLICATION-PARAMS-WITH" class="id_link">#</a></dt><dd><p>
  85       This clause specifies optional parameters for a publication.  The
  86       following parameters are supported:
  87
  88       </p><div class="variablelist"><dl class="variablelist"><dt id="SQL-CREATEPUBLICATION-PARAMS-WITH-PUBLISH"><span class="term"><code class="literal">publish</code> (<code class="type">string</code>)</span> <a href="#SQL-CREATEPUBLICATION-PARAMS-WITH-PUBLISH" class="id_link">#</a></dt><dd><p>
  89           This parameter determines which DML operations will be published by
  90           the new publication to the subscribers.  The value is
  91           comma-separated list of operations.  The allowed operations are
  92           <code class="literal">insert</code>, <code class="literal">update</code>,
  93           <code class="literal">delete</code>, and <code class="literal">truncate</code>.
  94           The default is to publish all actions,
  95           and so the default value for this option is
  96           <code class="literal">'insert, update, delete, truncate'</code>.
  97          </p><p>
  98           This parameter only affects DML operations. In particular, the initial
  99           data synchronization (see <a class="xref" href="logical-replication-architecture.html#LOGICAL-REPLICATION-SNAPSHOT" title="29.9.1. Initial Snapshot">Section 29.9.1</a>)
 100           for logical replication does not take this parameter into account when
 101           copying existing table data.
 102          </p></dd><dt id="SQL-CREATEPUBLICATION-PARAMS-WITH-PUBLISH-GENERATED-COLUMNS"><span class="term"><code class="literal">publish_generated_columns</code> (<code class="type">enum</code>)</span> <a href="#SQL-CREATEPUBLICATION-PARAMS-WITH-PUBLISH-GENERATED-COLUMNS" class="id_link">#</a></dt><dd><p>
 103           Specifies whether the generated columns present in the tables
 104           associated with the publication should be replicated. Possible values
 105           are <code class="literal">none</code> and <code class="literal">stored</code>.
 106          </p><p>
 107           The default is <code class="literal">none</code> meaning the generated
 108           columns present in the tables associated with publication will not be
 109           replicated.
 110          </p><p>
 111           If set to <code class="literal">stored</code>, the stored generated columns
 112           present in the tables associated with publication will be replicated.
 113          </p><div class="note"><h3 class="title">Note</h3><p>
 114            If the subscriber is from a release prior to 18, then initial table
 115            synchronization won't copy generated columns even if parameter
 116            <code class="literal">publish_generated_columns</code> is <code class="literal">stored</code>
 117            in the publisher.
 118           </p></div><p>
 119           See <a class="xref" href="logical-replication-gencols.html" title="29.6. Generated Column Replication">Section 29.6</a> for more details about
 120           logical replication of generated columns.
 121          </p></dd><dt id="SQL-CREATEPUBLICATION-PARAMS-WITH-PUBLISH-VIA-PARTITION-ROOT"><span class="term"><code class="literal">publish_via_partition_root</code> (<code class="type">boolean</code>)</span> <a href="#SQL-CREATEPUBLICATION-PARAMS-WITH-PUBLISH-VIA-PARTITION-ROOT" class="id_link">#</a></dt><dd><p>
 122           This parameter determines whether changes in a partitioned table (or
 123           on its partitions) contained in the publication will be published
 124           using the identity and schema of the partitioned table rather than
 125           that of the individual partitions that are actually changed; the
 126           latter is the default.  Enabling this allows the changes to be
 127           replicated into a non-partitioned table or a partitioned table
 128           consisting of a different set of partitions.
 129          </p><p>
 130           There can be a case where a subscription combines multiple
 131           publications. If a partitioned table is published by any
 132           subscribed publications which set
 133           <code class="literal">publish_via_partition_root = true</code>, changes on this
 134           partitioned table (or on its partitions) will be published using
 135           the identity and schema of this partitioned table rather than
 136           that of the individual partitions.
 137          </p><p>
 138           This parameter also affects how row filters and column lists are
 139           chosen for partitions; see below for details.
 140          </p><p>
 141           If this is enabled, <code class="literal">TRUNCATE</code> operations performed
 142           directly on partitions are not replicated.
 143          </p></dd></dl></div></dd></dl></div><p>
 144    When specifying a parameter of type <code class="type">boolean</code>, the
 145    <code class="literal">=</code> <em class="replaceable"><code>value</code></em>
 146    part can be omitted, which is equivalent to
 147    specifying <code class="literal">TRUE</code>.
 148   </p></div><div class="refsect1" id="id-1.9.3.77.7"><h2>Notes</h2><p>
 149    If <code class="literal">FOR TABLE</code>, <code class="literal">FOR ALL TABLES</code> or
 150    <code class="literal">FOR TABLES IN SCHEMA</code> are not specified, then the
 151    publication starts out with an empty set of tables.  That is useful if
 152    tables or schemas are to be added later.
 153   </p><p>
 154    The creation of a publication does not start replication.  It only defines
 155    a grouping and filtering logic for future subscribers.
 156   </p><p>
 157    To create a publication, the invoking user must have the
 158    <code class="literal">CREATE</code> privilege for the current database.
 159    (Of course, superusers bypass this check.)
 160   </p><p>
 161    To add a table to a publication, the invoking user must have ownership
 162    rights on the table.  The <code class="command">FOR ALL TABLES</code> and
 163    <code class="command">FOR TABLES IN SCHEMA</code> clauses require the invoking
 164    user to be a superuser.
 165   </p><p>
 166    The tables added to a publication that publishes <code class="command">UPDATE</code>
 167    and/or <code class="command">DELETE</code> operations must have
 168    <code class="literal">REPLICA IDENTITY</code> defined.  Otherwise those operations will be
 169    disallowed on those tables.
 170   </p><p>
 171    Any column list must include the <code class="literal">REPLICA IDENTITY</code> columns
 172    in order for <code class="command">UPDATE</code> or <code class="command">DELETE</code>
 173    operations to be published. There are no column list restrictions if the
 174    publication publishes only <code class="command">INSERT</code> operations.
 175   </p><p>
 176    A row filter expression (i.e., the <code class="literal">WHERE</code> clause) must contain only
 177    columns that are covered by the <code class="literal">REPLICA IDENTITY</code>, in
 178    order for <code class="command">UPDATE</code> and <code class="command">DELETE</code> operations
 179    to be published. For publication of <code class="command">INSERT</code> operations,
 180    any column may be used in the <code class="literal">WHERE</code> expression. The
 181    row filter allows simple expressions that don't have
 182    user-defined functions, user-defined operators, user-defined types,
 183    user-defined collations, non-immutable built-in functions, or references to
 184    system columns.
 185   </p><p>
 186    The generated columns that are part of <code class="literal">REPLICA IDENTITY</code>
 187    must be published explicitly either by listing them in the column list or
 188    by enabling the <code class="literal">publish_generated_columns</code> option, in
 189    order for <code class="command">UPDATE</code> and <code class="command">DELETE</code> operations
 190    to be published.
 191   </p><p>
 192    The row filter on a table becomes redundant if
 193    <code class="literal">FOR TABLES IN SCHEMA</code> is specified and the table
 194    belongs to the referred schema.
 195   </p><p>
 196    For published partitioned tables, the row filter for each
 197    partition is taken from the published partitioned table if the
 198    publication parameter <code class="literal">publish_via_partition_root</code> is true,
 199    or from the partition itself if it is false (the default).
 200    See <a class="xref" href="logical-replication-row-filter.html" title="29.4. Row Filters">Section 29.4</a> for details about row
 201    filters.
 202    Similarly, for published partitioned tables, the column list for each
 203    partition is taken from the published partitioned table if the
 204    publication parameter <code class="literal">publish_via_partition_root</code> is true,
 205    or from the partition itself if it is false.
 206   </p><p>
 207    For an <code class="command">INSERT ... ON CONFLICT</code> command, the publication will
 208    publish the operation that results from the command.  Depending
 209    on the outcome, it may be published as either <code class="command">INSERT</code> or
 210    <code class="command">UPDATE</code>, or it may not be published at all.
 211   </p><p>
 212    For a <code class="command">MERGE</code> command, the publication will publish an
 213    <code class="command">INSERT</code>, <code class="command">UPDATE</code>, or <code class="command">DELETE</code>
 214    for each row inserted, updated, or deleted.
 215   </p><p>
 216    <code class="command">ATTACH</code>ing a table into a partition tree whose root is
 217    published using a publication with <code class="literal">publish_via_partition_root</code>
 218    set to <code class="literal">true</code> does not result in the table's existing contents
 219    being replicated.
 220   </p><p>
 221    <code class="command">COPY ... FROM</code> commands are published
 222    as <code class="command">INSERT</code> operations.
 223   </p><p>
 224    <acronym class="acronym">DDL</acronym> operations are not published.
 225   </p><p>
 226    The <code class="literal">WHERE</code> clause expression is executed with the role used
 227    for the replication connection.
 228   </p></div><div class="refsect1" id="id-1.9.3.77.8"><h2>Examples</h2><p>
 229    Create a publication that publishes all changes in two tables:
 230 </p><pre class="programlisting">
 231 CREATE PUBLICATION mypublication FOR TABLE users, departments;
 232 </pre><p>
 233   </p><p>
 234    Create a publication that publishes all changes from active departments:
 235 </p><pre class="programlisting">
 236 CREATE PUBLICATION active_departments FOR TABLE departments WHERE (active IS TRUE);
 237 </pre><p>
 238   </p><p>
 239    Create a publication that publishes all changes in all tables:
 240 </p><pre class="programlisting">
 241 CREATE PUBLICATION alltables FOR ALL TABLES;
 242 </pre><p>
 243   </p><p>
 244    Create a publication that only publishes <code class="command">INSERT</code>
 245    operations in one table:
 246 </p><pre class="programlisting">
 247 CREATE PUBLICATION insert_only FOR TABLE mydata
 248     WITH (publish = 'insert');
 249 </pre><p>
 250   </p><p>
 251    Create a publication that publishes all changes for tables
 252    <code class="structname">users</code>, <code class="structname">departments</code> and
 253    all changes for all the tables present in the schema
 254    <code class="structname">production</code>:
 255 </p><pre class="programlisting">
 256 CREATE PUBLICATION production_publication FOR TABLE users, departments, TABLES IN SCHEMA production;
 257 </pre><p>
 258   </p><p>
 259    Create a publication that publishes all changes for all the tables present in
 260    the schemas <code class="structname">marketing</code> and
 261    <code class="structname">sales</code>:
 262 </p><pre class="programlisting">
 263 CREATE PUBLICATION sales_publication FOR TABLES IN SCHEMA marketing, sales;
 264 </pre><p>
 265    Create a publication that publishes all changes for table <code class="structname">users</code>,
 266    but replicates only columns <code class="structname">user_id</code> and
 267    <code class="structname">firstname</code>:
 268 </p><pre class="programlisting">
 269 CREATE PUBLICATION users_filtered FOR TABLE users (user_id, firstname);
 270 </pre></div><div class="refsect1" id="id-1.9.3.77.9"><h2>Compatibility</h2><p>
 271    <code class="command">CREATE PUBLICATION</code> is a <span class="productname">PostgreSQL</span>
 272    extension.
 273   </p></div><div class="refsect1" id="id-1.9.3.77.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterpublication.html" title="ALTER PUBLICATION"><span class="refentrytitle">ALTER PUBLICATION</span></a>, <a class="xref" href="sql-droppublication.html" title="DROP PUBLICATION"><span class="refentrytitle">DROP PUBLICATION</span></a>, <a class="xref" href="sql-createsubscription.html" title="CREATE SUBSCRIPTION"><span class="refentrytitle">CREATE SUBSCRIPTION</span></a>, <a class="xref" href="sql-altersubscription.html" title="ALTER SUBSCRIPTION"><span class="refentrytitle">ALTER SUBSCRIPTION</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createprocedure.html" title="CREATE PROCEDURE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createrole.html" title="CREATE ROLE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE PROCEDURE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE ROLE</td></tr></table></div></body></html>