MariaDB Replication Explained: How It Works, Topologies, and Setup

• 23 June 2026
• by: Danny Gee
• in: MySQL/MariaDB
• Tags: database high availability, gtid, mariadb administration, mariadb replication, read scaling
• note: no comments

If your application’s database is straining under read traffic, or you need a standby copy of your data ready to take over when a server fails, MariaDB replication is one of the foundational tools that makes both possible. At its core, replication is the process of copying data from one MariaDB server to one or more others, keeping the copies continuously in sync as new writes arrive. Done well, it underpins read scaling, high availability, painless backups, and geographically distributed deployments.

This guide explains what replication actually does under the hood, walks through the modern GTID-based setup process, and is honest about the trade-offs that catch teams off guard, especially the fact that replication is asynchronous by default.

Key Takeaways
• MariaDB replication copies data from a primary (master) server to one or more replicas (slaves) by streaming the primary’s binary log.
• It enables read scaling, high availability and failover, off-host backups, and geographic distribution.
• GTID-based replication is the modern, recommended approach and makes failover and topology changes far simpler than legacy binlog-position replication.
• Replication is asynchronous by default, so replicas can lag and recent writes can be lost on primary failure unless you enable semi-synchronous replication.
• Monitor health with `SHOW REPLICA STATUS`, watching `Seconds_Behind_Source` and the replica I/O and SQL threads.

What is MariaDB replication and how does it work?

Replication keeps a copy of one server’s data on other servers. The source of truth is the primary (historically called the *master*); the copies are replicas (historically *slaves*). MariaDB’s default replication is built on the binary log, an ordered record of every change that modifies data on the primary.

The flow looks like this:

1. The primary writes every data-changing statement or row event to its binary log (`binlog`).
2. Each replica runs an I/O thread that connects to the primary, requests new binary log events, and writes them to a local file called the relay log.
3. Each replica runs an SQL thread (or multiple, with parallel replication) that reads the relay log and applies those events to the replica’s own data, replaying the primary’s changes.

Because the replica simply replays the primary’s change stream, it ends up with an identical copy of the data, lagging only by the time it takes to ship and apply events.

Statement-based vs row-based replication

The binary log can record changes in different formats, set via `binlog_format`:

• STATEMENT logs the literal SQL statements. Compact, but non-deterministic functions (like `UUID()` or some `NOW()` usage) can produce different results on the replica.
• ROW logs the actual before/after row images. Safer and deterministic, at the cost of larger logs. This is the recommended default for most workloads.
• MIXED uses statement-based logging when safe and switches to row-based for non-deterministic statements.

Why use database replication?

Replication is rarely about a single goal. Most production setups benefit from several of these at once:

• Read scaling. Direct read-heavy queries (reports, search, dashboards) to one or more replicas while the primary handles writes. This spreads load and lets you add read capacity by adding replicas.
• High availability and failover. If the primary fails, you can promote a replica to become the new primary, minimizing downtime.
• Off-host backups. Run `mariabackup` or `mysqldump` against a replica so backup I/O never touches the production primary.
• Geographic distribution. Place replicas closer to users in other regions to reduce read latency, or keep a remote replica for disaster recovery.
• Zero-downtime maintenance. Patch or upgrade a replica, verify it, then fail over, instead of taking the whole database offline.

The detail that trips up the most teams: MariaDB replication is asynchronous by default. The primary commits a transaction and returns success to the client *without waiting* for any replica to receive it. This has two consequences you must design around. First, a replica can lag behind the primary, so a read served from a replica may not reflect a write that just succeeded, breaking naive “read-after-write” assumptions. Second, if the primary crashes before a committed transaction reaches any replica, that write is lost even after you promote a replica. If you need stronger guarantees, enable semi-synchronous replication, which makes the primary wait until at least one replica acknowledges receipt before reporting commit success. It is not synchronous (the replica still applies the event later), but it dramatically narrows the window for data loss on failover.

What replication topologies does MariaDB support?

A topology is simply how your primaries and replicas are wired together. The right choice depends on whether you are optimizing for read scaling, write availability, or geographic reach.

Topology	Structure	Best for	Watch out for
Primary-replica (master-slave)	One primary, one or more replicas reading from it	Read scaling, backups, HA standby	Single write point; replica lag
Primary-primary (master-master)	Two servers, each replicating from the other	Active-active writes, faster regional failover	Write conflicts, auto-increment collisions, complexity
Chain (relay)	Primary → intermediate replica → downstream replicas	Reducing load on the primary, multi-tier fan-out	Compounded lag; intermediate node is a dependency
Multi-source	One replica pulls from several primaries	Consolidating data from multiple sources	Schema separation; conflicting datasets

The primary-replica topology is the workhorse and the right starting point for most applications. Primary-primary sounds attractive for write availability but introduces conflict resolution problems: if both servers accept a write to the same row, you can end up with divergent data. Teams that use it typically route all writes for a given dataset to one node at a time, treating the second primary as a hot standby rather than a true active-active write target.

Why is GTID-based replication recommended?

Older MariaDB replication tracked a replica’s position using a binary log file name and offset (for example, `mariadb-bin.000045` at position `19283`). That worked, but it made failover painful: when you promoted a new primary, every other replica needed its position manually recalculated against the new primary’s logs.

GTID (Global Transaction ID) replication assigns every transaction a unique identifier that is consistent across the whole topology. A replica simply asks for “every transaction I haven’t seen yet,” and MariaDB figures out the correct starting point automatically. This makes failover, re-pointing replicas, and topology changes dramatically simpler, which is why GTID-based replication is the modern, recommended approach for new deployments.

How do you set up MariaDB replication?

Here is the basic flow for a GTID-based primary-replica setup. The exact paths and option-file locations vary by distribution, but the steps are consistent.

1. Configure the primary

Edit the primary’s option file (often `/etc/mysql/mariadb.conf.d/50-server.cnf` or `/etc/my.cnf`). Give the server a unique `server-id` and enable binary logging:

“`ini [mariadb] server-id = 1 log_bin = /var/log/mysql/mariadb-bin log_bin_index = /var/log/mysql/mariadb-bin.index binlog_format = ROW

sync_binlog = 1 expire_logs_days = 7 “`

Restart MariaDB for the changes to take effect.

2. Create a replication user

On the primary, create a dedicated account with the `REPLICATION SLAVE` privilege. Each replica authenticates as this user to pull binary log events:

“`sql CREATE USER ‘repl’@’%’ IDENTIFIED BY ‘a-strong-password’; GRANT REPLICATION SLAVE ON *.* TO ‘repl’@’%’; FLUSH PRIVILEGES; “`

In production, restrict the host (`’repl’@’10.0.0.%’`) to your private network rather than `’%’`.

3. Configure each replica

Each replica needs its own unique `server-id`. No two servers in the topology may share one:

“`ini [mariadb] server-id = 2 log_bin = /var/log/mysql/mariadb-bin binlog_format = ROW

read_only = ON “`

4. Take a consistent snapshot

Seed the replica with the primary’s current data. Use `mariabackup` for large datasets, or `mysqldump` with GTID and master-data flags for smaller ones:

“`bash mysqldump –all-databases –master-data=2 –gtid \ –single-transaction –routines –triggers \ -u root -p > primary_snapshot.sql “`

Restore that snapshot onto the replica before starting replication. The `–gtid` flag records the GTID position the dump was taken at.

5. Point the replica at the primary and start

On the replica, set the GTID position to match the snapshot, then configure the connection and start replicating. With GTID, you tell the replica to use its current GTID state:

“`sql SET GLOBAL gtid_slave_pos = “0-1-1234”;

CHANGE MASTER TO MASTER_HOST = ‘10.0.0.1’, MASTER_USER = ‘repl’, MASTER_PASSWORD = ‘a-strong-password’, MASTER_USE_GTID = slave_pos;

START REPLICA; “`

Newer MariaDB versions also accept the clearer `CHANGE REPLICATION SOURCE TO … START REPLICA` syntax, which mirrors the modern primary/replica terminology.

How do you monitor MariaDB replication health?

The single most important command is `SHOW REPLICA STATUS` (or the legacy `SHOW SLAVE STATUS`):

“`sql SHOW REPLICA STATUS\G “`

Watch these fields closely:

• `Replica_IO_Running` and `Replica_SQL_Running` must both read `Yes`. If either is `No`, replication has stopped.
• `Seconds_Behind_Source` (legacy `Seconds_Behind_Master`) reports the estimated replica lag in seconds. A steadily rising value signals the replica cannot keep up.
• `Last_IO_Error` and `Last_SQL_Error` explain why replication broke when a thread stops.
• `Gtid_IO_Pos` shows the GTID position the replica has reached, useful for confirming topology consistency.

For production, wire these into your monitoring stack and alert on stopped threads or lag crossing a threshold rather than checking by hand.

What are the common gotchas with MariaDB replication?

• Replica lag. Under heavy write bursts or with slow replica hardware, `Seconds_Behind_Source` climbs. Mitigate with parallel replication, faster storage, and by not overloading replicas with expensive read queries.
• Asynchronous data loss. As covered above, the default async mode can lose recently committed writes on primary failure. Use semi-synchronous replication where durability matters.
• Read-after-write inconsistency. A user who just saved data may read a stale replica that has not yet applied the change. Route critical “read your own write” queries to the primary, or use semi-sync plus lag-aware routing.
• Master-master conflicts. In primary-primary topologies, simultaneous writes to the same row diverge. Avoid true active-active writes on shared rows, and configure `auto_increment_increment` / `auto_increment_offset` to prevent ID collisions.
• Replication breaking on errors. A duplicate key or missing row on a replica halts the SQL thread. Investigate the real cause rather than blindly skipping events, which can silently drift your data.
• Forgetting `read_only`. Without `read_only = ON`, an application or admin can accidentally write directly to a replica, creating divergence that replication cannot reconcile.

Frequently asked questions

Is MariaDB replication synchronous or asynchronous? By default it is asynchronous: the primary commits and returns success without waiting for replicas. You can enable semi-synchronous replication so the primary waits for at least one replica to acknowledge receipt before reporting commit, which reduces the risk of losing recent writes during failover. Fully synchronous replication requires a different architecture, such as Galera Cluster.

What is the difference between MariaDB replication and Galera Cluster? Standard replication is asynchronous and primary-replica oriented, with one write node by default. Galera Cluster provides synchronous, multi-primary replication where every node can accept writes and transactions are certified across the cluster before commit. Replication is simpler and more flexible for read scaling and geo-distribution; Galera offers stronger consistency for active-active writes.

Can a MariaDB replica also be a primary for other replicas? Yes. In a chain (relay) topology, an intermediate replica enables binary logging (and `log_slave_updates`) so it relays the changes it receives to downstream replicas. This offloads fan-out from the top-level primary, at the cost of additional lag at each tier.

How do I reduce replica lag in MariaDB? Enable parallel replication so multiple SQL threads apply events concurrently, use fast storage (NVMe SSDs) on replicas, ensure a low-latency network between nodes, keep heavy ad-hoc read queries off lag-sensitive replicas, and use ROW binlog format to avoid expensive statement re-execution.

Do I need GTID to use MariaDB replication? No, you can still use legacy binary-log-position replication, but GTID is strongly recommended for new deployments because it makes failover and re-pointing replicas far simpler and less error-prone.