MariaDB / MySQL / Percona auto-clustering

For MariaDB, MySQL, and Percona, the Stack Harbor PaaS auto-clustering switch builds a production database cluster from the topology wizard. The cluster ships with replication, autodiscovery of new members, an integrated load-balancing tier, and automatic exclusion of unreachable nodes.

The benefits are concrete:

• High availability — preconfigured replication: primary-secondary, primary-primary, Galera, XtraDB.
• Scalability and autodiscovery — nodes added by horizontal scaling are joined to the cluster automatically.
• Load balancing — every cluster gets two ProxySQL nodes that split read and write traffic.
• Automatic failover — nodes that go unreachable or fall too far behind are excluded from the cluster and re-added when they catch up.

Enable auto-clustering

Click New Environment, pick MariaDB / MySQL / Percona, then turn on Auto-Clustering. A scheme drop-down appears with the options that apply to the engine:

• MariaDB — primary-secondary, primary-primary, Galera.
• MySQL — primary-secondary, primary-primary.
• Percona — primary-secondary, primary-primary, XtraDB.

Pick the scheme, set the node count, and configure the rest of the environment as usual.

What you get out of the box

Two ProxySQL nodes in front of the cluster

Every MariaDB / MySQL / Percona auto-cluster gets two ProxySQL nodes by default, sitting in front of the database tier. If you don’t need them, you can exclude them at the topology stage. You cannot add them later — that decision is permanent once the cluster is created.

Generated credentials, or your own

The platform generates database credentials during creation and emails them to you. To override them with your own, click Variables and add two entries before applying:

• DB_USER
• DB_PASS

Apply, and the custom credentials are emailed to you with the same access details (phpMyAdmin on the primary, cluster entry point).

Horizontal scaling extends the cluster

For primary-secondary and primary-primary topologies, scale-out adds a new secondary by cloning an existing secondary node. Once cloning is done, the new node catches up via binlog replay. Because the source is a secondary (not the primary), the binlog never expires during the operation, and scale-out completes in a short window.

Layer isolation from SLB

For each layer in the cluster, you choose whether it is exposed outside the environment through the platform’s SLB or not. Use this to expose only the ProxySQL entry point when applications are inside the same environment, or expose more layers when an external app needs direct access.

After installation — access details

The platform emails you a sequence of messages once the cluster is up:

• phpMyAdmin at primary — web admin with credentials for interactive database management.
• Cluster entry point — hostname and credentials your application uses. The hostname is proxy.${envName}.${platformDomain}.
• ProxySQL web panel — read-only UI for connection statistics, query performance, and backend health.

If you create custom database accounts after the cluster is up and want them to work through ProxySQL, you must add them to the mysql_users table on each ProxySQL node. From a shell on each ProxySQL node:

MYSQL_PWD=admin mysql -h 127.0.0.1 -P6032 -uadmin -e \
  "INSERT INTO mysql_users (username,password,default_hostgroup) VALUES ('<username>', '<password>', 2);"
MYSQL_PWD=admin mysql -h 127.0.0.1 -P6032 -uadmin -e \
  "LOAD MYSQL USERS TO RUNTIME; SAVE MYSQL USERS TO DISK;"

Without that step, connections from a freshly created database account will fail at the proxy layer.

Which replication scheme to pick

Primary-secondary

The most common pattern. One node accepts writes; reads can be spread across secondaries. Pros: good write consistency, low write latency (the primary commits locally before propagating), read throughput scales with secondaries, secondaries can be used for backups and analytics without impacting the primary. Cons: no automatic failover when the primary fails — promotion is a manual or external-tooling operation.

Primary-primary

Two primaries with asynchronous replication between them. Scale-out adds secondaries, which are distributed evenly between the two primaries. Pros: writes can be balanced across both primaries, recovery from a single-primary failure is simpler. Cons: still asynchronous — conflicting concurrent writes are possible if your application does not partition write keys.

Galera (MariaDB) and XtraDB (Percona)

Multi-primary synchronous replication: every transaction is broadcast to all cluster nodes at commit time. Pros: reads and writes can go to any node, scaling reads and writes is automatic, removing or adding a node does not require manual coordination, data-loss protection is strong because nothing is committed until all members have it, the application does not need to know about read / write splitting. Cons: write latency includes the slowest member; the cluster is more sensitive to network conditions between members.

Related pages

• What is auto-clustering — when to enable it and what is configured.
• Auto-clustering via topology wizard — the wizard-level reference.
• PostgreSQL auto-clustering — the PostgreSQL equivalent of this page.
• MongoDB auto-clustering — for NoSQL workloads.
• Database hosting overview, multi-region cluster, and the cluster recovery, backup / restore, and corruption diagnostic add-ons.