Database clusters
Some databases are best run as a cluster: several nodes that replicate data and survive a node failure. Pier can deploy these clusters across multiple servers on the WireGuard mesh, so the nodes live on different hosts but still reach each other over the private overlay.
Which engines support clustering
Section titled “Which engines support clustering”Clustering is opt-in per engine, declared in the catalog template. Seven engines support it:
| Engine | Topology | Min nodes | Max nodes |
|---|---|---|---|
| PostgreSQL | Streaming replication (1 primary + read replicas) | 2 | 5 |
| MySQL | Streaming replication (1 primary + read replicas) | 2 | 5 |
| MariaDB | Streaming replication (1 primary + read replicas) | 2 | 5 |
| MongoDB | Replica set with automatic primary election | 3 | 5 |
| Redis | Sentinel HA (1 master + replicas + sentinels) | 3 | 5 |
| Cassandra | Gossip ring with seed-based discovery | 2 | 5 |
| ScyllaDB | Gossip ring (Cassandra-compatible) | 2 | 5 |
The default node count for every clustered engine is 3. MongoDB and Redis require at least three nodes so their quorum-based elections work. Engines without a cluster section — for example PostGIS, TimescaleDB, Valkey and ClickHouse — deploy as a single standalone instance.
Single-server vs. cross-server
Section titled “Single-server vs. cross-server”You choose a cluster when creating the resource by selecting cluster mode and assigning each node to a server:
- If every node lands on one server, Pier builds a single-host Compose stack for the cluster.
- If nodes are spread across multiple servers, Pier deploys a distributed cluster. Every target server must be on an active WireGuard mesh, or the request is rejected — the nodes reach each other by mesh IP and published host port.
Cassandra and ScyllaDB have an extra constraint when distributed: one node per server, because their gossip port is fixed and two nodes on the same host would collide.
Scaling
Section titled “Scaling”Change the total node count with POST /api/v1/resources/{id}/scale, passing the new node_count. Pier validates it against the engine’s min and max bounds, regenerates the cluster, and preserves the existing nodes’ placement. Removing a node uses the engine’s own decommission path where one exists — nodetool decommission for Cassandra and ScyllaDB, rs.remove() on the primary for MongoDB.
Load balancing (
/load-balance) is for stateless service replicas, not database clusters. Clustered databases are scaled through/scale; the load-balance endpoint rejects cluster-mode services.
Automatic connection wiring
Section titled “Automatic connection wiring”Inspect a cluster’s nodes and connection details with GET /api/v1/resources/{id}/nodes. For distributed clusters, Pier assembles the right connection shape for the engine automatically:
- MongoDB — a replica-set URI listing every node’s mesh address, ending in
?replicaSet=rs0. - Redis — a Sentinel configuration: the list of sentinel addresses plus the master set name your client connects through.
Other engines return their node list without a synthesized URI; you point your application at the primary (or contact points) as appropriate for that engine.
Next steps
Section titled “Next steps”- WireGuard mesh — the overlay distributed clusters depend on.
- Servers & agents — add the servers your cluster nodes run on.
- Projects & services — how databases fit into a project.