<title>Upgrading logical replication clusters</title>

   <para>
    While upgrading a subscriber, write operations can be performed in the
    publisher. These changes will be replicated to the subscriber once the
    subscriber upgrade is completed.
   </para>

   <note>
    <para>
     The logical replication restrictions apply to logical replication cluster
     upgrades also. See <xref linkend="logical-replication-restrictions"/> for
     details.
    </para>
    <para>
     The prerequisites of publisher upgrade apply to logical replication
     cluster upgrades also. See <xref linkend="prepare-publisher-upgrades"/>
     for details.
    </para>
    <para>
     The prerequisites of subscriber upgrade apply to logical replication
     cluster upgrades also. See <xref linkend="prepare-subscriber-upgrades"/>
     for details.
    </para>
   </note>

   <warning>
    <para>
     Upgrading logical replication cluster requires multiple steps to be
     performed on various nodes. Because not all operations are
     transactional, the user is advised to take backups as described in
     <xref linkend="backup-base-backup"/>.
    </para>
   </warning>

   <para>
    The steps to upgrade the following logical replication clusters are
    detailed below:
    <itemizedlist>
     <listitem>
      <para>
       Follow the steps specified in
       <xref linkend="steps-two-node-logical-replication-cluster"/> to upgrade
       a two-node logical replication cluster.
      </para>
     </listitem>
     <listitem>
      <para>
       Follow the steps specified in
       <xref linkend="steps-cascaded-logical-replication-cluster"/> to upgrade
       a cascaded logical replication cluster.
      </para>
     </listitem>
     <listitem>
      <para>
       Follow the steps specified in
       <xref linkend="steps-two-node-circular-logical-replication-cluster"/>
       to upgrade a two-node circular logical replication cluster.
      </para>
     </listitem>
    </itemizedlist>
   </para>

   <sect3 id="steps-two-node-logical-replication-cluster">
    <title>Steps to upgrade a two-node logical replication cluster</title>
     <para>
      Let's say publisher is in <literal>node1</literal> and subscriber is
      in <literal>node2</literal>. The subscriber <literal>node2</literal> has
      a subscription <literal>sub1_node1_node2</literal> which is subscribing
      the changes from <literal>node1</literal>.
     </para>

     <procedure>
      <step id="two-node-cluster-disable-subscriptions-node2">
       <para>
        Disable all the subscriptions on <literal>node2</literal> that are
        subscribing the changes from <literal>node1</literal> by using
        <link linkend="sql-altersubscription-params-disable"><command>ALTER SUBSCRIPTION ... DISABLE</command></link>,
        e.g.:
<programlisting>
/* node2 # */ ALTER SUBSCRIPTION sub1_node1_node2 DISABLE;
</programlisting>
       </para>
      </step>
      <step>
       <para>
        Stop the publisher server in <literal>node1</literal>, e.g.:
<programlisting>
pg_ctl -D /opt/PostgreSQL/data1 stop
</programlisting>
       </para>
      </step>

      <step>
       <para>
        Initialize <literal>data1_upgraded</literal> instance by using the
        required newer version.
       </para>
      </step>

      <step>
       <para>
        Upgrade the publisher <literal>node1</literal>'s server to the
        required newer version, e.g.:
<programlisting>
pg_upgrade
        --old-datadir "/opt/PostgreSQL/postgres/17/data1"
        --new-datadir "/opt/PostgreSQL/postgres/18/data1_upgraded"
        --old-bindir "/opt/PostgreSQL/postgres/17/bin"
        --new-bindir "/opt/PostgreSQL/postgres/18/bin"
</programlisting>
       </para>
      </step>

      <step>
       <para>
        Start the upgraded publisher server in <literal>node1</literal>, e.g.:
<programlisting>
pg_ctl -D /opt/PostgreSQL/data1_upgraded start -l logfile
</programlisting>
       </para>
      </step>

      <step>