Wiunix
Talk to an Engineer
← Start of tutorial

WIUNIX ACADEMY

Install MariaDB primary-replica replication with GTID and TLS

Page 6 of 6. Review the earlier steps and prerequisites before continuing.

YOUR SYSTEM. YOUR STEPS.

Where are you working?

Choose your OS and version. The prerequisites, commands and troubleshooting follow your environment.

Debian 12Reviewed against official documentation ·

USE YOUR OWN VALUES

Configure this tutorial

Set the example values for your environment; related explanations and copy panels update together. Never enter passwords, private keys or tokens. Values stay in this tab and are not sent to the server or share links. Check actual DNS, certificates and network policy before running commands.

Different IP addresses, domains or ports? Open the settings below, change the values and select “Apply to tutorial”, then copy the updated commands.

Set values for my environment3 editable values
29

LET’S BUILD

Stop replication without deleting data or metadata

Replica only. Record status privately before stopping. Validate the edited option; stop the channel and confirm No/No and retained rows. Do not reset master/replica, delete relay/binlogs, skip transactions or wipe the data directory. This is a reversible operational pause, not a consistency repair. If the primary is still read-only because bootstrap was aborted, release that pause only after deciding it is the sole authoritative writer; the primary release panel is the explicit command.

Bash

Replica

(
set -euo pipefail
sudo mariadbd --verbose --help >/dev/null
sudo mariadb -e "SHOW SLAVE STATUS\G; STOP SLAVE; SHOW SLAVE STATUS\G; SELECT * FROM academy_lab.replication_probe ORDER BY id;"
)
How do I know it worked?

No/No threads, original rows/logs/connection metadata retained; read_only remains1.

30

LET’S BUILD

Resume only from a known consistent position

Optional, after repairing the cause and confirming all needed primary binlogs still exist and data is consistent. Remove only the skip_slave_start line with this editor; keep read_only and all channel settings. If history expired or data drifted, keep this replica paused and build a separately fresh replacement from a new verified seed; do not overwrite its retained data.

Bash

Replica

sudo nano /etc/mysql/mariadb.conf.d/90-academy-replication.cnf
How do I know it worked?

Only skip_slave_start removed after a successful consistency/retention review.

31

LET’S BUILD

Start and recheck both stages

Replica only, after the preceding consistency decision. No service restart is required to explicitly start the existing channel. Repeat exact GTID wait and row verification using the primary’s actual current target. A successful start is not proof of identical data.

Bash

Replica

(
set -euo pipefail
sudo mariadbd --verbose --help >/dev/null
sudo mariadb -e "START SLAVE; SHOW SLAVE STATUS\G; SELECT @@read_only,@@GLOBAL.gtid_slave_pos;"
)
How do I know it worked?

Yes/Yes with zero errors; read_only1; bounded GTID wait/data comparison repeated successfully.

Promotion needs fencing and a separate runbook

This tutorial deliberately stops short of promotion. Planned switchover requires a real write fence (including privileged sessions), a final committed position, confirmed replica catch-up, routing changes and a safe way to rejoin the old node. Unplanned primary loss may lose acknowledged transactions; a zero lag sample does not establish zero RPO. Never make both writable or rejoin an old primary blindly. Replica reads can be stale; read-after-write-sensitive requests stay on the primary.

Diagnose the failing stage before recovery

Run only the relevant diagnostic panel, on the named host. Logs may contain internal names and authentication details; redact before sharing. Missing binlogs or row drift require a new consistent seed on a separate fresh replacement, never guessed positions or skipped errors.

Service refuses startup

On the affected host inspect option errors, missing certificate/key permissions and private bind address. Correct that file with the earlier editor, validate again, then use that host’s explicit restart panel. Do not start a second daemon on the same data directory.

Bash
sudo mariadbd --verbose --help >/dev/null
sudo systemctl status mariadb --no-pager
sudo journalctl -u mariadb -n 60 --no-pager
ip -br address
Receiver is not Yes

Replica: distinguish DNS/TCP failure from1045 credentials or TLS certificate errors in Last_IO_Error. Check actual source IP and the primary firewall with its earlier panel. Do not disable TLS verification or widen the account host to a wildcard.

Bash
getent ahostsv4 db-primary.example.internal
sudo mariadb -e "SHOW SLAVE STATUS\G"
sudo -u mysql test -r /etc/mysql/tls/ca.pem
sudo journalctl -u mariadb -n 60 --no-pager
Applier stops or GTID wait times out

Replica:1062 duplicate row,1032 missing row or GTID out-of-order indicates drift/incorrect seeding; do not skip or reset. Keep the node out of reads and retain it for diagnosis using the pause procedure. A wait timeout can also mean normal backlog; inspect both threads, errors and storage before deciding.

Bash
sudo mariadb -e "SHOW SLAVE STATUS\G; SELECT @@GLOBAL.gtid_slave_pos;"
df -h /var/lib/mysql
df -i /var/lib/mysql
sudo journalctl -u mariadb -n 60 --no-pager
Required primary binlogs expired

Primary: compare available binary logs with receiver error1236 and your retained seed position. Do not purge/reset history or reuse an old seed with a newer GTID. Preserve this node; provision a separate fresh replica from a new consistent seed. Increase future retention only after sizing disk.

Bash
sudo mariadb -e "SHOW BINARY LOGS; SELECT @@GLOBAL.gtid_binlog_pos,@@binlog_expire_logs_seconds;"
df -h /var/lib/mysql
Certificate renewal changes trust

Primary: check validity, SAN and matching key using the earlier certificate panel. Replica: retain strict verification and deliver an approved overlapping CA chain before a CA rotation. A primary restart disrupts connections; schedule it and recheck both threads and data afterward. Never share private keys/logs to debug a public ticket.

Bash
sudo openssl x509 -in /etc/mysql/tls/server.pem -noout -dates -ext subjectAltName
sudo openssl x509 -in /etc/mysql/tls/server.pem -checkend 604800 -noout

Operate the replica as a monitored dependency

Alert on either stopped thread, nonzero replication errors, stale progress, growing relay logs, disk/inodes, certificate expiry and backup/restore failures. Keep a separate recovery plan and review access/retention regularly. Replication credentials grant access to the binary-log stream; treat the replica as a trusted data holder. Distribute reads only after measuring acceptable staleness and testing application behavior. Continue with backup restoration and a fenced switchover exercise in a separate lab.

GO TO THE SOURCE

Official references

Each environment states how it was reviewed. A documentation review does not claim a hands-on test of every version.

KEEP LEARNING

Your next step

Databases

Build a Prometheus + Grafana monitoring stack

Install Prometheus, node_exporter and Grafana with private access, validated configuration and checks that prove metrics reach your dashboard.

Continue learning ↗Databases

Install WordPress on Nginx with a privacy-safe FastCGI cache

Install WordPress, PHP-FPM and MariaDB over HTTPS, then cache only reviewed public pages and prove that sessions and password-protected content stay separate.

Continue learning ↗
Explore all tutorials ↗