Here we revise docs on sub_disable, sub_enable, and sub_show_status functions.

Some minor typos and trailed whitespaces fixed here and there in the code.
Also, this commit commences restructurisation of the UI .sql script to make it
a little more readable and synced with the docs/spock_functions.md.

Author: danolivo

Makefile

@@ -195,7 +195,7 @@ set -e -u -x
 # If you don't want leak checking, use --leak-check=no
 #
 # When just doing leak checking and not looking for detailed memory error reports you don't need:
-# 	--track-origins=yes --read-var-info=yes --malloc-fill=8f --free-fill=9f 
+# 	--track-origins=yes --read-var-info=yes --malloc-fill=8f --free-fill=9f
 #
 SUPP=$(POSTGRES_SRC)/src/tools/valgrind.supp
 

docs/spock_functions/functions/spock_sub_create.md

@@ -36,6 +36,6 @@ Use `spock.sub_wait_for_sync(subscription_name)` to wait for the subscription to
     force_text_transfer
         Force the provider to replicate all columns using a text representation (which is slower, but may be used to change the type of a replicated column on the subscriber). The default is false.
 	enabled
-		If true, it signals replication machinery to activate synchronisation of schema/data from the publisher. If false, the node synchronisation status is set to ready, no active sync The default is true.
+		If true, it signals replication machinery to activate synchronisation of schema/data from the publisher. If false, the node synchronisation status is set to ready, no synchronization will be made (TODO: refer to a correct use case). The default is true.
 	skip_schema
 		Array of schema names that will be skipped during the structure synchronisation. Data from any table, included in these schemas will be filtered at initial data synchronisation. The default is NULL.

docs/spock_functions/functions/spock_sub_disable.md

@@ -1,21 +1,20 @@
-## NAME 
+## NAME
 
 `spock.sub_disable ()`
 
 ### SYNOPSIS
 
 `spock.sub_disable (subscription_name name, immediate boolean)`
- 
+
 ### DESCRIPTION
-    Disable a subscription by putting it on hold and disconnect from provider. 
+    Disable a subscription by putting it on hold and disconnect from provider.
 
 ### EXAMPLE
 
-`spock sub_disable 'sub_n2n1'`
- 
+`spock sub_disable('sub_n2n1')`
+
 ### ARGUMENTS
     subscription_name
         The name of the existing subscription.
     immediate
         If true, the subscription is stopped immediately, otherwise it will be only stopped at the end of current transaction; the default is false.
- 

docs/spock_functions/functions/spock_sub_show_status.md

@@ -5,15 +5,29 @@
 ### SYNOPSIS
 
 `spock.sub_show_status (subscription_name name)`
- 
+
 ### DESCRIPTION
 
-Show the status and basic information of a subscription. 
+Show the status and basic information of a subscription.
 
 ### EXAMPLE
 
 `spock.sub_show_status ('sub_n2n1')`
- 
+
 ### ARGUMENTS
     subscription_name
         The optional name of the existing subscription.  If no name is provided, the function will show status for all subscriptions on the local node.
+
+### RETURN
+
+Returns one record per subscription with the following columns:
+
+* `subscription_name text`,
+* `status text`,
+* `provider_node text`,
+* `provider_dsn text`,
+* `slot_name text`,
+* `replication_sets text[]`,
+* `forward_origins text[]`
+
+Column `status` may have one of the following values: `unknown`, `replicating`, `initializing`, `disabled`, or `down`.

sql/spock--6.0.0-devel.sql

@@ -106,6 +106,10 @@ CREATE TABLE spock.progress (
 	PRIMARY KEY(node_id, remote_node_id)
 ) WITH (fillfactor=50);
 
+--
+-- Node Management Functions
+--
+
 CREATE FUNCTION spock.node_create(
 	node_name name,
 	dsn text,
@@ -117,6 +121,31 @@ RETURNS oid CALLED ON NULL INPUT VOLATILE
 AS 'MODULE_PATHNAME', 'spock_create_node'
 LANGUAGE C;
 
+CREATE FUNCTION spock.node_drop(
+	node_name name,
+	ifexists boolean DEFAULT false
+)
+RETURNS boolean
+AS 'MODULE_PATHNAME', 'spock_drop_node'
+LANGUAGE C STRICT VOLATILE;
+
+CREATE FUNCTION spock.node_info(
+	OUT node_id oid,
+	OUT node_name text,
+    OUT sysid text,
+	OUT dbname text,
+	OUT replication_sets text,
+    OUT location text,
+	OUT country text,
+	OUT info jsonb)
+RETURNS record
+AS 'MODULE_PATHNAME', 'spock_node_info'
+LANGUAGE C STABLE STRICT;
+
+--
+-- SSubscription Management Functions
+--
+
 CREATE FUNCTION spock.sub_create(
 	subscription_name name,
 	provider_dsn text,
@@ -141,23 +170,64 @@ RETURNS oid
 AS 'MODULE_PATHNAME', 'spock_drop_subscription'
 LANGUAGE C STRICT VOLATILE;
 
-CREATE FUNCTION spock.node_drop(node_name name, ifexists boolean DEFAULT false)
+CREATE FUNCTION spock.sub_disable(
+	subscription_name name,
+	immediate boolean DEFAULT false
+)
 RETURNS boolean
-AS 'MODULE_PATHNAME', 'spock_drop_node'
+AS 'MODULE_PATHNAME', 'spock_alter_subscription_disable'
 LANGUAGE C STRICT VOLATILE;
 
-CREATE FUNCTION spock.node_add_interface(node_name name, interface_name name, dsn text)
-RETURNS oid STRICT VOLATILE LANGUAGE c AS 'MODULE_PATHNAME', 'spock_alter_node_add_interface';
-CREATE FUNCTION spock.node_drop_interface(node_name name, interface_name name)
-RETURNS boolean STRICT VOLATILE LANGUAGE c AS 'MODULE_PATHNAME', 'spock_alter_node_drop_interface';
+CREATE FUNCTION spock.sub_enable(
+	subscription_name name,
+	immediate boolean DEFAULT false
+)
+RETURNS boolean
+AS 'MODULE_PATHNAME', 'spock_alter_subscription_enable'
+LANGUAGE C  STRICT VOLATILE;
+
+CREATE FUNCTION spock.sub_show_status(
+	subscription_name name DEFAULT NULL,
+    OUT subscription_name text,
+	OUT status text,
+	OUT provider_node text,
+    OUT provider_dsn text,
+	OUT slot_name text,
+	OUT replication_sets text[],
+    OUT forward_origins text[]
+)
+RETURNS SETOF record
+AS 'MODULE_PATHNAME', 'spock_show_subscription_status'
+LANGUAGE C STABLE;
 
-CREATE FUNCTION spock.sub_alter_interface(subscription_name name, interface_name name)
-RETURNS boolean STRICT VOLATILE LANGUAGE c AS 'MODULE_PATHNAME', 'spock_alter_subscription_interface';
+--
+-- Additional interface management routines for complex network configurations
+--
+
+CREATE FUNCTION spock.node_add_interface(
+	node_name name,
+	interface_name name,
+	dsn text
+)
+RETURNS oid
+AS 'MODULE_PATHNAME', 'spock_alter_node_add_interface'
+LANGUAGE C STRICT VOLATILE;
+
+CREATE FUNCTION spock.sub_alter_interface(
+	subscription_name name,
+	interface_name name
+)
+RETURNS boolean
+AS 'MODULE_PATHNAME', 'spock_alter_subscription_interface'
+LANGUAGE C STRICT VOLATILE;
 
-CREATE FUNCTION spock.sub_disable(subscription_name name, immediate boolean DEFAULT false)
-RETURNS boolean STRICT VOLATILE LANGUAGE c AS 'MODULE_PATHNAME', 'spock_alter_subscription_disable';
-CREATE FUNCTION spock.sub_enable(subscription_name name, immediate boolean DEFAULT false)
-RETURNS boolean STRICT VOLATILE LANGUAGE c AS 'MODULE_PATHNAME', 'spock_alter_subscription_enable';
+CREATE FUNCTION spock.node_drop_interface(
+	node_name name,
+	interface_name name
+)
+RETURNS boolean
+AS 'MODULE_PATHNAME', 'spock_alter_node_drop_interface'
+LANGUAGE C STRICT VOLATILE;
 
 CREATE FUNCTION spock.sub_add_repset(subscription_name name, replication_set name)
 RETURNS boolean STRICT VOLATILE LANGUAGE c AS 'MODULE_PATHNAME', 'spock_alter_subscription_add_replication_set';
@@ -166,12 +236,6 @@ RETURNS boolean STRICT VOLATILE LANGUAGE c AS 'MODULE_PATHNAME', 'spock_alter_su
 CREATE FUNCTION spock.sub_alter_skiplsn(subscription_name name, lsn pg_lsn)
 	RETURNS boolean STRICT VOLATILE LANGUAGE c AS 'MODULE_PATHNAME', 'spock_alter_subscription_skip_lsn';
 
-CREATE FUNCTION spock.sub_show_status(subscription_name name DEFAULT NULL,
-    OUT subscription_name text, OUT status text, OUT provider_node text,
-    OUT provider_dsn text, OUT slot_name text, OUT replication_sets text[],
-    OUT forward_origins text[])
-RETURNS SETOF record STABLE LANGUAGE c AS 'MODULE_PATHNAME', 'spock_show_subscription_status';
-
 CREATE TABLE spock.replication_set (
     set_id oid NOT NULL PRIMARY KEY,
     set_nodeid oid NOT NULL REFERENCES node(node_id) ON UPDATE CASCADE,
@@ -280,6 +344,10 @@ CREATE VIEW spock.TABLES AS
       FROM user_tables t
      WHERE t.oid NOT IN (SELECT set_reloid FROM set_relations);
 
+--
+-- Replication Set Management Functions
+--
+
 CREATE FUNCTION spock.repset_create(set_name name,
     replicate_insert boolean = true, replicate_update boolean = true,
     replicate_delete boolean = true, replicate_truncate boolean = true)
@@ -354,12 +422,6 @@ CREATE FUNCTION spock.replicate_ddl(command text[],
 RETURNS SETOF boolean STRICT VOLATILE LANGUAGE sql AS
     'SELECT spock.replicate_ddl(cmd, $2, $3, $4) FROM (SELECT unnest(command) cmd)';
 
-CREATE FUNCTION spock.node_info(OUT node_id oid, OUT node_name text,
-    OUT sysid text, OUT dbname text, OUT replication_sets text,
-    OUT location text, OUT country text, OUT info jsonb)
-RETURNS record
-STABLE STRICT LANGUAGE c AS 'MODULE_PATHNAME', 'spock_node_info';
-
 CREATE FUNCTION spock.spock_gen_slot_name(name, name, name)
 RETURNS name
 IMMUTABLE STRICT LANGUAGE c AS 'MODULE_PATHNAME';

src/spock_functions.c

@@ -636,7 +636,8 @@ spock_create_subscription(PG_FUNCTION_ARGS)
 /*
  * Remove subscribption.
  */
-Datum spock_drop_subscription(PG_FUNCTION_ARGS)
+Datum
+spock_drop_subscription(PG_FUNCTION_ARGS)
 {
 	char *sub_name = NameStr(*PG_GETARG_NAME(0));
 	bool ifexists = PG_GETARG_BOOL(1);
@@ -741,14 +742,15 @@ Datum spock_drop_subscription(PG_FUNCTION_ARGS)
 /*
  * Disable subscription.
  */
-Datum spock_alter_subscription_disable(PG_FUNCTION_ARGS)
+Datum
+spock_alter_subscription_disable(PG_FUNCTION_ARGS)
 {
 	char *sub_name = NameStr(*PG_GETARG_NAME(0));
 	bool immediate = PG_GETARG_BOOL(1);
 	SpockSubscription *sub = get_subscription_by_name(sub_name, false);
 
 	/* XXX: Only used for locking purposes. */
-	(void)get_local_node(true, false);
+	(void) get_local_node(true, false);
 
 	sub->enabled = false;
 
@@ -1117,7 +1119,8 @@ Datum spock_show_subscription_table(PG_FUNCTION_ARGS)
 /*
  * Show info about subscribtion.
  */
-Datum spock_show_subscription_status(PG_FUNCTION_ARGS)
+Datum
+spock_show_subscription_status(PG_FUNCTION_ARGS)
 {
 	List *subscriptions;
 	ListCell *lc;
@@ -2274,7 +2277,8 @@ Datum spock_dependency_check_trigger(PG_FUNCTION_ARGS)
 	PG_RETURN_VOID();
 }
 
-Datum spock_node_info(PG_FUNCTION_ARGS)
+Datum
+spock_node_info(PG_FUNCTION_ARGS)
 {
 	TupleDesc tupdesc;
 	Datum values[8];

src/spock_manager.c

@@ -93,7 +93,7 @@ manage_apply_workers(void)
 		if (!wlc)
 			apply = NULL;
 
-		/* Skip if the worker was alrady registered. */
+		/* Skip if the worker was already registered. */
 		if (spock_worker_running(apply))
 			continue;