To configure a Galera cluster, you need a MySQL-compatible server built with wsrep support, the matching Galera provider, a consistent cluster configuration on every host, and a deliberate bootstrap of exactly one node. Install and configure all nodes first, start one new cluster with --wsrep-new-cluster (or the distribution’s bootstrap command), then start every other node normally. Never leave an empty gcomm:// address in persistent configuration and never use the new-cluster flag for an ordinary restart.
Antihost offers Linux VPS plans with full root access, unlimited traffic on a 1 Gbps port and a 14-day free trial.
“MySQL” is not a single Galera packaging target. MariaDB Galera, MySQL wsrep builds and vendor distributions can use different package names, provider paths, service units, SST methods and bootstrap commands. Confirm those details for the exact release you installed before applying any example below.
As an Amazon Associate I earn from qualifying purchases.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →What a Galera-enabled MySQL server requires
Galera is not enabled simply because a normal MySQL-compatible server is installed. The server binary must contain wsrep integration, and the Galera provider library must be installed and loadable. The server then needs explicit wsrep and replication settings in its option file. If either the wsrep-enabled server or provider is missing, settings such as wsrep_cluster_address will not turn an ordinary standalone server into a cluster member.
Galera nodes exchange replicated database state over a group-communication address. A node joining after an outage may receive an incremental state transfer (IST) when the required write history is available, or a full state transfer (SST) when it is not. The transfer method, donor selection and credentials are distribution-specific, so choose and test them as part of the deployment rather than copying a method intended for another package.
#1 Best Overall
Choose and verify the exact distribution first
Before editing my.cnf, record the server and provider versions on every host. Keep the wsrep-enabled server, Galera provider generation and supporting packages compatible. Do not assume that a configuration written for MariaDB uses the same library path or systemd unit as a MySQL wsrep build.
| Implementation choice | What must be checked | Why it matters |
|---|---|---|
| MariaDB Galera | MariaDB release, Galera provider package, provider library path, service name and documented bootstrap command | MariaDB documentation supplies the common option names and port defaults, but package paths and service integration still vary by release. |
| MySQL wsrep build | Exact wsrep-enabled build, provider generation, option-file location, systemd unit and bootstrap procedure | A stock MySQL package without wsrep support cannot join a Galera cluster. |
| Vendor distribution such as Percona XtraDB Cluster | Vendor-specific SST tooling, credentials, service wrappers and recovery instructions | Vendor defaults can change the SST method and the command used to create the first primary component. |
Check that the provider file exists at the path you intend to use and that the service account can load it. If the package supplies a sample configuration, use its path and unit names as the starting point. Label your internal runbook with the tested vendor and version; there is no universal MySQL Galera command that is safe for every distribution.
Plan names, addresses and traffic before installation
Give every node a stable identity
Choose one cluster name and use it on every node. Assign each node a unique wsrep_node_name and a stable, reachable wsrep_node_address. The node address should be the address other database hosts can actually route to, not merely a loopback address or an unadvertised cloud interface.
In a cloud host or a machine with multiple interfaces, bind and advertise the intended address explicitly. Verify forward and reverse DNS if you use hostnames, and make sure the names resolve consistently from every node. A node that can reach its own address but cannot be reached by its peers will fail discovery or state transfer.
Rank #2
Decide which traffic is allowed
MariaDB’s Galera reference documents these default roles. Change the values if your configuration changes the ports, and apply the same decision to firewall rules and security groups.
| Purpose | Default port | Required access |
|---|---|---|
| Normal database client traffic | 3306 | Application networks to the nodes that serve clients |
| Galera group communication | 4567 | Bidirectional node-to-node access |
| Incremental state transfer (IST) | 4568 | Bidirectional node-to-node access |
State transfer (SST) methods other than mysqldump |
4444 | Donor to joiner, and any additional direction required by the selected method |
Do not expose replication ports to untrusted networks. Permit only the cluster’s addresses and the administrative sources that need database access. A successful TCP test to port 3306 does not prove that Galera traffic on 4567, IST on 4568 or SST on 4444 is usable.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Install the wsrep server and provider on every host
- Install the wsrep-enabled server package for the chosen distribution on each host. A normal MySQL server package is insufficient.
- Install the matching Galera provider package and note its full library path. The path in examples such as
/usr/lib/galera/libgalera_smm.sois only an example; use the path supplied by your package. - Install or select an SST implementation supported by that distribution. Record its method name, required helper packages and authentication settings.
- Keep package versions aligned unless the vendor explicitly documents a mixed-version upgrade path. A node with an incompatible provider or wsrep interface can fail before it makes a network connection.
- Stop the database service while you are preparing the cluster configuration. Do not let multiple unconfigured services start and form accidental standalone instances.
Use the service and package names supplied by your platform. Some systems call the service mysql, others mariadb or use a vendor-specific unit. The unit name is not evidence that the installed binary has wsrep support; verify the binary and provider separately.
Build the common option-file configuration
Put the shared settings in the option file read by the server, commonly a file included by my.cnf. Use the same cluster identity and peer list on every node, changing only values that are explicitly node-specific.
[mysqld]
wsrep_on=ON
wsrep_provider=/path/to/the/installed/libgalera_smm.so
wsrep_cluster_name=production-galera
wsrep_cluster_address=gcomm://db1,db2,db3
wsrep_node_name=db1
wsrep_node_address=10.0.0.11
binlog_format=ROW
default_storage_engine=InnoDB
wsrep_sst_method=your-supported-methodThe provider path, SST method and addresses in this example are placeholders for values from your installation plan. Replace them before starting the service.
What each required setting does
wsrep_provider: points to the Galera provider library. An incorrect path produces a provider-load error and prevents wsrep startup.wsrep_cluster_address: lists peer addresses in thegcomm://form. Use reachable hostnames or IP addresses and keep the peer list consistent across nodes. It is a discovery list, not a license or a guarantee that every listed host is online.binlog_format=ROW: sets row-based binary logging, the format required by the documented Galera configuration.wsrep_on=ON: enables wsrep replication for the server. A server can start with wsrep disabled and look healthy while remaining outside the cluster, so check the effective value after startup.default_storage_engine=InnoDB: makes InnoDB the default engine. Review existing schemas for tables using another engine before putting them into replicated production service.wsrep_cluster_name: provides a shared identity so nodes intended for one cluster do not silently join a differently named deployment.wsrep_node_nameandwsrep_node_address: identify the individual member. These values must be unique and reachable for each node.wsrep_sst_method: selects the state-transfer mechanism supported by your distribution. Its helper programs, credentials and firewall requirements must be configured before a join is attempted.
Do not add an empty gcomm:// value to this persistent file. An empty address tells a server to create a new cluster. If it remains in the option file, every restart can create a new cluster instead of rejoining the existing one.
Validate the configuration before the first start
- Check that the provider library exists, is readable by the database service account and matches the wsrep-enabled server build.
- Resolve every hostname in
wsrep_cluster_addressfrom every node. Test the advertisedwsrep_node_addressin both directions. - Check firewall and security-group rules for 4567, 4568 and the SST port required by your method, in addition to client port 3306 where applications connect.
- Confirm that each node has a unique node name and address, while the cluster name and peer list are shared.
- Check the SST account, authentication file or helper configuration required by your chosen method. A node can discover peers successfully and still fail during the transfer because credentials are wrong.
- Review the service’s effective option-file search path. Editing a file that the running unit does not read creates a misleading configuration review.
Start with all nodes stopped. This avoids accidentally creating independent database instances while you are still correcting addresses or provider settings.
Bootstrap exactly one new cluster
The first startup is different from a normal restart. One node must be told that no existing primary component is available. The documented warning is: “Do not use the –wsrep-new-cluster option when connecting to an existing cluster.” Treat this flag as a one-time creation operation, not as a general startup option.
Rank #4
- Choose the node whose data directory will seed the new deployment. For a genuinely new installation, it should be initialized with the intended schema and configuration. For recovery after an outage, use the recovery procedure described below instead of choosing arbitrarily.
- Start that node with the platform’s transient bootstrap mechanism. Depending on the distribution, this may be
mysqld --wsrep-new-cluster,galera_new_cluster,mysqld_bootstrapor a systemd wrapper. Use the command documented for your exact package. - Watch the service log until the provider starts and the node reports a primary component. A process that merely stays running is not proof of cluster membership.
- Connect locally and inspect wsrep status before adding application traffic. Confirm that the cluster size and primary state are what you expect.
- Start each remaining node with its ordinary service command, without
--wsrep-new-cluster. It should discover the bootstrap node throughwsrep_cluster_addressand obtain IST or SST as required.
Do not save the new-cluster flag in the persistent service definition. A later restart must use the normal start path and rejoin the existing cluster.
Confirm membership from SQL and logs
Run status checks on every node after it starts. The exact status output can vary by server release, but these variables are the essential checks:
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteSHOW STATUS LIKE 'wsrep_cluster_size';
SHOW STATUS LIKE 'wsrep_cluster_status';
SHOW STATUS LIKE 'wsrep_local_state_comment';
SHOW STATUS LIKE 'wsrep_ready';
SHOW STATUS LIKE 'wsrep_connected';
SHOW VARIABLES LIKE 'wsrep_on';
SHOW VARIABLES LIKE 'wsrep_cluster_address';
SHOW VARIABLES LIKE 'wsrep_provider';wsrep_cluster_sizeshould equal the number of members you expect.wsrep_cluster_statusshould show a primary component rather than a non-primary state.wsrep_local_state_commentshould indicate that the node is synced before it serves normal application traffic.wsrep_readyshould be ready for client operations, andwsrep_connectedshould confirm a provider connection.- The effective provider, cluster address and wsrep setting should match the file you intended to deploy.
Read the service log at the same time. Look for provider-load failures, address or name-resolution errors, authentication failures, donor selection messages and SST or IST completion. A standalone server can accept local SQL connections while never joining the primary component, so SQL availability alone is not a membership test.
How joining nodes receive state
IST: incremental state transfer
When the donor retains the transactions the joining node needs, Galera can transfer only the missing history through IST. This normally reduces the amount of data moved and shortens recovery, but it depends on the donor’s available write-set history and the node’s state.
Best Value
- Used Book in Good Condition
SST: full state transfer
If the required history is unavailable, the joiner needs a full state transfer. The selected SST method determines whether the donor blocks writes, which helper packages are required, how credentials are supplied and which ports are used. MariaDB’s reference lists port 4444 for SST methods other than mysqldump; verify the actual method and any additional ports in your distribution documentation.
Plan donor capacity before adding a node. A transfer can consume disk, CPU, network bandwidth and donor resources. Keep the joiner out of application traffic until its local state reports synchronized and the cluster size is correct.
Recover safely after a complete outage
A full outage is not the same as restarting one member while the cluster remains primary. If every node stopped, first determine which node has the most advanced sequence state. Galera records recovery metadata in grastate.dat. The documented recovery process uses the node with the latest state, sets safe_to_bootstrap: 1 in that node’s metadata when appropriate, and then runs galera_new_cluster or the equivalent bootstrap command.
- Keep all database services stopped so that multiple nodes cannot bootstrap separate components.
- Inspect each node’s
grastate.datand other provider logs to identify the node with the most advanced sequence state. Do not select a node solely because it is the first host in your inventory. - Follow the distribution’s documented safe-to-bootstrap procedure. If the metadata identifies the correct node, use that node for the recovery bootstrap; do not casually edit the file on an arbitrary host.
- Bootstrap only that node with the platform’s recovery command, commonly
galera_new_clusterin MariaDB-based systems. - Verify primary membership and state on the recovered node, then start the remaining nodes normally so they rejoin and receive IST or SST.
Using an empty gcomm:// or repeatedly applying --wsrep-new-cluster is not a recovery strategy. It can create a new cluster identity and leave nodes or applications divided between independent components.
Troubleshoot a node that will not join
| Observed symptom | Likely area | Checks and corrective action |
|---|---|---|
| Provider cannot be loaded | Package or path mismatch | Confirm that the wsrep-enabled server is installed, the Galera library exists at the configured path, permissions allow the service to read it, and the provider generation matches the server. |
| Node starts as a standalone server | wsrep disabled or wrong option file | Check wsrep_on, the effective option-file path and the server log. A running process or successful local login does not prove membership. |
| Cannot discover peers | Cluster address, DNS or firewall | Compare wsrep_cluster_address on all nodes, resolve every name, test the advertised node addresses and permit bidirectional traffic on 4567. |
| IST fails and SST begins | Missing write history | Confirm that an SST fallback is installed and configured. Check donor availability, disk space, method-specific credentials and the required transfer port. |
| SST authentication fails | Account or helper configuration | Recheck the SST account, secret files, ownership and method name. Ensure the donor and joiner use compatible helper versions. |
| State transfer times out | Port filtering or overloaded donor | Permit the selected SST port, verify routing and security groups, inspect donor resource pressure and read the service log for the specific timeout stage. |
| Cluster reports non-primary | Quorum or accidental bootstrap | Stop any unintended standalone component, identify the legitimate surviving component and follow the documented recovery procedure rather than bootstrapping another node at random. |
| Node rejoins the wrong cluster | Stale or empty discovery configuration | Remove any persistent empty gcomm://, restore the intended peer list and confirm the cluster name and node identity before restarting normally. |
Collect the service log from the first failed startup, not only the final error after repeated retries. Early provider, DNS or authentication messages usually identify the fault more precisely.
Quick Recap
Operational practices that prevent repeat failures
- Keep a versioned copy of the option file, provider package version, SST method and service-unit override used on each host.
- Document which address is advertised when a host has public, private and management interfaces.
- Monitor cluster size, primary status, local state, readiness and connection state, not just whether the database process is running.
- Test a planned node restart without any bootstrap flag. The expected behavior is a normal rejoin, not creation of a new cluster.
- Test a controlled state transfer in a maintenance window so that credentials, firewall rules and disk capacity are known before an emergency.
- Keep the full-outage recovery runbook with the location of
grastate.dat, the approved bootstrap command and the criteria for selecting the most advanced node. - Do not assume a node is safe for application traffic until it is synchronized and the cluster has the expected primary membership.
A practical first-deployment checklist
- Choose one wsrep-enabled distribution and record its exact release.
- Install the matching provider and verify its library path on every host.
- Assign a shared cluster name, a unique node name and a reachable node address for each host.
- Set
wsrep_cluster_address,binlog_format=ROW,wsrep_on=ONanddefault_storage_engine=InnoDB. - Select an SST method supported by that distribution and configure its credentials and helper packages.
- Allow client, Galera, IST and SST traffic on the ports your deployment actually uses; the documented defaults are 3306, 4567, 4568 and 4444 respectively.
- Start one node with the transient new-cluster mechanism only.
- Verify primary membership and synchronized state from SQL and logs.
- Start all other nodes normally, without the new-cluster flag.
- Verify the final cluster size and readiness on every member before directing production traffic.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Recommended Free Tools
