Skip to main content
Version: 4.4

Clustering

The following operations are available for configuring and managing Harper replication.\

If you are using NATS for clustering, please see the NATS Clustering Operations documentation.

Add Node​

Adds a new Harper instance to the cluster. If subscriptions are provided, it will also create the replication relationships between the nodes. If they are not provided a fully replicating system will be created. Learn more about adding nodes here.

Operation is restricted to super_user roles only

  • operation (required) - must always be add_node
  • hostname or url (required) - one of these fields is required. You must provide either the hostname or the url of the node you want to add
  • verify_tls (optional) - a boolean which determines if the TLS certificate should be verified. This will allow the Harper default self-signed certificates to be accepted. Defaults to true
  • authorization (optional) - an object or a string which contains the authorization information for the node being added. If it is an object, it should contain username and password fields. If it is a string, it should use HTTP Authorization style credentials
  • retain_authorization (optional) - a boolean which determines if the authorization credentials should be retained/stored and used everytime a connection is made to this node. If true, the authorization will be stored on the node record. Generally this should not be used, as mTLS/certificate based authorization is much more secure and safe, and avoids the need for storing credentials. Defaults to false.
  • subscriptions (optional) - The relationship created between nodes. If not provided a fully replicated cluster will be setup. Must be an object array and include database, table, subscribe and publish:
    • database - the database to replicate
    • table - the table to replicate
    • subscribe - a boolean which determines if transactions on the remote table should be replicated on the local table
    • publish - a boolean which determines if transactions on the local table should be replicated on the remote table

Body​

{
	"operation": "add_node",
	"hostname": "server-two",
	"verify_tls": false,
	"authorization": {
		"username": "admin",
		"password": "password"
	}
}

Response: 200​

{
	"message": "Successfully added 'server-two' to cluster"
}

Update Node​

Modifies an existing Harper instance in the cluster.

Operation is restricted to super_user roles only

Note: will attempt to add the node if it does not exist

  • operation (required) - must always be update_node
  • hostname (required) - the hostname of the remote node you are updating
  • subscriptions (required) - The relationship created between nodes. Must be an object array and include database, table, subscribe and publish:
    • database - the database to replicate from
    • table - the table to replicate from
    • subscribe - a boolean which determines if transactions on the remote table should be replicated on the local table
    • publish - a boolean which determines if transactions on the local table should be replicated on the remote table

Body​

{
	"operation": "update_node",
	"hostname": "server-two",
	"subscriptions": [
		{
			"database": "dev",
			"table": "my-table",
			"subscribe": true,
			"publish": true
		}
	]
}

Response: 200​

{
	"message": "Successfully updated 'server-two'"
}

Remove Node​

Removes a Harper node from the cluster and stops replication, Learn more about remove node here.

Operation is restricted to super_user roles only

  • operation (required) - must always be remove_node
  • name (required) - The name of the node you are removing

Body​

{
	"operation": "remove_node",
	"hostname": "server-two"
}

Response: 200​

{
	"message": "Successfully removed 'server-two' from cluster"
}

Cluster Status​

Returns an array of status objects from a cluster.

database_sockets shows the actual websocket connections that exist between nodes.

Operation is restricted to super_user roles only

  • operation (required) - must always be cluster_status

Body​

{
	"operation": "cluster_status"
}

Response: 200​

{
	"type": "cluster-status",
	"connections": [
		{
			"url": "wss://server-two:9925",
			"subscriptions": [
				{
					"schema": "dev",
					"table": "my-table",
					"publish": true,
					"subscribe": true
				}
			],
			"name": "server-two",
			"database_sockets": [
				{
					"database": "dev",
					"connected": true,
					"latency": 0.84197798371315,
					"threadId": 1,
					"nodes": ["server-two"]
				}
			]
		}
	],
	"node_name": "server-one",
	"is_enabled": true
}

Configure Cluster​

Bulk create/remove subscriptions for any number of remote nodes. Resets and replaces any existing clustering setup.

Operation is restricted to super_user roles only

  • operation (required) - must always be configure_cluster
  • connections (required) - must be an object array with each object following the add_node schema.

Body​

{
	"operation": "configure_cluster",
	"connections": [
		{
			"hostname": "server-two",
			"verify_tls": false,
			"authorization": {
				"username": "admin",
				"password": "password2"
			},
			"subscriptions": [
				{
					"schema": "dev",
					"table": "my-table",
					"subscribe": true,
					"publish": false
				}
			]
		},
		{
			"hostname": "server-three",
			"verify_tls": false,
			"authorization": {
				"username": "admin",
				"password": "password3"
			},
			"subscriptions": [
				{
					"schema": "dev",
					"table": "dog",
					"subscribe": true,
					"publish": true
				}
			]
		}
	]
}

Response: 200​

{
	"message": "Cluster successfully configured."
}

Cluster Set Routes​

Adds a route/routes to the replication.routes configuration. This operation behaves as a PATCH/upsert, meaning it will add new routes to the configuration while leaving existing routes untouched.

Operation is restricted to super_user roles only

  • operation (required) - must always be cluster_set_routes
  • routes (required) - the routes field is an array that specifies the routes for clustering. Each element in the array can be either a string or an object with hostname and port properties.

Body​

{
	"operation": "cluster_set_routes",
	"routes": [
		"wss://server-two:9925",
		{
			"hostname": "server-three",
			"port": 9930
		}
	]
}

Response: 200​

{
	"message": "cluster routes successfully set",
	"set": [
		"wss://server-two:9925",
		{
			"hostname": "server-three",
			"port": 9930
		}
	],
	"skipped": []
}

Cluster Get Routes​

Gets the replication routes from the Harper config file.

Operation is restricted to super_user roles only

  • operation (required) - must always be cluster_get_routes

Body​

{
	"operation": "cluster_get_routes"
}

Response: 200​

[
	"wss://server-two:9925",
	{
		"hostname": "server-three",
		"port": 9930
	}
]

Cluster Delete Routes​

Removes route(s) from the Harper config file. Returns a deletion success message and arrays of deleted and skipped records.

Operation is restricted to super_user roles only

  • operation (required) - must always be cluster_delete_routes
  • routes (required) - Must be an array of route object(s)

Body​

{
	"operation": "cluster_delete_routes",
	"routes": [
		{
			"hostname": "server-three",
			"port": 9930
		}
	]
}

Response: 200​

{
	"message": "cluster routes successfully deleted",
	"deleted": [
		{
			"hostname": "server-three",
			"port": 9930
		}
	],
	"skipped": []
}