LogoLogo
Studio
4.5
4.5
  • 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
      • Query Instance Data
      • 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
      • Blob
    • Release Notes
      • Harper Tucker (Version 4)
        • 4.5.8
        • 4.5.7
        • 4.5.6
        • 4.5.5
        • 4.5.4
        • 4.5.3
        • 4.5.2
        • 4.5.1
        • 4.5.0
        • 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
  • Upgrading
  • Node Version Manager (nvm)
  • Upgrading Nats to Plexus 4.4
  • Enabling Plexus
  • Upgrade Steps
  1. Deployments

Upgrade a Harper Instance

PreviousOn LinuxNextHarper Cloud

Last updated 1 month ago

This document describes best practices for upgrading self-hosted Harper instances. Harper can be upgraded using a combination of npm and built-in Harper upgrade scripts. Whenever upgrading your Harper installation it is recommended you make a backup of your data first. Note: This document applies to self-hosted Harper instances only. All will be upgraded by the Harper Cloud team.

Upgrading

Upgrading Harper is a two-step process. First the latest version of Harper must be downloaded from npm, then the Harper upgrade scripts will be utilized to ensure the newest features are available on the system.

  1. Install the latest version of Harper using npm install -g harperdb.

    Note -g should only be used if you installed Harper globally (which is recommended).

  2. Run harperdb to initiate the upgrade process.

    Harper will then prompt you for all appropriate inputs and then run the upgrade directives.

Node Version Manager (nvm)

is an easy way to install, remove, and switch between different versions of Node.js as required by various applications. More information, including directions on installing nvm can be found here: https://nvm.sh/.

Harper supports Node.js versions 14.0.0 and higher, however, please check our for our recommended Node.js version. To install a different version of Node.js with nvm, run the command:

nvm install <the node version>

To switch to a version of Node run:

nvm use <the node version>

To see the current running version of Node run:

node --version

With a handful of different versions of Node.js installed, run nvm with the ls argument to list out all installed versions:

nvm ls

When upgrading Harper, we recommend also upgrading your Node version. Here we assume you're running on an older version of Node; the execution may look like this:

Switch to the older version of Node that Harper is running on (if it is not the current version):

nvm use 14.19.0

Make sure Harper is not running:

harperdb stop

Uninstall Harper. Note, this step is not required, but will clean up old artifacts of Harper. We recommend removing all other Harper installations to ensure the most recent version is always running.

npm uninstall -g harperdb

Switch to the newer version of Node:

nvm use <the node version>

Install Harper globally

npm install -g harperdb

Run the upgrade script

harperdb

Start Harper

harperdb start

Upgrading Nats to Plexus 4.4

To upgrade from NATS clustering to Plexus replication, follow these manual steps. They are designed for a fully replicating cluster to ensure minimal disruption during the upgrade process.

The core of this upgrade is the bridge node. This node will run both NATS and Plexus simultaneously, ensuring that transactions are relayed between the two systems during the transition. The bridge node is crucial in preventing any replication downtime, as it will handle transactions from NATS nodes to Plexus nodes and vice versa.

Enabling Plexus

replication:
    url: wss://my-cluster-node-1:9925
    hostname: node-1

replication.url – This should be set to the URL of the current Harper instance.

replication.hostname – Since we are upgrading from NATS, this value should match the clustering.nodeName of the current instance.

Upgrade Steps

  1. Set up the bridge node:

    • Choose one node to be the bridge node.

    • On this node, follow the "Enabling Plexus" steps from the previous section, but do not disable NATS clustering on this instance.

    • Stop the instance and perform the upgrade.

    • Start the instance. This node should now be running both Plexus and NATS.

  2. Upgrade a node:

    • Choose a node that needs upgrading and enable Plexus by following the "Enable Plexus" steps.

    • Disable NATS by setting clustering.enabled to false.

    • Stop the instance and upgrade it.

    • Start the instance.

{
    "operation": "add_node",
    "hostname:": "node-1",
    "url": "wss://my-cluster-node-1:9925"
}
  1. Repeat Step 2 on all remaining nodes that need to be upgraded.

  2. Disable NATS on the bridge node by setting clustering.enabled to false and restart the instance.

Your cluster upgrade should now be complete, with no NATS processes running on any of the nodes.

To enable Plexus on a node that is already running NATS, you will need to update in the harperdb-config.yaml file:

Call on the upgraded instance. In this call, omit subscriptions so that a fully replicating cluster is built. The target node for this call should be the bridge node. Note: depending on your setup, you may need to expand this add_node call to include .

Harper Cloud instances
Node Version Manager (nvm)
NPM page
two values
add_node
authorization and/or tls information