# Dokumentasi Teknis Perbaikan MariaBackup GFS (Replica Database Direct to Windows Vault)

**Tanggal Pembaruan**: 31 Agustus 2026  
**Target Server**: Server Database Replica (Slave) $\rightarrow$ Windows Storage Vault  
**Skrip Utama**: [`backup_mariabackup_gfs_direct.sh`](file:///z:/san_29agus/backup_mariabackup_gfs_direct.sh)  
**Status**: Diperbarui & Teruji (Production Ready)

---

## 1. Latar Belakang Masalah (Root Cause Analysis)

### Kronologi Insiden
Saat menjalankan pencadangan incremental maupun full backup di server replica, proses backup mengalami kegagalan mendadak dengan rincian log:
```text
ERROR: Script gagal di baris 173 (Perintah: zstd) dengan exit code 134
ERROR: Incremental Pipeline Gagal!
```

### Investigasi Teknis & Temuan Kunci
1. **Analisa Exit Code 134**:
   Exit code 134 berasal dari sinyal **`SIGABRT` (Signal 6)** yang memicu *core dump*.
2. **Sumber Crash Sebenarnya**:
   Pemeriksaan PID pipeline menunjukkan bahwa proses yang mengalami *abort* adalah **`mariabackup` (bukan `zstd`)**. Trap Bash melaporkan `zstd` karena berada di ujung pipeline dengan flag `pipefail`.
3. **Penyebab Fatal di Level Disk/InnoDB**:
   Log detail MariaBackup `/tmp/mariabackup_local_*.log` mencatat:
   ```text
   [01] Streaming ./run_sumber_boga_modul/transaksi_realtimepos.ibd
   InnoDB: Retry attempts for reading partial data failed.
   InnoDB: Tried to read 10485760 bytes at offset 4582277120, but was only able to read 0
   InnoDB: Operating system error number 61 in a file operation (ENODATA: No data available)
   mariabackup(_Z15xb_fil_cur_readP12xb_fil_cur_tR14CorruptedPages+0x383)
   ```
4. **Akar Masalah (*The Core Problem*)**:
   Tabel `run_sumber_boga_modul.transaksi_realtimepos` (berukuran 7.0 GB) menerima aliran transaksi tinggi secara *real-time* dari Master. Saat MariaBackup sedang membaca blok data pada offset 4.58 GB, proses **SQL Thread Replica (`Slave_SQL_Running`)** terus menulis dan memodifikasi halaman tabel tersebut di disk. Hal ini menyebabkan *file size descriptor* dan posisi *End-Of-File (EOF)* di Linux bergeser (*race condition* / *torn read*), sehingga `mariabackup` mengalami abort demi mencegah korupsi arsip backup.

---

## 2. Arsitektur Solusi: Zero-Write Replica Protection

Berdasarkan *Official Best Practice* dari **MariaDB Knowledge Base** dan **Percona XtraBackup**, proteksi penuh diterapkan dengan mematikan sementara proses eksekusi tulis di Replica selama proses streaming data berlangsung.

```mermaid
sequenceDiagram
    autonumber
    participant B as Skrip Backup
    participant R as MariaDB Replica Engine
    participant V as Windows Storage Vault

    B->>R: STOP SLAVE SQL_THREAD;<br/>SET GLOBAL read_only = ON;<br/>FLUSH TABLES;
    Note over R: Status I/O Thread TETAP AKTIF (Download Binlog terus berjalan).<br/>Seluruh file .ibd di disk 100% STATIS & KONSISTEN.
    
    B->>V: Eksekusi mariabackup --slave-info --lock-ddl-per-table | zstd -3
    Note over V: Data distreaming langsung ke Vault bebas bit-rot & race condition.
    
    B->>R: SET GLOBAL read_only = OFF;<br/>START SLAVE SQL_THREAD;
    Note over R: Replikasi kembali aktif normal & mengejar relay log lokal.
    
    B->>V: Verifikasi SHA256 & Retensi GFS
```

---

## 3. Rincian Pembaruan Kode pada Skrip

Skrip [`backup_mariabackup_gfs_direct.sh`](file:///z:/san_29agus/backup_mariabackup_gfs_direct.sh) telah diperbarui dengan fitur-fitur berikut:

### A. Jaminan Fail-Safe Tingkat Kernel (`trap cleanup EXIT INT TERM HUP`)
Menjamin bahwa dalam kondisi apa pun (Sukses, Gagal di tengah jalan, Error syntax, atau di-cancel via `Ctrl+C`), server replica **pasti dikembalikan ke status normal (Replikasi ON & Read-Only OFF)**:
```bash
cleanup() {
    log ">> Memastikan Replikasi SQL Thread & Mode Database kembali Normal..."
    mysql --user="$DB_USER" --password="$DB_PASS" -e "
        SET GLOBAL read_only = OFF;
        START SLAVE SQL_THREAD;
    " 2>/dev/null || true

    if [ -f "$BACKUP_LOG" ]; then
        mv -f "$BACKUP_LOG" "$LOCAL_LOG_DIR/mariabackup_${DATE}_$$.log" 2>/dev/null || true
    fi
}
trap cleanup EXIT INT TERM HUP
```

### B. Flag Khusus Replikasi MariaBackup
Menambahkan flag resmi pencadangan replica:
* `--slave-info`: Menyimpan koordinat Binlog Master (`xtrabackup_slave_info`) untuk memudahkan disaster recovery / pembuatan replica baru.
* `--safe-slave-backup`: Mengamankan kuncian metadata saat snapshot checkpoint.
* `--lock-ddl-per-table`: Mengunci metadata tabel selama pembacaan `.ibd`.

### C. Isolasi Evaluasi Status Pipeline & Sanitasi Telegram HTML
* Menonaktifkan sementara `trap ERR` di sekitar pipeline (`trap - ERR`) agar exit status MariaBackup vs ZSTD dievaluasi secara terpisah (`${PIPESTATUS[0]}` vs `${PIPESTATUS[1]}`).
* Menyaring karakter `<` dan `>` pada log error menggunakan `sed 's/</\&lt;/g; s/>/\&gt;/g'` agar pesan error dari MariaDB tidak memicu error HTTP 400 di Telegram API.

### D. CIFS Vault Health Check
Fungsi `ensure_vault_mounted` melakukan uji I/O ringan (`ls "$MOUNT_POINT"`) sebelum backup dimulai. Jika terdeteksi *stale handle* akibat gangguan jaringan Windows, skrip melakukan *lazy remount* otomatis dengan parameter performa `cache=loose,wsize=1048576`.

---

## 4. Panduan Operasional (*Operational Runbook*)

### 1. Inisialisasi Ulang Rantai Backup (Full Backup)
Jika rantai LSN sebelumnya rusak atau terputus:
```bash
/path/to/backup_mariabackup_gfs_direct.sh --force-full
```

### 2. Jadwal Otomatis Harian (Cron)
Skrip otomatis mendeteksi hari:
* **Hari Minggu**: Menjalankan Full Backup Mingguan.
* **Senin s.d Sabtu**: Menjalankan Incremental Backup Harian berdasarkan LSN terakhir di `/var/lib/mariabackup_metadata/latest_lsn.txt`.

### 3. Pembersihan Berkas Binlog Yatim (*Orphaned Logs*)
Jika ditemukan berkas log lama yang tidak terdaftar di `SHOW BINARY LOGS;`:
```bash
# Pastikan prefix aktif via: SHOW VARIABLES LIKE 'log_bin%';
# Bersihkan berkas lama yang tidak terdaftar:
rm -f /var/lib/mysql/mariadb-bin.*
```
Serta atur retensi otomatis di MariaDB CLI & `/etc/my.cnf`:
```sql
SET GLOBAL expire_logs_days = 3;
```
```ini
[mysqld]
expire_logs_days = 3
```

---

## 5. Kesimpulan
Dengan arsitektur **Zero-Write Protection** dan **Fail-Safe Multi-Signal Trap**, server Replica terlindungi dari segala risiko *downtime*, kehilangan data, ataupun desinkronisasi replikasi saat proses pencadangan database berlangsung.