Wire --region through CLI, fix extension versioning, add 3-DC stall test

- Thread --region option (-G) through all three pg_autoctl create postgres
  long_options arrays in cli_create_node.c, central option parsing in
  cli_common.c (case 'G'), keeper_config KeeperConfig.region field,
  nodespec.c ini/argv builder, and monitor_register_node() SQL call ().

- Bump extension version to 2.3 consistently: Makefile EXTVERSION, metadata.h
  AUTO_FAILOVER_EXTENSION_VERSION, and pgautofailover.control already at 2.3.
  Add pgautofailover--2.3--dummy.sql upgrade path for dummy_update regress test.
  Update dummy_update.out expected DETAIL line to say '2.3'.

- Fix monitor regress test ordering: add ORDER BY nodeid to the unordered
  SELECT from pgautofailover.node so the result is deterministic regardless
  of heap page layout (wider rows from new region/replication_stall_since
  columns changed physical scan order).

- Update watch_colspecs.h MAX_COL_SPECS 12→14 to accommodate the new
  COLUMN_TYPE_REGION entry plus COLUMN_TYPE_LAST sentinel in the fully-verbose
  column policy (13 entries total).

- Add pgaftest DSL support for 'region <name>' node option: T_REGION token in
  lexer, grammar rule in parser, TestNode.region field, compose_gen writes
  --region flag, cli_indent pretty-prints it.

- Add tests/tap/specs/replication_stall_3dc.pgaf: 2-node cluster across
  dc1/dc2 regions; cuts network to node2, waits for node1 to reach
  wait_primary (FSM rule fires after replication_stall_timeout), then
  restores connectivity and waits for secondary recovery.

Author: dimitri

src/bin/pg_autoctl/cli_common.c

@@ -407,6 +407,14 @@ cli_common_keeper_getopts(int argc, char **argv,
 				break;
 			}
 
+			case 'G':
+			{
+				/* { "region", required_argument, NULL, 'G' } */
+				strlcpy(LocalOptionConfig.region, optarg, NAMEDATALEN);
+				log_trace("--region %s", LocalOptionConfig.region);
+				break;
+			}
+
 			case 'V':
 			{
 				/* keeper_cli_print_version prints version and exits. */

src/bin/pg_autoctl/cli_create_node.c

@@ -343,6 +343,7 @@ cli_create_postgres_getopts(int argc, char **argv)
 		{ "candidate-priority", required_argument, NULL, 'P' },
 		{ "replication-quorum", required_argument, NULL, 'r' },
 		{ "maximum-backup-rate", required_argument, NULL, 'R' },
+		{ "region", required_argument, NULL, 'G' },
 		{ "run", no_argument, NULL, 'x' },
 		{ "no-ssl", no_argument, NULL, 'N' },
 		{ "ssl-self-signed", no_argument, NULL, 's' },
@@ -356,7 +357,7 @@ cli_create_postgres_getopts(int argc, char **argv)
 
 	int optind =
 		cli_create_node_getopts(argc, argv, long_options,
-								"C:D:H:p:l:U:A:SLd:a:n:f:m:MI:W:w:RVvqhP:r:xsN",
+								"C:D:H:p:l:U:A:SLd:a:n:f:m:MI:W:w:RGVvqhP:r:xsN",
 								&options);
 
 	/* publish our option parsing in the global variable */
@@ -441,6 +442,7 @@ cli_create_coordinator_getopts(int argc, char **argv)
 		{ "citus-cluster", required_argument, NULL, 'Z' },
 		{ "candidate-priority", required_argument, NULL, 'P' },
 		{ "replication-quorum", required_argument, NULL, 'r' },
+		{ "region", required_argument, NULL, 'G' },
 		{ "run", no_argument, NULL, 'x' },
 		{ "no-ssl", no_argument, NULL, 'N' },
 		{ "ssl-self-signed", no_argument, NULL, 's' },
@@ -454,7 +456,7 @@ cli_create_coordinator_getopts(int argc, char **argv)
 
 	int optind =
 		cli_create_node_getopts(argc, argv, long_options,
-								"C:D:H:p:l:U:A:SLd:a:n:f:m:MRVvqhzZ:P:r:xsN",
+								"C:D:H:p:l:U:A:SLd:a:n:f:m:MRGVvqhzZ:P:r:xsN",
 								&options);
 
 	options.groupId = 0;
@@ -551,6 +553,7 @@ cli_create_worker_getopts(int argc, char **argv)
 		{ "citus-cluster", required_argument, NULL, 'Z' },
 		{ "candidate-priority", required_argument, NULL, 'P' },
 		{ "replication-quorum", required_argument, NULL, 'r' },
+		{ "region", required_argument, NULL, 'G' },
 		{ "run", no_argument, NULL, 'x' },
 		{ "no-ssl", no_argument, NULL, 'N' },
 		{ "ssl-self-signed", no_argument, NULL, 's' },
@@ -564,7 +567,7 @@ cli_create_worker_getopts(int argc, char **argv)
 
 	int optind =
 		cli_create_node_getopts(argc, argv, long_options,
-								"C:D:H:p:l:y:zZ:U:A:SLd:a:n:f:m:MRVvqhzP:r:xsN",
+								"C:D:H:p:l:y:zZ:U:A:SLd:a:n:f:m:MRGVvqhzP:r:xsN",
 								&options);
 
 	if (options.groupId == 0)

src/bin/pg_autoctl/defaults.h

@@ -19,7 +19,7 @@
 #define PG_AUTOCTL_VERSION GIT_VERSION
 
 /* version of the extension that we requite to talk to on the monitor */
-#define PG_AUTOCTL_EXTENSION_VERSION "2.2"
+#define PG_AUTOCTL_EXTENSION_VERSION "2.3"
 
 /* environment variable to use to make DEBUG facilities available */
 #define PG_AUTOCTL_DEBUG "PG_AUTOCTL_DEBUG"

src/bin/pg_autoctl/keeper.c

@@ -1670,6 +1670,7 @@ keeper_register_and_init(Keeper *keeper, NodeState initialState)
 								  config->pgSetup.settings.candidatePriority,
 								  config->pgSetup.settings.replicationQuorum,
 								  config->pgSetup.citusClusterName,
+								  config->region,
 								  &mayRetry,
 								  &assignedState))
 		{
@@ -1875,6 +1876,7 @@ keeper_register_again(Keeper *keeper)
 								  config->pgSetup.settings.candidatePriority,
 								  config->pgSetup.settings.replicationQuorum,
 								  DEFAULT_CITUS_CLUSTER_NAME,
+								  config->region,
 								  &mayRetry,
 								  &assignedState))
 		{

src/bin/pg_autoctl/keeper_config.c

@@ -61,6 +61,10 @@
 	make_strbuf_option("pg_autoctl", "nodekind", NULL, false, NAMEDATALEN, \
 					   config->nodeKind)
 
+#define OPTION_AUTOCTL_REGION(config) \
+	make_strbuf_option_default("pg_autoctl", "region", "region", \
+							   false, NAMEDATALEN, config->region, "")
+
 #define OPTION_POSTGRESQL_PGDATA(config) \
 	make_strbuf_option("postgresql", "pgdata", "pgdata", true, MAXPGPATH, \
 					   config->pgSetup.pgdata)
@@ -227,6 +231,7 @@
 		OPTION_AUTOCTL_HOSTNAME(config), \
 		OPTION_AUTOCTL_NODENAME(config), \
 		OPTION_AUTOCTL_NODEKIND(config), \
+		OPTION_AUTOCTL_REGION(config), \
 		OPTION_POSTGRESQL_PGDATA(config), \
 		OPTION_POSTGRESQL_PG_CTL(config), \
 		OPTION_POSTGRESQL_USERNAME(config), \

src/bin/pg_autoctl/keeper_config.h

@@ -46,6 +46,7 @@ typedef struct KeeperConfig
 	char name[_POSIX_HOST_NAME_MAX];
 	char hostname[_POSIX_HOST_NAME_MAX];
 	char nodeKind[NAMEDATALEN];
+	char region[NAMEDATALEN];
 
 	/* PostgreSQL setup */
 	PostgresSetup pgSetup;

src/bin/pg_autoctl/monitor.c

@@ -861,19 +861,20 @@ monitor_register_node(Monitor *monitor, char *formation,
 					  NodeState initialState,
 					  PgInstanceKind kind, int candidatePriority, bool quorum,
 					  char *citusClusterName,
+					  char *region,
 					  bool *mayRetry,
 					  MonitorAssignedState *assignedState)
 {
 	PGSQL *pgsql = &monitor->pgsql;
 	const char *sql =
 		"SELECT * FROM pgautofailover.register_node($1, $2, $3, $4, $5, $6, $7, "
-		"$8, $9::pgautofailover.replication_state, $10, $11, $12, $13)";
-	int paramCount = 13;
-	Oid paramTypes[13] = {
+		"$8, $9::pgautofailover.replication_state, $10, $11, $12, $13, $14)";
+	int paramCount = 14;
+	Oid paramTypes[14] = {
 		TEXTOID, TEXTOID, INT4OID, NAMEOID, TEXTOID, INT8OID,
-		INT8OID, INT4OID, TEXTOID, TEXTOID, INT4OID, BOOLOID, TEXTOID
+		INT8OID, INT4OID, TEXTOID, TEXTOID, INT4OID, BOOLOID, TEXTOID, TEXTOID
 	};
-	const char *paramValues[13];
+	const char *paramValues[14];
 	MonitorAssignedStateParseContext parseContext =
 	{ { 0 }, assignedState, false };
 	const char *nodeStateString = NodeStateToString(initialState);
@@ -899,6 +900,10 @@ monitor_register_node(Monitor *monitor, char *formation,
 		IS_EMPTY_STRING_BUFFER(citusClusterName)
 		? DEFAULT_CITUS_CLUSTER_NAME
 		: citusClusterName;
+	paramValues[13] =
+		IS_EMPTY_STRING_BUFFER(region)
+		? "default"
+		: region;
 
 	if (!pgsql_execute_with_params(pgsql, sql,
 								   paramCount, paramTypes, paramValues,

src/bin/pg_autoctl/monitor.h

@@ -140,6 +140,7 @@ bool monitor_register_node(Monitor *monitor,
 						   int candidatePriority,
 						   bool quorum,
 						   char *citusClusterName,
+						   char *region,
 						   bool *mayRetry,
 						   MonitorAssignedState *assignedState);
 bool monitor_node_active(Monitor *monitor,

src/bin/pg_autoctl/nodespec.c

@@ -114,6 +114,9 @@ nodespec_read(const char *path, NodeSpec *spec)
 		make_strbuf_option_default("settings", "replication_quorum", NULL, false,
 								   sizeof(replicationQuorumStr),
 								   replicationQuorumStr, "true"),
+		make_strbuf_option_default("settings", "region", NULL, false,
+								   sizeof(spec->region), spec->region,
+								   ""),
 
 		/* [options] — immutable, used only at create time */
 		make_strbuf_option_default("options", "ssl", NULL, false,
@@ -694,6 +697,13 @@ nodespec_create_argv(const NodeSpec *spec,
 			PUSH("false");
 		}
 
+		/* region label (omit when empty — monitor defaults to "default") */
+		if (!IS_EMPTY_STRING_BUFFER(spec->region))
+		{
+			PUSH("--region");
+			PUSH(spec->region);
+		}
+
 		/* Citus secondary/read-replica cluster settings */
 		if (spec->citusSecondary)
 		{

src/bin/pg_autoctl/nodespec.h

@@ -71,6 +71,7 @@ typedef struct NodeSpec
 	/* [settings]  — mutable; applied on SIGHUP / file change */
 	int candidate_priority;      /* 0-100, default 50 */
 	bool replication_quorum;     /* sync quorum participant, default true */
+	char region[NAMEDATALEN];    /* data-centre / availability zone label */
 
 	/* [options]    — immutable; used only at pg_autoctl create time */
 	char ssl[32];                /* self-signed | verify-ca | verify-full | off */