Spock documentation improvement attempt

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_node_create.md

@@ -5,17 +5,26 @@
 ### SYNOPSIS
 
 `spock.node_create (node_name name, dsn text, location text, country text, info jsonb)`
- 
+
 ### DESCRIPTION
 
-Create a spock node. 
+Create a spock node.
+    Initialize internal state of the spock extension that will be used further in communications with other replication participants to identify the node and connection settings.
+	It doesn't check correctness or reachability of the dsn at the moment.
+	Parameters 'location', 'country', and 'info' are optional and is intended for simplifying automatisation infrastructure.
 
-### EXAMPLE 
+### EXAMPLE
 
 `spock.node_create ('n1', 'host=10.1.2.5 user=rocky dbname=demo')`
- 
-### POSITIONAL ARGUMENTS
+
+### ARGUMENTS
     node_name
-        The name of the node. Only one node is allowed per database, and each node in a cluster must have a unique name. To use the Snowflake extension, use the convention n1,n2, etc. Example: n1
+        The name of the node. Only one node is allowed per database, and each node in a cluster must have a unique name. Example: n1
     dsn
         The connection string to the node. The user in this string should equal the OS user. This connection string should be reachable from outside and match the one used later in the sub-create command. Example: host=10.1.2.5 port= 5432 user=rocky dbname=demo
+	location
+		(optional) Text string identifying the node location as precise as needed. Doesn't affect any internal logic.
+    country
+        (optional) Text string dedicated to conveniently store and expose the country code where the spock node is located. Doesn't affect any internal logic.
+	info
+		(optional) JSONB field where arbitrary meta information may be stored in structured form. The only optional field that affects the spock behaviour is the 'tiebreaker' integer value that serves as a priority value (less value - more priority) that is used in conflict resolution cases in case commit timestamp is the same for all the concurrent transactions updating the same row.

docs/spock_functions/functions/spock_node_drop.md

@@ -5,14 +5,14 @@
 ### SYNOPSIS
 
 `spock.node_drop (node_name name, ifexists bool)`
- 
+
 ### DESCRIPTION
-    Drop a spock node. 
+    Drop a spock node. Beforehand, any subscriptions on remote spock nodes must be deleted by the 'sub_drop' function as well as any subscriptions on the dropping node.
 
-### EXAMPLE 
+### EXAMPLE
 
 `spock.node_drop ('n1')`
- 
+
 ### POSITIONAL ARGUMENTS
     node_name
         The name of the node. Example: n1

docs/spock_functions/functions/spock_sub_create.md

@@ -4,35 +4,38 @@
 
 ### SYNOPSIS
 
-`spock.sub_create (subscription_name name, provider_dsn text, repsets text[], sync_structure boolean,
-  sync_data boolean, forward_origins text[], apply_delay interval)`
-
+`spock.sub_create (subscription_name name, provider_dsn text, replication_sets text[], synchronize_structure boolean, synchronize_data boolean, forward_origins text[], apply_delay interval, force_text_transfer boolean, enabled boolean, skip_schema text[])`
+
 ### DESCRIPTION
 
-Creates a subscription from current node to the provider node. The command does not wait for completion before returning to the caller.
+Creates a subscription from current node to the provider node. The command does not wait for completion before returning to the caller. Needs preliminary call of the `spock.node_create`.
 
 The `subscription_name` is used as `application_name` by the replication connection. This means that it's visible in the `pg_stat_replication` monitoring view. It can also be used in `synchronous_standby_names` when Spock is used as part of a synchronous replication scenario.
 
 Use `spock.sub_wait_for_sync(subscription_name)` to wait for the subscription to asynchronously start replicating and complete any needed schema and/or data sync.
 
-### EXAMPLE 
+### EXAMPLE
 
 `spock.sub_create ('sub_n2n1', 'host=10.1.2.5 port=5432 user=rocky dbname=demo')`
- 
+
 ### ARGUMENTS
-    subscription_name 
-        The name of the subscription. Each subscription in a cluster must have a unique name.  The name is used as application_name by the replication connection. This means that the name is visible in the pg_stat_replication monitoring view. 
-    provider_dsn 
+    subscription_name
+        The name of the subscription. Each subscription in a cluster must have a unique name.  The name is used as application_name by the replication connection. This means that the name is visible in the pg_stat_replication monitoring view.
+    provider_dsn
         The connection string to a provider.
-    repsets
+    replication_sets
         An array of existing replication sets to subscribe to; the default is {default,default_insert_only,ddl_sql}.
-    sync_structure
+    synchronize_structure
         Specifies if Spock should synchronize the structure from provider to the subscriber; the default is false.
-    sync_data 
+    synchronize_data
         Specifies if Spock should synchronize data from provider to the subscriber, the default is true.
     forward_origins
         An array of origin names to forward; currently the only supported values are an empty array (don't forward any changes that didn't originate on provider node, useful for two-way replication between the nodes), or {all} which means replicate all changes no matter what is their origin. The default is {all}.
     apply_delay
         How much to delay replication; the default is 0 seconds.
     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 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_drop.md

@@ -5,16 +5,16 @@
 ### SYNOPSIS
 
 `spock.sub_drop (subscription_name name, ifexists bool)`
- 
+
 ### DESCRIPTION
 
-Disconnects the subscription and removes it from the catalog. 
+Disconnects the subscription and removes it from the catalog.
 
 ### EXAMPLE
 
 `spock.sub_drop ('sub_n2n1')`
- 
-### POSITIONAL ARGUMENTS
+
+### ARGUMENTS
     subscription_name
         The name of the existing subscription.
     ifexists

docs/spock_functions/functions/spock_sub_resync_table.md

@@ -4,18 +4,20 @@
 
 ### SYNOPSIS
 
-`spock.sub_resync_table (subscription_name name, relation regclass)`
- 
+`spock.sub_resync_table (subscription_name name, relation regclass, truncate boolean)`
+
 ### DESCRIPTION
 
-Resynchronize one existing table. 
+Resynchronize one existing table.
 
 ### EXAMPLE
 
-`spock.sub-resync-table ('sub_n2n1', 'mytable')`
- 
+`spock.sub_resync_table ('sub_n2n1', 'mytable')`
+
 ### POSITIONAL ARGUMENTS
     subscription_name
         The name of the existing subscription.
     relation
         The name of existing table, optionally schema qualified.
+	truncate
+		Truncate table on the subscriber before re-synchronization. In the `false` state any rows, coming from the publisher will be applied other existing state, causing conflicts. The default value is true.

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`.

docs/spock_functions/index.md

@@ -44,7 +44,6 @@ The following user functions are available via the Spock extension:
 | spock.spock_version | Returns the Spock version in a major/minor version form: `4.0.10`.
 | spock.spock_version_num | Returns the Spock version in a single numeric form: `40010`.
 | spock.get_channel_stats | Returns tuple traffic statistics.
-| spock.get_country | Returns the country code if explicitly set; returns `??` if not set.
 | spock.lag_tracker | Returns a list of slots, with commit_lsn and commit_timestamp for each.
 | spock.repair_mode | Used to manage the state of replication - If set to `true`, stops replicating statements; when `false`, resumes replication.
 | spock.replicate_ddl | Replicate a specific statement.