postgresql/doc/src/sgml/ref/alter_publication.sgml

<!--
doc/src/sgml/ref/alter_publication.sgml
PostgreSQL documentation
-->

<refentry id="sql-alterpublication">
 <indexterm zone="sql-alterpublication">
  <primary>ALTER PUBLICATION</primary>
 </indexterm>

 <refmeta>
  <refentrytitle>ALTER PUBLICATION</refentrytitle>
  <manvolnum>7</manvolnum>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>ALTER PUBLICATION</refname>
  <refpurpose>change the definition of a publication</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
ALTER PUBLICATION <replaceable class="parameter">name</replaceable> ADD TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [, ...]
ALTER PUBLICATION <replaceable class="parameter">name</replaceable> SET TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [, ...]
ALTER PUBLICATION <replaceable class="parameter">name</replaceable> DROP TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [, ...]
ALTER PUBLICATION <replaceable class="parameter">name</replaceable> SET ( <replaceable class="parameter">publication_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )
ALTER PUBLICATION <replaceable class="parameter">name</replaceable> OWNER TO { <replaceable>new_owner</replaceable> | CURRENT_USER | SESSION_USER }
ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <replaceable>new_name</replaceable>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   The command <command>ALTER PUBLICATION</command> can change the attributes
   of a publication.
  </para>

  <para>
   The first three variants change which tables are part of the publication.
   The <literal>SET TABLE</literal> clause will replace the list of tables in
   the publication with the specified one.  The <literal>ADD TABLE</literal>
   and <literal>DROP TABLE</literal> clauses will add and remove one or more
   tables from the publication.  Note that adding tables to a publication that
   is already subscribed to will require a <literal>ALTER SUBSCRIPTION
   ... REFRESH PUBLICATION</literal> action on the subscribing side in order
   to become effective.
  </para>

  <para>
   The fourth variant of this command listed in the synopsis can change
   all of the publication properties specified in
   <xref linkend="sql-createpublication"/>.  Properties not mentioned in the
   command retain their previous settings.
  </para>

  <para>
   The remaining variants change the owner and the name of the publication.
  </para>

  <para>
   You must own the publication to use <command>ALTER PUBLICATION</command>.
   To alter the owner, you must also be a direct or indirect member of the new
   owning role. The new owner must have <literal>CREATE</literal> privilege on
   the database.  Also, the new owner of a <literal>FOR ALL TABLES</literal>
   publication must be a superuser.  However, a superuser can change the
   ownership of a publication while circumventing these restrictions.
  </para>
 </refsect1>

 <refsect1>
  <title>Parameters</title>

  <variablelist>
   <varlistentry>
    <term><replaceable class="parameter">name</replaceable></term>
    <listitem>
     <para>
      The name of an existing publication whose definition is to be altered.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="parameter">table_name</replaceable></term>
    <listitem>
     <para>
      Name of an existing table.  If <literal>ONLY</literal> is specified before the
      table name, only that table is affected.  If <literal>ONLY</literal> is not
      specified, the table and all its descendant tables (if any) are
      affected.  Optionally, <literal>*</literal> can be specified after the table
      name to explicitly indicate that descendant tables are included.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>SET ( <replaceable class="parameter">publication_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
    <listitem>
     <para>
      This clause alters publication parameters originally set by
      <xref linkend="sql-createpublication"/>.  See there for more information.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="parameter">new_owner</replaceable></term>
    <listitem>
     <para>
      The user name of the new owner of the publication.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="parameter">new_name</replaceable></term>
    <listitem>
     <para>
      The new name for the publication.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Examples</title>

  <para>
   Change the publication to publish only deletes and updates:
<programlisting>
ALTER PUBLICATION noinsert SET (publish = 'update, delete');
</programlisting>
  </para>

  <para>
   Add some tables to the publication:
<programlisting>
ALTER PUBLICATION mypublication ADD TABLE users, departments;
</programlisting></para>
 </refsect1>

 <refsect1>
  <title>Compatibility</title>

  <para>
   <command>ALTER PUBLICATION</command> is a <productname>PostgreSQL</productname>
   extension.
  </para>
 </refsect1>

 <refsect1>
  <title>See Also</title>

  <simplelist type="inline">
   <member><xref linkend="sql-createpublication"/></member>
   <member><xref linkend="sql-droppublication"/></member>
   <member><xref linkend="sql-createsubscription"/></member>
   <member><xref linkend="sql-altersubscription"/></member>
  </simplelist>
 </refsect1>
</refentry>