DOC: Updates to spock content

docs/install_spock.md

@@ -111,7 +111,8 @@ Also, you will need to configure your `pg_hba.conf` file to allow logical
 replication connections from localhost. Logical replication connections are
 treated by `pg_hba.conf` as regular connections to the provider database.
 
-Then, use the `spock.node_create` command to create the provider node:
+Then, connect to the psql command line of the first provider node, and use 
+the `spock.node_create` command to create the provider node:
 
 ```sql
     SELECT spock.node_create(

docs/spock_functions/functions/spock_gen_slot_name.md

@@ -0,0 +1,43 @@
+## NAME
+
+spock.spock_gen_slot_name()
+
+### SYNOPSIS
+
+spock.spock_gen_slot_name (dbname name, provider_node name,
+subscription name)
+
+### RETURNS
+
+The generated replication slot name as a name type.
+
+### DESCRIPTION
+
+Generates a standardized replication slot name for a Spock subscription.
+
+This function creates a consistent naming convention for replication slots
+based on the database name, provider node name, and subscription name. The
+generated name follows Spock's internal naming scheme to ensure uniqueness
+and traceability.
+
+This is a pure function that performs a calculation without accessing the
+database or modifying any data. It can be used to predict what slot name
+Spock will generate for a given subscription configuration.
+
+### ARGUMENTS
+
+dbname
+
+    The name of the database.
+
+provider_node
+
+    The name of the provider node.
+
+subscription
+
+    The name of the subscription.
+
+### EXAMPLE
+
+SELECT spock.spock_gen_slot_name('postgres', 'n1', 'sub_n2_n1');

docs/spock_functions/functions/spock_get_country.md

@@ -0,0 +1,38 @@
+## NAME
+
+spock.get_country()
+
+### SYNOPSIS
+
+spock.get_country ()
+
+### RETURNS
+
+The country code configured for the current session as text, or an error if
+not set.
+
+### DESCRIPTION
+
+Returns the country code that has been configured for the current database
+session.
+
+This function retrieves the value of the spock.country configuration
+parameter for the current session. The country code is typically used in
+multi-region or geo-distributed replication topologies to identify the
+geographic location of nodes and apply region-specific routing or filtering
+rules.
+
+The country code must be set using PostgreSQL's SET command or in the
+session configuration before calling this function. If the spock.country
+parameter has not been set, this function will raise an error.
+
+This is a read-only query function that does not modify any data.
+
+### ARGUMENTS
+
+This function takes no arguments.
+
+### EXAMPLE
+
+SET spock.country = 'US';
+SELECT spock.get_country();

docs/spock_functions/functions/spock_max_proto_version.md

@@ -0,0 +1,39 @@
+## NAME
+
+spock.spock_max_proto_version()
+
+### SYNOPSIS
+
+spock.spock_max_proto_version ()
+
+### RETURNS
+
+The maximum protocol version supported by the installed Spock extension as
+an integer.
+
+### DESCRIPTION
+
+Returns the maximum protocol version supported by the Spock extension.
+
+This function queries the Spock extension and returns the highest protocol
+version number it can use for replication communication. The protocol
+version determines the features and capabilities available for replication
+between nodes.
+
+When establishing replication connections between nodes running different
+Spock versions, the nodes negotiate to use the lower of the two maximum
+protocol versions. This ensures compatibility between nodes running
+different Spock releases.
+
+The protocol version is returned as an integer value. Higher numbers
+indicate newer protocol versions with additional features.
+
+This is a read-only query function that does not modify any data.
+
+### ARGUMENTS
+
+This function takes no arguments.
+
+### EXAMPLE
+
+SELECT spock.spock_max_proto_version();

docs/spock_functions/functions/spock_min_proto_version.md

@@ -0,0 +1,41 @@
+## NAME
+
+spock.spock_min_proto_version()
+
+### SYNOPSIS
+
+spock.spock_min_proto_version ()
+
+### RETURNS
+
+The minimum protocol version supported by the installed Spock extension as
+an integer.
+
+### DESCRIPTION
+
+Returns the minimum protocol version supported by the Spock extension.
+
+This function queries the Spock extension and returns the lowest protocol
+version number it can use for replication communication. The protocol
+version determines the features and capabilities available for replication
+between nodes.
+
+When establishing replication connections between nodes running different
+Spock versions, the nodes negotiate to use a protocol version that falls
+within the supported range of both nodes. The minimum protocol version
+defines the lower bound of compatibility - nodes supporting only protocol
+versions below this minimum cannot replicate with this Spock installation.
+
+The protocol version is returned as an integer value. This minimum version
+ensures backward compatibility with older Spock releases while still
+allowing the use of newer protocol features when both nodes support them.
+
+This is a read-only query function that does not modify any data.
+
+### ARGUMENTS
+
+This function takes no arguments.
+
+### EXAMPLE
+
+SELECT spock.spock_min_proto_version();

docs/spock_functions/functions/spock_node_add_interface.md

@@ -5,22 +5,50 @@
 
 ### SYNOPSIS
 
-`spock.node_add_interface (node_name name, interface_name name, dsn text)` 
+spock.node_add_interface (node_name name, interface_name name, dsn text)
+
+### RETURNS
+
+The OID of the newly created interface.
 
 ### DESCRIPTION
 
-Add an additional interface to a spock node. 
-
-When a node is created, the interface is also created using the dsn specified in the create_node command, and with the same name as the node. This interface allows you to add alternative interfaces with different connection strings to an existing node.
+Adds a new network interface definition to an existing Spock node.
+
+Interfaces allow a single node to be reachable through multiple connection
+endpoints. This is commonly used in environments where nodes are accessible
+through different hostnames, IP addresses, private networks, public networks,
+or load balancers.
+
+The interface definition consists of a name and a PostgreSQL DSN string that
+describes how other nodes should connect to this node.
+
+This function writes metadata into the Spock catalogs but does not modify
+PostgreSQL server configuration or networking settings.
+
+Returns NULL if any argument is NULL.
+
+This command must be executed by a superuser.
+
+### ARGUMENTS
+
+node_name
+
+    The name of an existing Spock node.
+
+interface_name
+
+    A unique name for this interface on the node.
+
+dsn
 
-### EXAMPLE 
+    A PostgreSQL connection string that other nodes will use to connect to
+    this 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
 
-`spock.node_add_interface ('n1', 'n1_2', 'host=10.1.2.5 user=rocky')`
+### EXAMPLE
 
-### POSITIONAL ARGUMENTS
-    node_name
-        The name of the node. Should reference the node already created in this database. Example: n1
-    interface_name
-        The interface name to add to the node. The interface created by default matches the node name, add a new interface with a unique name. Example: n1_2
-    dsn
-        The additional 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
+SELECT spock.node_add_interface('n1', 'private_net',
+    'host=10.0.0.10 port=5432 dbname=postgres');

docs/spock_functions/functions/spock_node_create.md

@@ -1,21 +1,62 @@
 ## NAME
 
-`spock.node_create()`
+spock.node_create()
 
 ### SYNOPSIS
 
-`spock.node_create (node_name name, dsn text, location text, country text, info jsonb)`
-
+spock.node_create (node_name name, dsn text, location text DEFAULT NULL,
+country text DEFAULT NULL, info jsonb DEFAULT NULL)
+
+### RETURNS
+
+The OID of the newly created Spock node.
+
 ### DESCRIPTION
 
-Create a spock node. 
+Creates a new Spock node definition.
+
+A node represents a PostgreSQL instance that participates in Spock
+replication. The node definition includes the connection information that
+other nodes will use to communicate with this node.
+
+Optional metadata fields such as location, country, and info can be provided
+to describe the node for organizational or management purposes. These values
+are stored in the Spock catalogs but are not required for replication to
+function.
+
+This function writes metadata into the Spock catalogs but does not modify
+PostgreSQL server configuration or networking settings.
+
+Returns NULL if any argument is NULL.
+
+This command must be executed by a superuser.
+
+### ARGUMENTS
+
+node_name
+
+    A unique name for the Spock node.
+
+dsn
+
+    A PostgreSQL connection string that other nodes will use to
+    connect to this node.
+
+location
+
+    Optional descriptive text indicating the physical or logical
+    location of the node.
+
+country
+
+    Optional country code or name associated with the node.
+
+info
+
+    Optional JSONB field for storing arbitrary metadata about
+    the node.
 
-### EXAMPLE 
+### EXAMPLE
 
-`spock.node_create ('n1', 'host=10.1.2.5 user=rocky dbname=demo')`
-
-### POSITIONAL 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
-    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
+SELECT spock.node_create('n1',
+    'host=10.0.0.10 port=5432 dbname=postgres');

docs/spock_functions/functions/spock_node_drop.md

@@ -1,20 +1,51 @@
 ## NAME
 
-`spock.node_drop()`
+spock.node_drop()
 
 ### SYNOPSIS
 
-`spock.node_drop (node_name name, ifexists bool)`
-
+spock.node_drop (node_name name, ifexists boolean DEFAULT false)
+
+### RETURNS
+
+  - true if the node was dropped successfully.
+
+  - false if the node did not exist and ifexists was set to true.
+
+  - ERROR if the call has invalid parameters, insufficient privileges, or
+    the node cannot be removed due to existing dependencies.
+
 ### DESCRIPTION
-    Drop a spock node. 
 
-### EXAMPLE 
+Removes an existing Spock node from the cluster metadata.
+
+This function deletes the node definition and all associated metadata from the
+Spock catalogs. It does not remove any PostgreSQL data directory or stop
+the PostgreSQL server; it only removes Spock’s logical representation of the
+node.
+
+If ifexists is set to false (default), an error is raised when the specified
+node does not exist. If ifexists is true, the function returns false
+instead of raising an error.
+
+Returns NULL if any argument is NULL.
+
+This command must be executed by a superuser and modifies Spock catalog
+tables.
+
+### EXAMPLE
+
+SELECT spock.node_drop('n1');
+
+SELECT spock.node_drop('n1', true);
+
+### ARGUMENTS
+
+node_name
+
+    The name of the existing Spock node to remove.
+
+ifexists
 
-`spock.node_drop ('n1')`
-
-### POSITIONAL ARGUMENTS
-    node_name
-        The name of the node. Example: n1
-    ifexists
-        `ifexists` specifies the Spock extension behavior with regards to error messages. If `true`, an error is not thrown when the specified node does not exist. The default is `false`.
+    If true, do not raise an error when the node does not exist; return
+    false instead. Default is false.