Spockctrl Functions

Spockctrl provides functions to manage different aspects of your Spock replication setup. The functions are grouped by the type of object they manage:

• Spockctrl node management functions
• Spockctrl replication management functions
• Spockctrl subscription management functions
• Spockctrl SQL execution functions

Spockctrl Node Management Functions

Use the node command to manage the nodes that participate in a replication cluster. The functions are:

spockctrl node create

Use spockctrl node create to create a new Spock node within the Spock metadata. The syntax is:

spockctrl node create <node_name> --dsn <connection_string>

• <node_name>: A unique name for the node.
• --dsn <connection_string>: Specifies the connection string for the PostgreSQL instance.

Optional Arguments

• -c <file>, --config=<path_to_spockctrl.json> - Specifies the path to the spockctrl.json configuration file. If not provided, spockctrl looks for spockctrl.json in the current directory. For example: spockctrl node list -c /etc/spock/spockctrl.conf
• -f <format>, --format=<table or json> - Determines the output format for commands that display data. Specify: table (the default) to outputs data in a human-readable tabular format or json to output data in JSON format, which is useful for scripting or integration with other tools. For example: spockctrl sub list --format=json
• -v <level>, --verbose=<integer_value> - Enables verbose logging to provide more detailed output about what spockctrl is doing. The verbosity level is an integer with higher numbers providing more detailed logs. 0 logs ERRORs only, 1 logs WARNINGs and ERRORs, 2 logs informational messages, WARNINGs, and ERRORs, and 3 logs debug level messages (most verbose). For example: spockctrl --verbose=2 node create mynode ...
• -w <file>, --workflow=<path_to_workflow> - Executes a predefined workflow from the specified JSON file. When using this option, you typically don't specify other commands like node or sub directly on the command line, as the workflow file directs the operations. For example: spockctrl --config=myconfig.json --workflow=workflows/add_node.json
• -h, --help - Displays a general help message listing all available commands, or help for a specific command or subcommand. For example, to request help for the node create subcommand: spockctrl node create --help

Example

spockctrl node create my_node --dsn "host=pg1 port=5432 dbname=testdb user=spock"

spockctrl node drop

Use spockctrl node drop to remove a Spock node. The syntax is:

spockctrl node drop <node_name>

• <node_name>: A unique name for the node.

Example

spockctrl node drop my_node

spockctrl node list

Use spockctrl node list to list all configured Spock nodes. The syntax is:

spockctrl node list

Example

spockctrl node list

spockctrl node add-interface

Use spockctrl node add-interface to add an alternative connection interface to a node. The syntax is:

spockctrl node add-interface <node_name> <interface_name> --dsn <connection_string>

• <node_name>: The name of the node accessed by the interface.
• <interface_name>: A unique name for the new interface.
• --dsn <connection_string>: Specifies the connection string of the new interface.

Example

spockctrl node add-interface my_node secondary_conn --dsn "host=pg1_alt_ip port=5432 dbname=testdb"

spockctrl node drop-interface

Use spockctrl node drop-interface to drop an interface from a node. The syntax is:

spockctrl node drop-interface <node_name> <interface_name> drops an interface from a node.

• <node_name>: The name of the node accessed by the interface.
• <interface_name>: A unique name for the new interface.

Example

spockctrl node drop-interface my_node secondary_conn

Replication Set Management Functions

You can use the spockctrl repset command to manage the Spock replication sets that participate in a replication cluster. A replication set defines groups of tables and sequences to be replicated.

spockctrl repset create

Use spockctrl repset create to create a new replication set. The syntax is:

spockctrl repset create <repset_name> [options]

• <repset_name>: Name for the replication set (e.g., default, custom_set).
• You can include options to control DDL replication, DML replication, etc. (for example, --replicate_insert=true, --replicate_update=false).

Example

spockctrl repset create my_repset

spockctrl repset drop

Use spockctrl repset drop to drop a replication set; the syntax is:

spockctrl repset drop <repset_name>

• <repset_name>: Name for the replication set (e.g., default, custom_set).

Example

spockctrl repset drop my_repset

spockctrl repset add-table

Use spockctrl repset add-table to add a specific table to a replication set. The syntax is:

spockctrl repset add-table <repset_name> <table_name> [options]

• <repset_name>: Name for the replication set (e.g., default, custom_set).
• <table_name> is the schema-qualified table name (e.g., public.my_table).
• You can include options to specify which columns to replicate and filtering conditions.

Example

spockctrl repset add-table my_repset public.orders --columns "order_id,product_id,quantity"

spockctrl repset add-all-tables

Use spockctrl repset add-all-tables to add all tables from the specified schema to a replication set. The syntax is:

spockctrl repset add-all-tables <repset_name> <schema_name>

• <repset_name>: Name for the replication set (e.g., default, custom_set).
• <schema_name>: The name of the schema (e.g., public).

Example

spockctrl repset add-all-tables my_repset public

spockctrl repset add-seq

Use spockctrl repset add-seq to add a sequence to a replication set. The syntax is:

spockctrl repset add-seq <repset_name> <sequence_name>

• <repset_name>: Name for the replication set (e.g., default, custom_set).
• <sequence_name>: The name of the sequence.

Example

spockctrl repset add-seq my_repset public.my_sequence

spockctrl repset add-all-sequences

Use spockctrl repset add-all-sequences to adds all sequences from a given schema. The syntax is:

spockctrl repset add-all-sequences <repset_name> <schema_name>

• <repset_name>: Name for the replication set (e.g., default, custom_set).
• <schema_name>: The name of the schema (e.g., public).

Example

spockctrl repset add-all-sequences my_repset public

spockctrl repset list

Use spockctrl repset list to list the available replication sets. The syntax is:

spockctrl repset list

Spockctrl Subscription Management Functions

The sub command manages subscriptions, which connect a subscriber node to a provider node and initiate replication.

spockctrl sub create

Use spockctrl sub create <subscription_name> <provider_dsn> [options] to create a new subscription.

• <subscription_name>: A unique name for the subscription.
• <provider_dsn>: The DSN of the provider node to subscribe to.
• You can include options to specifying replication sets, synchronization options, etc.

Example

spockctrl sub create sub_n3_n1 "host=pg1 port=5432 dbname=testdb user=spock" --repsets "default,my_repset"

spockctrl sub drop

Use spockctrl sub drop to drop a subscription. The syntax is:

spockctrl sub drop <subscription_name>

• <subscription_name>: A unique name for the subscription.

Example

spockctrl sub drop sub_n3_n1

spockctrl sub enable

Use spockctrl sub enable to enable a disabled subscription. The syntax is:

spockctrl sub enable <subscription_name>

• <subscription_name>: A unique name for the subscription.

Example

spockctrl sub enable sub_n3_n1

spockctrl sub disable

Use spockctrl sub disable to disable an active subscription, pausing replication. The syntax is:

spockctrl sub disable <subscription_name>

• <subscription_name>: A unique name for the subscription.

Example

spockctrl sub disable sub_n3_n1

spockctrl sub list

Use spockctrl sub list to list all subscriptions. The syntax is:

spockctrl sub list

spockctrl sub show-status

Use spockctrl sub show-status to show the status of a specific subscription. The syntax is:

spockctrl sub show-status <subscription_name>

• <subscription_name>: A unique name for the subscription.

Example

spockctrl sub show-status sub_n3_n1

spockctrl sub wait-for-sync

Use spockctrl sub wait-for-sync to wait for a subscription to complete its initial data synchronization.

spockctrl sub wait-for-sync <subscription_name>

Example

spockctrl sub wait-for-sync sub_n3_n1

Spockctrl SQL Execution Functions

The sql command allows you to execute arbitrary SQL commands on a specified node. This can be useful for performing administrative tasks or querying Spock-specific metadata.

spockctrl sql

Use the spockctrl sql command to execute a SQL command. The syntax is:

spockctrl sql <node_name> <SQL_command_string>

• <node_name> is the name of the node (from spockctrl.json) on which to execute the command.
• <SQL_command_string> is the SQL query or command to run.

Examples

spockctrl sql my_node "SELECT * FROM spock.node;" spockctrl sql my_node "CALL spock.sub_resync_table('my_subscription', 'public.my_table');"