From 2294b256c7b7c70697eb617b7f3cdae2be201d3c Mon Sep 17 00:00:00 2001
From: Bertrand Drouvot <bertranddrouvot.pg@gmail.com>
Date: Tue, 17 Nov 2026 10:44:25 +0000
Subject: [PATCH v1 2/2] Detect mismatched subscription and slot two_phase
 states

A subscription can use a manually managed slot whose two_phase property does
not match its state, for example after changing its slot or connection, or
recreating the slot.

For PostgreSQL 20 and later publishers, pass the expected state to pgoutput
and validate it after acquiring the slot, before decoding starts. A pending
subscription requires two_phase to remain disabled until table synchronization
is complete, after which START_REPLICATION may enable it. Older publishers
retain the existing behavior and rely on the documented requirement that the
values match.

Checking before decoding avoids detecting a mismatch only after parallel streaming
has produced nontransactional effects on the subscriber. Use the startup error
handling so disable_on_error and apply_error_count work as expected.

Document the behavior and test both mismatch directions and the pending state.

Author: Bertrand Drouvot <bertranddrouvot.pg@gmail.com>
Reviewed-by:
Discussion: https://postgr.es/m/avMmtxMsgqKy4IQq@bdtpg
---
 doc/src/sgml/logicaldecoding.sgml             |  11 ++
 doc/src/sgml/ref/alter_subscription.sgml      |  30 ++-
 doc/src/sgml/ref/create_subscription.sgml     |  16 ++
 .../libpqwalreceiver/libpqwalreceiver.c       |   7 +
 src/backend/replication/logical/worker.c      |  14 ++
 src/backend/replication/pgoutput/pgoutput.c   |  27 +++
 src/include/replication/pgoutput.h            |   2 +
 src/include/replication/walreceiver.h         |   2 +
 .../subscription/t/039_slot_properties.pl     | 183 +++++++++++++++++-
 9 files changed, 278 insertions(+), 14 deletions(-)

diff --git a/doc/src/sgml/logicaldecoding.sgml b/doc/src/sgml/logicaldecoding.sgml
index 79397c7a3f1..780ea092cc9 100644
--- a/doc/src/sgml/logicaldecoding.sgml
+++ b/doc/src/sgml/logicaldecoding.sgml
@@ -740,6 +740,17 @@ DETAIL:  Synchronization could lead to data loss, because the remote slot needs
        </listitem>
       </varlistentry>
 
+      <varlistentry id="pgoutput-options-slot-two-phase">
+       <term><varname>slot_two_phase</varname> (<type>boolean</type>)</term>
+       <listitem>
+        <para>
+         Reports an error unless the selected replication slot's
+         <literal>two_phase</literal> property matches the specified value.
+         The slot property is checked only when this option is specified.
+        </para>
+       </listitem>
+      </varlistentry>
+
       <varlistentry id="pgoutput-options-slot-failover">
        <term><varname>slot_failover</varname> (<type>boolean</type>)</term>
        <listitem>
diff --git a/doc/src/sgml/ref/alter_subscription.sgml b/doc/src/sgml/ref/alter_subscription.sgml
index e17516d0a65..087094435a2 100644
--- a/doc/src/sgml/ref/alter_subscription.sgml
+++ b/doc/src/sgml/ref/alter_subscription.sgml
@@ -310,13 +310,16 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
      <para>
       When altering the
       <link linkend="sql-createsubscription-params-with-slot-name"><literal>slot_name</literal></link>,
-      the <literal>failover</literal> and <literal>two_phase</literal> property
-      values of the named slot may differ from the counterpart
+      the named slot's <literal>failover</literal> property may differ from the
+      counterpart
       <link linkend="sql-createsubscription-params-with-failover"><literal>failover</literal></link>
-      and <link linkend="sql-createsubscription-params-with-two-phase"><literal>two_phase</literal></link>
-      parameters specified in the subscription. When creating the slot, ensure
-      the slot properties <literal>failover</literal> and <literal>two_phase</literal>
-      match their counterpart parameters of the subscription.
+      parameter, and its <literal>two_phase</literal> property may differ from
+      the state required by the subscription's
+      <link linkend="sql-createsubscription-params-with-two-phase"><literal>two_phase</literal></link>
+      parameter. When creating the slot, ensure the
+      <literal>failover</literal> property matches the corresponding parameter
+      and the <literal>two_phase</literal> property matches the required
+      subscription state.
       Otherwise, the slot on the publisher may behave differently from what these
       subscription options say: for example, the slot on the publisher could either be
       synced to the standbys even when the subscription's
@@ -327,12 +330,27 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
       option is enabled.
      </para>
 
+     <para>
+      While the subscription's internal two-phase state is
+      <quote>pending</quote> and not all tables are synchronized and ready, the
+      required slot <literal>two_phase</literal> property is
+      <literal>false</literal>, even if the subscription's
+      <literal>two_phase</literal> parameter is <literal>true</literal>. This
+      also applies to a subscription with no tables, which remains in the
+      <quote>pending</quote> state. Once all tables are ready,
+      <command>START_REPLICATION</command> can enable the slot property, after
+      which the apply worker updates the subscription state.
+     </para>
+
      <para>
       When the publisher is running
       <productname>PostgreSQL</productname> 20 or later, the apply worker
       reports an error when starting replication if the named slot's
       <literal>failover</literal> property does not match the subscription
       parameter.
+      With such a publisher, the apply worker also reports an error when
+      starting replication if the named slot's <literal>two_phase</literal>
+      property does not match the state required by the subscription.
      </para>
 
      <para>
diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
index 1ee3b4d0f55..23a080e7231 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -221,6 +221,22 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
           <literal>failover</literal> property does not match the subscription
           parameter.
          </para>
+
+         <para>
+          The named slot's <literal>two_phase</literal> property may likewise
+          differ from the state required by the subscription. Ensure these
+          values match as well. While the subscription's internal two-phase
+          state is <quote>pending</quote> and not all tables are synchronized
+          and ready, the required slot property is <literal>false</literal>,
+          even if the subscription's <literal>two_phase</literal> parameter is
+          <literal>true</literal>. This also applies to a subscription with no
+          tables, which remains in the <quote>pending</quote> state. Once all
+          tables are ready, <command>START_REPLICATION</command> can enable the
+          slot property, after which the apply worker updates the subscription
+          state. With a <productname>PostgreSQL</productname> 20 or later
+          publisher, the apply worker also reports an error when starting
+          replication if they do not match.
+         </para>
         </listitem>
        </varlistentry>
       </variablelist>
diff --git a/src/backend/replication/libpqwalreceiver/libpqwalreceiver.c b/src/backend/replication/libpqwalreceiver/libpqwalreceiver.c
index e581e60b9c3..eed1a164f83 100644
--- a/src/backend/replication/libpqwalreceiver/libpqwalreceiver.c
+++ b/src/backend/replication/libpqwalreceiver/libpqwalreceiver.c
@@ -658,6 +658,13 @@ libpqrcv_startstreaming(WalReceiverConn *conn,
 			PQserverVersion(conn->streamConn) >= 150000)
 			appendStringInfoString(&cmd, ", two_phase 'on'");
 
+		if (options->proto.logical.slot_twophase_set &&
+			PQserverVersion(conn->streamConn) >=
+			LOGICALREP_SLOT_PROPERTY_CHECK_SERVER_VERSION_NUM)
+			appendStringInfo(&cmd, ", slot_two_phase '%s'",
+							 options->proto.logical.slot_twophase ?
+							 "true" : "false");
+
 		if (options->proto.logical.slot_failover_set &&
 			PQserverVersion(conn->streamConn) >=
 			LOGICALREP_SLOT_PROPERTY_CHECK_SERVER_VERSION_NUM)
diff --git a/src/backend/replication/logical/worker.c b/src/backend/replication/logical/worker.c
index 31f20703883..322107b79ae 100644
--- a/src/backend/replication/logical/worker.c
+++ b/src/backend/replication/logical/worker.c
@@ -5675,6 +5675,8 @@ set_stream_options(WalRcvStreamOptions *options,
 	}
 
 	options->proto.logical.twophase = false;
+	options->proto.logical.slot_twophase = false;
+	options->proto.logical.slot_twophase_set = false;
 	options->proto.logical.slot_failover = false;
 	options->proto.logical.slot_failover_set = false;
 	options->proto.logical.origin = pstrdup(MySubscription->origin);
@@ -5831,6 +5833,18 @@ run_apply_worker(void)
 		MySubscription->twophasestate == LOGICALREP_TWOPHASE_STATE_PENDING &&
 		AllTablesyncsReady();
 
+	/*
+	 * A pending subscription that is ready can enable two-phase decoding as
+	 * part of START_REPLICATION. Otherwise, require the slot to match the
+	 * subscription state before decoding starts.
+	 */
+	if (!enable_twophase)
+	{
+		options.proto.logical.slot_twophase =
+			MySubscription->twophasestate == LOGICALREP_TWOPHASE_STATE_ENABLED;
+		options.proto.logical.slot_twophase_set = true;
+	}
+
 	options.proto.logical.slot_failover = MySubscription->failover;
 	options.proto.logical.slot_failover_set = true;
 
diff --git a/src/backend/replication/pgoutput/pgoutput.c b/src/backend/replication/pgoutput/pgoutput.c
index 6258b96b11d..e39e22cafa8 100644
--- a/src/backend/replication/pgoutput/pgoutput.c
+++ b/src/backend/replication/pgoutput/pgoutput.c
@@ -27,6 +27,7 @@
 #include "replication/logicalproto.h"
 #include "replication/origin.h"
 #include "replication/pgoutput.h"
+#include "replication/slot.h"
 #include "rewrite/rewriteHandler.h"
 #include "utils/builtins.h"
 #include "utils/inval.h"
@@ -296,6 +297,7 @@ parse_output_parameters(List *options, PGOutputData *data)
 	bool		messages_option_given = false;
 	bool		streaming_given = false;
 	bool		two_phase_option_given = false;
+	bool		slot_two_phase_option_given = false;
 	bool		slot_failover_option_given = false;
 	bool		origin_option_given = false;
 
@@ -304,6 +306,8 @@ parse_output_parameters(List *options, PGOutputData *data)
 	data->streaming = LOGICALREP_STREAM_OFF;
 	data->messages = false;
 	data->two_phase = false;
+	data->slot_two_phase = false;
+	data->slot_two_phase_set = false;
 	data->slot_failover = false;
 	data->slot_failover_set = false;
 	data->publish_no_origin = false;
@@ -399,6 +403,17 @@ parse_output_parameters(List *options, PGOutputData *data)
 
 			data->two_phase = defGetBoolean(defel);
 		}
+		else if (strcmp(defel->defname, "slot_two_phase") == 0)
+		{
+			if (slot_two_phase_option_given)
+				ereport(ERROR,
+						(errcode(ERRCODE_SYNTAX_ERROR),
+						 errmsg("conflicting or redundant options")));
+			slot_two_phase_option_given = true;
+
+			data->slot_two_phase = defGetBoolean(defel);
+			data->slot_two_phase_set = true;
+		}
 		else if (strcmp(defel->defname, "slot_failover") == 0)
 		{
 			if (slot_failover_option_given)
@@ -564,6 +579,18 @@ pgoutput_startup(LogicalDecodingContext *ctx, OutputPluginOptions *opt,
 		else
 			ctx->twophase_opt_given = true;
 
+		if (data->slot_two_phase_set &&
+			data->slot_two_phase != MyReplicationSlot->data.two_phase)
+			ereport(ERROR,
+					(errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
+					 errmsg("replication slot \"%s\" has two_phase %s",
+							NameStr(MyReplicationSlot->data.name),
+							MyReplicationSlot->data.two_phase ?
+							"enabled" : "disabled"),
+					 errdetail("The expected two_phase setting is %s.",
+							   data->slot_two_phase ?
+							   "enabled" : "disabled")));
+
 		if (data->slot_failover_set &&
 			data->slot_failover != MyReplicationSlot->data.failover)
 			ereport(ERROR,
diff --git a/src/include/replication/pgoutput.h b/src/include/replication/pgoutput.h
index 41d2be1be3c..0d0e8e8ecfb 100644
--- a/src/include/replication/pgoutput.h
+++ b/src/include/replication/pgoutput.h
@@ -33,6 +33,8 @@ typedef struct PGOutputData
 	char		streaming;
 	bool		messages;
 	bool		two_phase;
+	bool		slot_two_phase;
+	bool		slot_two_phase_set;
 	bool		slot_failover;
 	bool		slot_failover_set;
 	bool		publish_no_origin;
diff --git a/src/include/replication/walreceiver.h b/src/include/replication/walreceiver.h
index 36afc96553d..6d3615b0c80 100644
--- a/src/include/replication/walreceiver.h
+++ b/src/include/replication/walreceiver.h
@@ -186,6 +186,8 @@ typedef struct
 			char	   *streaming_str;	/* Streaming of large transactions */
 			bool		twophase;	/* Streaming of two-phase transactions at
 									 * prepare time */
+			bool		slot_twophase;	/* Expected slot two_phase state */
+			bool		slot_twophase_set;	/* Check slot two_phase state */
 			bool		slot_failover;	/* Expected slot failover state */
 			bool		slot_failover_set;	/* Check slot failover state */
 			char	   *origin; /* Only publish data originating from the
diff --git a/src/test/subscription/t/039_slot_properties.pl b/src/test/subscription/t/039_slot_properties.pl
index b771b5b493e..9403996934c 100644
--- a/src/test/subscription/t/039_slot_properties.pl
+++ b/src/test/subscription/t/039_slot_properties.pl
@@ -9,18 +9,25 @@ use Test::More;
 
 my $publisher = PostgreSQL::Test::Cluster->new('publisher');
 $publisher->init(allows_streaming => 'logical');
+$publisher->append_conf('postgresql.conf',
+	"max_prepared_transactions = 10\nlogical_decoding_work_mem = 64kB");
 $publisher->start;
 
 my $subscriber = PostgreSQL::Test::Cluster->new('subscriber');
 $subscriber->init;
+$subscriber->append_conf('postgresql.conf',
+		"max_prepared_transactions = 10\n"
+	  . "max_worker_processes = 20\n"
+	  . "max_logical_replication_workers = 10\n"
+	  . "max_parallel_apply_workers_per_subscription = 4");
 $subscriber->start;
 
 my $publisher_connstr = $publisher->connstr . ' dbname=postgres';
 
-# Recreate a logical slot with the requested failover property.
+# Recreate a logical slot with the requested properties.
 sub recreate_slot
 {
-	my ($slot_name, $failover) = @_;
+	my ($slot_name, $two_phase, $failover) = @_;
 
 	$publisher->safe_psql(
 		'postgres', qq[
@@ -28,7 +35,7 @@ sub recreate_slot
 		WHERE EXISTS (
 			SELECT FROM pg_replication_slots WHERE slot_name = '$slot_name');
 		SELECT pg_create_logical_replication_slot(
-			'$slot_name', 'pgoutput', false, false, $failover);
+			'$slot_name', 'pgoutput', false, $two_phase, $failover);
 	]);
 }
 
@@ -53,11 +60,171 @@ $publisher->safe_psql(
 
 $subscriber->safe_psql(
 	'postgres', q[
-	CREATE TABLE property_tab (a integer PRIMARY KEY, payload text);
+	CREATE SEQUENCE local_seq;
+	CREATE TABLE property_tab (
+		a integer PRIMARY KEY,
+		payload text,
+		local_value bigint DEFAULT nextval('local_seq'));
+]);
+
+my $subscriber_log_offset;
+
+# A pending two-phase subscription requires two-phase decoding to remain
+# disabled until all table synchronization workers have finished.
+recreate_slot('pending_slot', 'true', 'false');
+$subscriber->safe_psql(
+	'postgres', qq[
+	CREATE SUBSCRIPTION pending_sub
+	CONNECTION '$publisher_connstr application_name=pending_sub'
+	PUBLICATION property_pub
+	WITH (slot_name = 'pending_slot', create_slot = false,
+		  copy_data = true, enabled = false, two_phase = true,
+		  disable_on_error = true);
+]);
+
+is( $subscriber->safe_psql(
+		'postgres', q[
+		SELECT subtwophasestate = 'p' AND EXISTS (
+			SELECT FROM pg_subscription_rel
+			WHERE srsubid = pg_subscription.oid
+			AND srsubstate <> 'r')
+		FROM pg_subscription
+		WHERE subname = 'pending_sub';
+	]),
+	't',
+	'two-phase subscription is pending while table synchronization is incomplete'
+);
+
+$subscriber_log_offset = -s $subscriber->logfile;
+$subscriber->safe_psql('postgres', 'ALTER SUBSCRIPTION pending_sub ENABLE');
+$subscriber->wait_for_log(
+	qr/replication slot "pending_slot" has two_phase enabled/,
+	$subscriber_log_offset);
+
+$subscriber->poll_query_until(
+	'postgres', q[
+	SELECT NOT subenabled
+	FROM pg_subscription
+	WHERE subname = 'pending_sub';
+]) or die 'timed out waiting for pending_sub to be disabled';
+
+is( $subscriber->safe_psql(
+		'postgres', q[
+		SELECT subtwophasestate = 'p' AND EXISTS (
+			SELECT FROM pg_subscription_rel
+			WHERE srsubid = pg_subscription.oid
+			AND srsubstate <> 'r')
+		FROM pg_subscription
+		WHERE subname = 'pending_sub';
+	]),
+	't',
+	'two-phase subscription remains pending after the slot mismatch');
+
+wait_for_slot_inactive('pending_slot');
+$subscriber->safe_psql('postgres', 'DROP SUBSCRIPTION pending_sub');
+
+# A subscription without two-phase replication must reject a slot that can
+# send prepared transactions. In particular, it must do so before parallel
+# apply can execute subscriber-side defaults.
+recreate_slot('disabled_slot', 'true', 'false');
+$subscriber->safe_psql(
+	'postgres', qq[
+	CREATE SUBSCRIPTION disabled_sub
+	CONNECTION '$publisher_connstr application_name=disabled_sub'
+	PUBLICATION property_pub
+	WITH (slot_name = 'disabled_slot', create_slot = false,
+		  copy_data = false, enabled = false, two_phase = false,
+		  streaming = parallel, disable_on_error = true);
+]);
+
+$publisher->safe_psql(
+	'postgres', q[
+	BEGIN;
+	INSERT INTO property_tab
+	SELECT i, repeat(i::text, 1000)
+	FROM generate_series(1, 5000) AS i;
+	PREPARE TRANSACTION 'disabled_gid';
 ]);
 
+$subscriber_log_offset = -s $subscriber->logfile;
+$subscriber->safe_psql('postgres', 'ALTER SUBSCRIPTION disabled_sub ENABLE');
+$subscriber->wait_for_log(
+	qr/replication slot "disabled_slot" has two_phase enabled/,
+	$subscriber_log_offset);
+
+$subscriber->poll_query_until(
+	'postgres', q[
+	SELECT NOT subenabled
+	FROM pg_subscription
+	WHERE subname = 'disabled_sub';
+]) or die 'timed out waiting for disabled_sub to be disabled';
+$subscriber->poll_query_until(
+	'postgres', q[
+	SELECT apply_error_count > 0
+	FROM pg_stat_subscription_stats
+	WHERE subname = 'disabled_sub';
+]) or die 'timed out waiting for the apply error to be counted';
+
+is( $subscriber->safe_psql(
+		'postgres', 'SELECT last_value, is_called FROM local_seq'),
+	'1|f',
+	'subscriber-side defaults did not run before the mismatch error');
+is($subscriber->safe_psql('postgres', 'SELECT count(*) FROM property_tab'),
+	'0', 'no prepared transaction changes were applied');
+
+$publisher->safe_psql('postgres', "ROLLBACK PREPARED 'disabled_gid'");
+wait_for_slot_inactive('disabled_slot');
+$subscriber->safe_psql('postgres', 'DROP SUBSCRIPTION disabled_sub');
+
+# Once a subscription has enabled two-phase replication, it must reject a
+# replacement slot without two-phase decoding enabled.
+recreate_slot('enabled_slot', 'true', 'false');
+$subscriber->safe_psql(
+	'postgres', qq[
+	CREATE SUBSCRIPTION enabled_sub
+	CONNECTION '$publisher_connstr application_name=enabled_sub'
+	PUBLICATION property_pub
+	WITH (slot_name = 'enabled_slot', create_slot = false,
+		  copy_data = false, enabled = false, two_phase = true,
+		  disable_on_error = true);
+	ALTER SUBSCRIPTION enabled_sub ENABLE;
+]);
+
+$subscriber->poll_query_until(
+	'postgres', q[
+	SELECT subtwophasestate = 'e'
+	FROM pg_subscription
+	WHERE subname = 'enabled_sub';
+]) or die 'timed out waiting for two-phase replication to be enabled';
+
+$subscriber->safe_psql('postgres', 'ALTER SUBSCRIPTION enabled_sub DISABLE');
+wait_for_slot_inactive('enabled_slot');
+recreate_slot('enabled_slot', 'false', 'false');
+
+$subscriber_log_offset = -s $subscriber->logfile;
+$subscriber->safe_psql('postgres', 'ALTER SUBSCRIPTION enabled_sub ENABLE');
+$subscriber->wait_for_log(
+	qr/replication slot "enabled_slot" has two_phase disabled/,
+	$subscriber_log_offset);
+
+$subscriber->poll_query_until(
+	'postgres', q[
+	SELECT NOT subenabled
+	FROM pg_subscription
+	WHERE subname = 'enabled_sub';
+]) or die 'timed out waiting for enabled_sub to be disabled';
+$subscriber->poll_query_until(
+	'postgres', q[
+	SELECT apply_error_count > 0
+	FROM pg_stat_subscription_stats
+	WHERE subname = 'enabled_sub';
+]) or die 'timed out waiting for the apply error to be counted';
+
+wait_for_slot_inactive('enabled_slot');
+$subscriber->safe_psql('postgres', 'DROP SUBSCRIPTION enabled_sub');
+
 # A failover-enabled subscription requires a failover-enabled slot.
-recreate_slot('failover_slot', 'true');
+recreate_slot('failover_slot', 'false', 'true');
 $subscriber->safe_psql(
 	'postgres', qq[
 	CREATE SUBSCRIPTION failover_sub
@@ -78,9 +245,9 @@ $publisher->poll_query_until(
 
 $subscriber->safe_psql('postgres', 'ALTER SUBSCRIPTION failover_sub DISABLE');
 wait_for_slot_inactive('failover_slot');
-recreate_slot('failover_slot', 'false');
+recreate_slot('failover_slot', 'false', 'false');
 
-my $subscriber_log_offset = -s $subscriber->logfile;
+$subscriber_log_offset = -s $subscriber->logfile;
 $subscriber->safe_psql('postgres', 'ALTER SUBSCRIPTION failover_sub ENABLE');
 $subscriber->wait_for_log(
 	qr/replication slot "failover_slot" has failover disabled/,
@@ -104,7 +271,7 @@ wait_for_slot_inactive('failover_slot');
 $subscriber->safe_psql('postgres', 'DROP SUBSCRIPTION failover_sub');
 
 # A subscription without failover enabled must reject a failover-enabled slot.
-recreate_slot('extra_failover_slot', 'true');
+recreate_slot('extra_failover_slot', 'false', 'true');
 $subscriber->safe_psql(
 	'postgres', qq[
 	CREATE SUBSCRIPTION extra_failover_sub
-- 
2.47.3

