Backup database dengan Litestream

Ketika ngomongin backup database SQLite ane ada 2 pilihan yaitu backup full compress atau memanfaatkan WAL. Untuk yang full adalah membuat salinan database yang kemudian dikompresi dengan tar.xz dan dikirim ke clouds, seperti yang sudah ane lakukan dengan Restic atau Rclone. Meski sangat handal, memakai cara ini memiliki sedikit kekurangan yaitu database harus dalam idle state (tidak ada proses baca tulis) dan data yang disimpan mengikuti update waktu saat dilakukan penyimpanan atau backup.

Misal database di-backup setiap jam 24 maka jika di jam 03 terjadi masalah maka data yang tersedia untuk di-restore hanya data saat jam 24 tersebut. Sehingga data antara jam 24-03 tidak tersedia, pengorbanan yang memang harus diterima sampai kemudian datang aplikasi bernama Litestream dengan misi untuk fully-replicated database with no pain and little cost¹.

Ane akan pakai Litestream untuk backup database SQLite yang ane pakai di Gotosocial yang juga sudah mendukung pemanfaatan Litestream dengan baik. Beberapa keterangan yang tersedia sebagai berikut:

Mempersiapkan database Gotosocial #

Agar bisa memanfaatkan Litestream untuk membackup database SQLite maka perlu mengaktifkan WAL Mode atau Write-Ahead Logging. Di Gotosocial untuk mengaktifkan ini perlu menambahkan pengaturan di file config.yaml seperti berikut

db-sqlite-journal-mode: "WAL"
db-sqlite-synchronous: "NORMAL"

Litestream #

Ane pakai #FreeBSD, btw. versi Litestream yang ane pakai adalah versi stabil 0.33 sedangkan versi terakhir adalah 0.5, alasannya adalah karena 0.33 lebih stabil menurut ane dan masih pakai mode WAL klasik².

Masalah lainnya adalah alih - alih menjanjikan ukuran backup yang lebih hemat penyimpanan, pengalaman ane memakai versi 0.5 malah sebaliknya. Backup database bengkak menjadi 4-5 kali lipat padahal proses baru berjalan kurang dari 24 jam.

Sedangkan versi 0.3 malah lebih hemat karena hasil backup untuk database yang sama hasilnya mirip dengan ukuran database aslinya, selisih pun tidak signifikan. Berikut adalah perbandingan antar versi Litestream yang pernah ane pakai:

Build manual #

Masalahnya paket 0.33 sudah tidak tersedia di repositori FreeBSD maka ane perlu membuild secara manual.

$ mkdir tmp && cd tmp
$ fetch https://github.com/benbjohnson/litestream/archive/refs/tags/v0.3.13.tar.gz
$ tar -xf v0.3.13.tar.gz
$ cd litestream-0.3.13
$ go build -tags osusergo,netgo -ldflags "-X main.version=0.3.13" ./cmd/litestream

karena litestream dibuat dengan Golang, maka minimal harus ada Golang versi 1.21. Tunggu sampai selesai akan muncul file litestream. Pindahkan ke /usr/local/bin dan beri atribut eksekusi.

$ cp litestream /usr/local/bin/litestream
$ doas chmod +x /usr/local/bin/litestream

Konfigurasi #

Umumnya Litestream menyimpan konfigurasi dalam bentuk berkas yaml atau yml³ dan ditaruh di folder /etc/, Sehingga path lengkap dari berkas konfigurasinya adalah /etc/litestream.yml.

dbs:
  - path: /var/www/database/egois.db
    lock-timeout: 30s
    replicas:
      - name: nama_replika
        type: s3
        bucket: nama_bucket
        path: gotosocial
        region: us-east-1
        skip-verify: true
        endpoint: https://s3.provider.id
        force-path-style: true
        access-key-id: <access-key>
        secret-access-key: <secret-access-key>
        sync-interval: 60s
        retention: 12h

Pengaturan tambahan yang menurut ane penting adalah sync-interval dan retention.

sync-interval berguna untuk berapa sering Litestream memeriksa database untuk mencari perubahan dan membackup file WAL-nya ke storage, sedangkan retention mengontrol Litestream untuk secara aktif menghapus file WAL yang lama sebagai contoh 12h akan membuat Litestream menghapus file WAL yang usinyanya lebih dari 12 jam.

Agar bisa berjalan setiap boot dan atau mempermudah dalam pemakaian maka ane buat rc script sederhana, sebagai berikut

#!/bin/sh

. etc/rc.subr

name=litestream
rcvar=litestream_enable
load_rc_config "${name}"
procname="/usr/local/bin/litestream"

command=/usr/sbin/daemon
command_args="-S -T ${name} ${procname} replicate > /dev/null 2>1&"

run_rc_command "$1"

Replicate #

Kemudian daftarkan ke layanan service daemon di /etc.rc.conf dan setelah itu bisa dijalankan dengan command service

$ doas sysrc litestream_enable=YES
litestream_enable = NO → YES
$ doas service litestream start
$ tail -f /var/log/messages | grep litestream

Litestream membutuhkan waktu untuk menyusun snapshot dan persiapan backup setelah selesai dan berjalan normal, akan muncul file backup di bucket S3. Hasil file backupnya biasanya ada di folder generations yang berisi folder snapshot dan WAL, snapshot berisi salinan dari database sedangkan WAL berisi file kecil yang merupakan catatan transaksi.

Untuk periode tertentu, Litestream akan mengkonversi WAL dan snapshot menjadi 1 file snapshot baru, default-nya setiap 24 jam.

Restore #

Proses restore adalah mengembalikan database yang sudah dibackup sebelumnya dengan Litestream. Ada beberapa pilihan yang bisa dilakukan yaitu langsung restore database dari backup terakhir atau restore dari jam tertentu.

Namun sebelum melakukan itu ada baiknya untuk memeriksa timestamp dan daftar files yang tersedia.

$ litestream generations -config /etc/litestream.yml /var/www/database/egois.db
name  generation       start                 end
idc   b37bjda78c437    2026-06-25T10:16:02Z  2026-06-25T10:30:55Z

Dari hasil perintah di atas, diketahui

• ada 1 buah generasi yang file snapshotnya dibuat pertama kali pada tanggal 25 Juni 2026 jam 10:16 WIB
• Jam 10:16 WIB adalah batas paling lama dan tidak bisa melakukan restore sebelum jam dan tanggal ini karena ini adalah checkpoint awal backup dibuat,
• Jam 10:30 WIB adalah posisi backup paling akhir (terkini) yang tersedia, mungkin setelah jam ini ada checkpoint baru namun saat perintah di atas dilaksanakan, 10:30 WIB adalah checkpoint terkini yang tersedia.

Restore langsung ke backup terakhir #

Jika ingin langsung saja restore ke waktu paling akhir (yaitu jam 10:30 WIB) maka matikan dulu semua akses ke database existing di lokal dan gunakan perintah seperti ini

$ litestream restore -config /etc/litestream.yml \
-o /home/poes/egois-restore.db /var/www/database/egois.db

Litestream akan melakukan restore dan menyimpan hasilnya di /home/poes/egois-restore.db. Setelah selesai, sebaiknya lakukan pemeriksaan integritas data dengan perintah sqlite3 "PRAGMA integrity_check;". Hasil yang diharapkan adalah OK namun jika ada error’s maka ada masalah saat restore atau backup.

Restore ke backup di jam tertentu #

Seperti hasil dari pemeriksaan generasi data backup di atas, maka restore database ke jam tertentu hanya bisa dilakukan di rentang antara 10:16 WIB - 10:30 WIB⁴. Pemilihan waktu sampai detail ke menit ditentukan oleh apakah di jam tersebut ada proses backup yang berhasil dijalankan.

Jika tidak ada biasanya proses restore tidak akan berjalan, jadi pemilihan waktu ini sangat krusial yang dipengaruhi oleh pengaturan sync-interval di file /etc/litestream.yml, semakin kecil nilainya semakin besar peluang data tersedia setiap menit.

Sebagai contoh ane akan restore database di pukul 10:20 WIB, maka perintah yang ane terapkan adalah

$ litestream restore \
  -config /etc/litestream.yml \
  -replica nama_replika \
  -timestamp "2026-06-25T10:20:00Z" \
  -o /home/poes/egois-restore.db \
  /var/www/database/egois.db

Jika ada check point di jam tersebut maka database akan di-restore ke /home/poes/egois-restore.db. Jangan lupa lakukan pemeriksaan integritas data.

Kesimpulan #

Litestream adalah tool yang sangat bagus untuk membantu proses backup & restore untuk database yang tidak memiliki tool backup internal seperti SQLite. Ane lebih memilih memakai versi 0.3.13 yang menurut ane lebih stabil (di #FreeBSD) dibandingkan versi terbaru 0.5 yang masih ada beberapa bug’s mengganggu.

Aplikasi ini mengsyaratkan S3 sebagai tempat penyimpanan. Meski memiliki layanan self host S3 sendiri, namun ane tetap berlangganan layanan S3 dari provider eksternal seperti ID Cloudhost untuk urusan penyimpanan backup berjaga - jaga jika layanan self host S3 ane bermsalah apalagi lokasinya 1 server yang sama dengan instance #Gotosocial. Mengikuti kata pepatah “Jangan menaruh semua telur di keranjang yang sama”.

Sedangkan jika tidak memiliki layanan S3, maka mempergunakan alat lain seperti Restic dan Rclone bisa dipertimbangkan.