LogoLogo
Studio
4.4
4.4
  • Harper Docs
  • Getting Started
  • Developers
    • Applications
      • Caching
      • Defining Schemas
      • Defining Roles
      • Debugging Applications
      • Define Fastify Routes
      • Web Applications
      • Example Projects
    • Components
      • Managing
      • Reference
      • Built-In Components
    • REST
    • Operations API
      • Quick Start Examples
      • Databases and Tables
      • NoSQL Operations
      • Bulk Operations
      • Users and Roles
      • Clustering
        • Clustering with NATS
      • Custom Functions
      • Components
      • Registration
      • Jobs
      • Logs
      • Utilities
      • Token Authentication
      • SQL Operations
      • Advanced JSON SQL Examples
    • Real-Time
    • Replication/Clustering
      • Sharding
      • Legacy NATS Clustering
        • Requirements and Definitions
        • Creating A Cluster User
        • Naming A Node
        • Enabling Clustering
        • Establishing Routes
        • Subscription Overview
        • Managing Subscriptions
        • Things Worth Knowing
        • Certificate Management
    • Security
      • JWT Authentication
      • Basic Authentication
      • mTLS Authentication
      • Configuration
      • Users & Roles
      • Certificate Management
    • SQL Guide
      • SQL Features Matrix
      • SQL Date Functions
      • SQL Reserved Word
      • SQL Functions
      • SQL JSON Search
      • SQL Geospatial Functions
    • Miscellaneous
      • Google Data Studio
      • SDKs
      • Query Optimization
  • Administration
    • Best Practices and Recommendations
    • Logging
      • Standard Logging
      • Audit Logging
      • Transaction Logging
    • Clone Node
    • Compact
    • Jobs
    • Harper Studio
      • Create an Account
      • Log In & Password Reset
      • Organizations
      • Instances
      • Manage Databases / Browse Data
      • Manage Clustering
      • Manage Instance Users
      • Manage Instance Roles
      • Manage Applications
      • Instance Metrics
      • Instance Configuration
      • Enable Mixed Content
  • Deployments
    • Configuration File
    • Harper CLI
    • Install Harper
      • On Linux
    • Upgrade a Harper Instance
    • Harper Cloud
      • IOPS Impact on Performance
      • Instance Size Hardware Specs
      • Alarms
      • Verizon 5G Wavelength
  • Technical Details
    • Reference
      • Analytics
      • Architecture
      • Content Types
      • Data Types
      • Dynamic Schema
      • GraphQL
      • Harper Headers
      • Harper Limits
      • Globals
      • Resource Class
      • Transactions
      • Storage Algorithm
    • Release Notes
      • Harper Tucker (Version 4)
        • 4.4.24
        • 4.4.23
        • 4.4.22
        • 4.4.21
        • 4.4.20
        • 4.4.19
        • 4.4.18
        • 4.4.17
        • 4.4.16
        • 4.4.15
        • 4.4.14
        • 4.4.13
        • 4.4.12
        • 4.4.11
        • 4.4.10
        • 4.4.9
        • 4.4.8
        • 4.4.7
        • 4.4.6
        • 4.4.5
        • 4.4.4
        • 4.4.3
        • 4.4.2
        • 4.4.1
        • 4.4.0
        • 4.3.38
        • 4.3.37
        • 4.3.36
        • 4.3.35
        • 4.3.34
        • 4.3.33
        • 4.3.32
        • 4.3.31
        • 4.3.30
        • 4.3.29
        • 4.3.28
        • 4.3.27
        • 4.3.26
        • 4.3.25
        • 4.3.24
        • 4.3.23
        • 4.3.22
        • 4.3.21
        • 4.3.20
        • 4.3.19
        • 4.3.18
        • 4.3.17
        • 4.3.16
        • 4.3.15
        • 4.3.14
        • 4.3.13
        • 4.3.12
        • 4.3.11
        • 4.3.10
        • 4.3.9
        • 4.3.8
        • 4.3.7
        • 4.3.6
        • 4.3.5
        • 4.3.4
        • 4.3.3
        • 4.3.2
        • 4.3.1
        • 4.3.0
        • 4.2.8
        • 4.2.7
        • 4.2.6
        • 4.2.5
        • 4.2.4
        • 4.2.3
        • 4.2.2
        • 4.2.1
        • 4.2.0
        • 4.1.2
        • 4.1.1
        • 4.1.0
        • 4.0.7
        • 4.0.6
        • 4.0.5
        • 4.0.4
        • 4.0.3
        • 4.0.2
        • 4.0.1
        • 4.0.0
        • Tucker
      • HarperDB Monkey (Version 3)
        • 3.3.0
        • 3.2.1
        • 3.2.0
        • 3.1.5
        • 3.1.4
        • 3.1.3
        • 3.1.2
        • 3.1.1
        • 3.1.0
        • 3.0.0
      • HarperDB Penny (Version 2)
        • 2.3.1
        • 2.3.0
        • 2.2.3
        • 2.2.2
        • 2.2.0
        • 2.1.1
      • HarperDB Alby (Version 1)
        • 1.3.1
        • 1.3.0
        • 1.2.0
        • 1.1.0
  • More Help
    • Support
    • Slack
    • Contact Us
Powered by GitBook
On this page
  • Add Node
  • Body
  • Response: 200
  • Update Node
  • Body
  • Response: 200
  • Remove Node
  • Body
  • Response: 200
  • Cluster Status
  • Body
  • Response: 200
  • Configure Cluster
  • Body
  • Response: 200
  • Cluster Set Routes
  • Body
  • Response: 200
  • Cluster Get Routes
  • Body
  • Response: 200
  • Cluster Delete Routes
  • Body
  • Response: 200
  1. Developers
  2. Operations API

Clustering

PreviousUsers and RolesNextClustering with NATS

Last updated 2 months ago

The following operations are available for configuring and managing .\

If you are using NATS for clustering, please see the 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. .

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

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": []
}

Removes a Harper node from the cluster and stops replication, .

Harper replication
NATS Clustering Operations
Learn more about adding nodes here
Learn more about remove node here