docs(replication): remove all NATS/legacy clustering content

Ethan-Arrowood · claude · Ethan-Arrowood · commit 4dd92923620c · 2026-03-25T13:58:13.000-06:00
Strips the Legacy NATS Clustering section from clustering.md, removes
NATS-era callout blockquotes from overview.md, and drops version
annotations that only make sense in a migration-history context.

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/reference_versioned_docs/version-v4/replication/clustering.md b/reference_versioned_docs/version-v4/replication/clustering.md
@@ -2,27 +2,12 @@
 title: Clustering
 ---
 
-<!-- Source: versioned_docs/version-4.7/developers/operations-api/clustering.md (primary — native replication operations) -->
-<!-- Source: versioned_docs/version-4.7/reference/clustering/index.md (legacy NATS overview) -->
-<!-- Source: versioned_docs/version-4.7/reference/clustering/requirements-and-definitions.md -->
-<!-- Source: versioned_docs/version-4.7/reference/clustering/enabling-clustering.md -->
-<!-- Source: versioned_docs/version-4.7/reference/clustering/establishing-routes.md -->
-<!-- Source: versioned_docs/version-4.7/reference/clustering/naming-a-node.md -->
-<!-- Source: versioned_docs/version-4.7/reference/clustering/creating-a-cluster-user.md -->
-<!-- Source: versioned_docs/version-4.7/reference/clustering/managing-subscriptions.md -->
-<!-- Source: versioned_docs/version-4.7/reference/clustering/subscription-overview.md -->
-<!-- Source: versioned_docs/version-4.7/reference/clustering/certificate-management.md -->
-<!-- Source: versioned_docs/version-4.7/reference/clustering/things-worth-knowing.md -->
-<!-- Source: release-notes/v4-tucker/4.4.0.md (confirmed native replication in v4.4.0) -->
-<!-- Source: release-notes/v4-tucker/4.5.0.md (confirmed cluster status improvements in v4.5.0) -->
+<!-- Source: versioned_docs/version-4.7/developers/operations-api/clustering.md (primary) -->
+<!-- Source: release-notes/v4-tucker/4.5.0.md (confirmed cluster status timing statistics in v4.5.0) -->
 
 # Clustering
 
-This page documents the Operations API for managing Harper's native replication system (available since v4.4.0). For an overview of how replication works, see [Replication Overview](./overview.md). For sharding configuration, see [Sharding](./sharding.md).
-
-> **Legacy NATS Clustering**: The NATS-based clustering used in v4.0–4.3 is described in the [Legacy NATS Clustering](#legacy-nats-clustering) section below. The operations described here apply to the native replication system in v4.4.0+.
-
-## Operations API
+Operations API for managing Harper's replication system. For an overview of how replication works, see [Replication Overview](./overview.md). For sharding configuration, see [Sharding](./sharding.md).
 
 All clustering operations require `super_user` role.
 
@@ -32,8 +17,6 @@ All clustering operations require `super_user` role.
 
 Adds a new Harper instance to the cluster. If `subscriptions` are provided, it creates the specified replication relationships between the nodes. Without `subscriptions`, a fully replicating system is created (all data in all databases).
 
-Added in: v4.4.0
-
 **Parameters**:
 
 - `operation` _(required)_ — must be `add_node`
@@ -80,8 +63,6 @@ Added in: v4.4.0
 
 Modifies an existing Harper instance in the cluster. Will attempt to add the node if it does not exist.
 
-Added in: v4.4.0
-
 **Parameters**:
 
 - `operation` _(required)_ — must be `update_node`
@@ -121,8 +102,6 @@ Added in: v4.4.0
 
 Removes a Harper node from the cluster and stops all replication to and from that node.
 
-Added in: v4.4.0
-
 **Parameters**:
 
 - `operation` _(required)_ — must be `remove_node`
@@ -212,8 +191,6 @@ Added in: v4.4.0; timing statistics added in v4.5.0
 
 Bulk creates or resets subscriptions for any number of remote nodes. **Resets and replaces any existing clustering setup.**
 
-Added in: v4.4.0
-
 **Parameters**:
 
 - `operation` _(required)_ — must be `configure_cluster`
@@ -275,8 +252,6 @@ Added in: v4.4.0
 
 Adds routes to the `replication.routes` configuration. Behaves as a PATCH/upsert — adds new routes while leaving existing routes untouched.
 
-Added in: v4.4.0
-
 **Parameters**:
 
 - `operation` _(required)_ — must be `cluster_set_routes`
@@ -372,159 +347,3 @@ Removes routes from the Harper config file.
 }
 ```
 
----
-
-## Legacy NATS Clustering
-
-> **Applies to v4.0–4.3 only.** Harper v4.4.0 replaced NATS clustering with the native replication system. The operations and configuration below are documented for legacy reference.
-
-Harper 4.0–4.3 used a clustering system based on NATS. NATS clustering used a bi-directional pub/sub model on a per-table basis with eventual consistency. Individual transactions were sent in the order they were transacted, and once received by the destination instance, processed in an ACID-compliant manner. Conflict resolution used last-writer-wins based on recorded transaction time.
-
-### Requirements
-
-A cluster requires two or more Harper nodes (instances). A node is a single installation of Harper and can operate independently with clustering enabled or disabled.
-
-### Enabling NATS Clustering
-
-Clustering must be explicitly enabled. Set `clustering.enabled` to `true` in `harperdb-config.yaml`:
-
-```yaml
-clustering:
-  enabled: true
-```
-
-Or via the operations API (requires restart):
-
-```json
-{
-	"operation": "set_configuration",
-	"clustering_enabled": true
-}
-```
-
-Or via CLI / environment variable:
-
-```bash
-harperdb --CLUSTERING_ENABLED true
-# or
-CLUSTERING_ENABLED=true
-```
-
-### Naming a Node
-
-Each node must have a unique name in the cluster. The name cannot contain `.`, `,`, `*`, `>`, or whitespace.
-
-```yaml
-clustering:
-  nodeName: Node1
-```
-
-Or via the operations API:
-
-```json
-{
-	"operation": "set_configuration",
-	"clustering_nodeName": "Node1"
-}
-```
-
-### Creating a Cluster User
-
-Inter-node authentication in NATS clustering used a special `cluster_user` role. All clustered nodes must share the same cluster user credentials.
-
-Create the user via the operations API:
-
-```json
-{
-	"operation": "add_user",
-	"role": "cluster_user",
-	"username": "cluster_account",
-	"password": "letsCluster123!",
-	"active": true
-}
-```
-
-Then configure the cluster user in `harperdb-config.yaml`:
-
-```yaml
-clustering:
-  user: cluster_account
-```
-
-Or set both at install time:
-
-```bash
-harperdb install \
-  --CLUSTERING_ENABLED true \
-  --CLUSTERING_NODENAME Node1 \
-  --CLUSTERING_USER cluster_account \
-  --CLUSTERING_PASSWORD letsCluster123!
-```
-
-### Routes
-
-A route is a connection between two nodes. Routes create a mesh network — you do not need to cross-connect all nodes. One route from any node to the cluster is sufficient for all nodes to reach each other.
-
-Route configuration used the `clustering.hubServer.cluster.network.routes` key:
-
-```yaml
-clustering:
-  hubServer:
-    cluster:
-      network:
-        routes:
-          - host: 3.62.184.22
-            port: 9932
-          - host: 3.735.184.8
-            port: 9932
-```
-
-Routes could also be set via `cluster_set_routes`, `cluster_get_routes`, and `cluster_delete_routes` operations (same API as the native system, but with NATS-specific parameters).
-
-### Subscriptions
-
-In NATS clustering, subscriptions were the mechanism for controlling which tables replicated and in which direction. A subscription consisted of:
-
-- `database` — the database the table belongs to
-- `table` — the table name
-- `publish` — if `true`, local transactions are replicated to the remote table
-- `subscribe` — if `true`, remote transactions are replicated to the local table
-
-Subscriptions were managed with the `set_node_replication` operation:
-
-```json
-{
-	"operation": "set_node_replication",
-	"node_name": "Node2",
-	"subscriptions": [
-		{
-			"database": "data",
-			"table": "dog",
-			"publish": true,
-			"subscribe": true
-		}
-	]
-}
-```
-
-### Certificate Management (NATS)
-
-Harper generated self-signed certificates for NATS cluster connections by default, stored in `<ROOTPATH>/keys/`. For development:
-
-```yaml
-clustering:
-  tls:
-    certificate: ~/hdb/keys/certificate.pem
-    certificateAuthority: ~/hdb/keys/ca.pem
-    privateKey: ~/hdb/keys/privateKey.pem
-    insecure: true
-    verify: true
-```
-
-For production, use certificates from your own CA or a public CA with matching CNs. Certificates must have `Extended Key Usage` including both `TLS Web Server Authentication` and `TLS Web Client Authentication`.
-
-### What Replicated
-
-The same data operations that replicate in the native system also replicated in NATS: insert, update, upsert, delete, and bulk loads. Destructive operations (`drop_database`, `drop_table`, `drop_attribute`) and users/roles did not replicate.
-
-NATS clustering had built-in resiliency for network interruptions — when reconnected, a catchup routine replayed missed transactions.
diff --git a/reference_versioned_docs/version-v4/replication/overview.md b/reference_versioned_docs/version-v4/replication/overview.md
@@ -3,17 +3,12 @@ title: Replication Overview
 ---
 
 <!-- Source: versioned_docs/version-4.7/developers/replication/index.md (primary) -->
-<!-- Source: release-notes/v4-tucker/4.4.0.md (confirmed native replication introduction) -->
 <!-- Source: release-notes/v4-tucker/4.5.0.md (confirmed cluster status improvements, default port change, certificate revocation, expanded sharding) -->
 
 # Replication Overview
 
-Added in: v4.4.0
-
 Harper's replication system is designed to make distributed data replication fast and reliable across multiple nodes. You can build a distributed database that ensures high availability, disaster recovery, and data localization — all without complex setup. Nodes can be added or removed dynamically, you can choose which data to replicate, and you can monitor cluster health without jumping through hoops.
 
-> **Legacy NATS Clustering**: Harper 4.0–4.3 used a NATS-based clustering system. In v4.4.0, Harper replaced this with a new native replication system (codenamed Plexus) that provides better performance, reliability, and data consistency. The legacy NATS system is documented in [Clustering](./clustering.md).
-
 ## Peer-to-Peer Model
 
 Harper replication uses a peer-to-peer model where every node in your cluster can send data to and receive data from other nodes. Nodes communicate over WebSockets, allowing data to flow in both directions. Harper automatically manages these connections and subscriptions, so you don't need to manually track data consistency. Connections between nodes are secured and reliable by default.
@@ -43,7 +38,7 @@ replication:
       port: 9933
 ```
 
-By default, replication connects on the secure port `9933`. Added in: v4.5.0 (changed from 9925).
+By default, replication connects on the secure port `9933`.
 
 ```yaml
 replication:
@@ -289,7 +284,7 @@ The following data operations are replicated across the cluster:
 
 Users and roles are not replicated across the cluster.
 
-Added in: v4.4.0 (replicated operations): certain management operations — including component deployment and rolling restarts — can also be replicated across the cluster.
+Certain management operations — including component deployment and rolling restarts — can also be replicated across the cluster.
 
 ## Inspecting Cluster Configuration
 
