---
order: 1
summary: 'Hosted MariaDB Galera clusters: synchronous multi-master replication behind
  a single load-balanced endpoint.'
title: Scuttle
path: index
status: published
---

# Scuttle

Scuttle is the ScaiLabs **hosted MariaDB Galera cluster system** — provision a
synchronous multi-master cluster, reach it through one load-balanced endpoint,
and let Scuttle handle node recovery, backups, upgrades and monitoring.

> This namespace is freshly bootstrapped. Real content lands here as the
> Scuttle team ships. Watch this space for the provisioning guide, the
> connection reference, and the operational runbooks.

## What Scuttle provides

- **Synchronous multi-master replication.** Galera write-set replication, so
  every node holds the same committed data. Any node can take writes; there
  is no primary to fail over.
- **A single endpoint.** Clients connect to one load-balanced hostname
  rather than tracking individual nodes, so node replacement is invisible to
  applications.
- **Quorum management.** The cluster keeps a Primary component and evicts
  partitioned nodes, protecting against split-brain.
- **Automatic node recovery.** A node that falls behind rejoins by state
  transfer (IST where possible, SST when it has drifted too far) and returns
  to `Synced` without operator action.
- **Backups and point-in-time recovery.** Scheduled logical and physical
  backups with retention policy, plus restore into a fresh cluster.
- **Rolling upgrades.** Minor-version and configuration changes applied node
  by node, keeping the cluster writable throughout.
- **Observability.** Cluster size, quorum status, node state, replication lag
  and flow control exposed for alerting and dashboards.

## Cluster anatomy

A Scuttle cluster is a set of MariaDB nodes plus a load-balanced entry point:

```
  clients ──▶  <cluster>-lb1        single endpoint clients connect to
                    │
      ┌─────────────┼─────────────┐
      ▼             ▼             ▼
  <cluster>-n1  <cluster>-n2  <cluster>-n3     Galera nodes, all writable
```

Health is read from the standard wsrep status variables:

| Variable | Healthy value | Meaning |
|---|---|---|
| `wsrep_cluster_status` | `Primary` | This component holds quorum |
| `wsrep_cluster_size` | node count | Nodes currently in the component |
| `wsrep_local_state_comment` | `Synced` | Node is caught up and serving |
| `wsrep_connected` | `ON` | Node is attached to the group |

A quick health check from any client:

```sql
SHOW STATUS WHERE Variable_name IN (
  'wsrep_cluster_status',
  'wsrep_cluster_size',
  'wsrep_local_state_comment',
  'wsrep_connected'
);
```

## Application guidance

Two Galera characteristics are worth designing around:

- **Use InnoDB.** Write-set replication only covers transactional storage
  engines; MyISAM tables are not replicated reliably.
- **Expect deadlocks at commit.** Conflicting writes on different nodes are
  resolved by certification, surfacing as a deadlock error on `COMMIT`
  rather than at statement time. Retry the transaction.

## Where it fits

Scuttle is a **platform primitive** — the database layer other ScaiLabs
products run on. ScaiCMS, ScaiKey, ScaiSend and others store their relational
state in Scuttle clusters, alongside Storey for object storage and ScaiVault
for secrets. ScaiLog receives cluster events for centralised alerting.

## For operators

Provisioning, sizing, quorum and arbitrator configuration, backup policy,
upgrades, and node-replacement runbooks will land under
`/docs/scuttle/operating/`.

## For application developers

Connection strings, driver and pooling guidance, transaction and retry
patterns, and schema-migration practice on a multi-master cluster will land
under `/docs/scuttle/using/`.

## For integrators

Provisioning API, metrics endpoints, backup/restore automation and webhook
events will land under `/docs/scuttle/api/`.

## Status

| Item                              | State        |
|-----------------------------------|--------------|
| Namespace bootstrapped            | ✅ done       |
| Provisioning API                  | 🚧 pending    |
| Backup and PITR                   | 🚧 pending    |
| Rolling upgrades                  | 🚧 pending    |
| Metrics and alerting              | 🚧 pending    |
| ScaiLog event forwarding          | 🚧 pending    |

More content lands here as the Scuttle team ships.