Saat melakukan migrasi data berskala besar atau operasi intensif pada Carbonio Files, administrator mungkin akan menemukan pesan error seperti berikut:

HikariPool - Failed to validate connection ... possibly consider using a shorter maxLifetime value

Pesan ini menandakan bahwa salah satu koneksi database di dalam HikariCP connection pool telah ditutup lebih awal oleh PostgreSQL atau jaringan, sebelum masa pakainya berakhir menurut aplikasi. Kondisi ini umumnya disebabkan oleh idle connection timeout yang diterapkan di level database, sistem operasi, atau perangkat jaringan (firewall/NAT).

Dokumen ini menjelaskan langkah-langkah untuk mendiagnosis dan menyesuaikan pengaturan Hikari Connection Pool pada Carbonio Files menggunakan Consul Key-Value (KV) Store, yang berfungsi sebagai pusat konfigurasi layanan Carbonio.

1. Diagnostik Awal

1.1 Memeriksa Log Carbonio Files

Langkah pertama adalah memastikan bahwa error yang terjadi memang berkaitan dengan koneksi database. Periksa log Carbonio Files dengan perintah berikut:

journalctl -xau carbonio-files.service

Cari pesan yang berhubungan dengan:

• database timeout
• connection validation failure
• HikariPool warning

1.2 Memeriksa Idle Timeout di PostgreSQL

Pengaturan timeout di PostgreSQL sering menjadi penyebab utama koneksi ditutup secara otomatis.

Periksa nilai tcp_keepalives_idle pada PostgreSQL:

cat /etc/postgresql/16/main/postgresql.conf | grep tcp_keepalives_idle

Jika nilainya 0, maka PostgreSQL akan menggunakan nilai default dari sistem operasi.

1.3 Memeriksa Timeout Keepalive di Level OS

Untuk melihat pengaturan keepalive di sistem operasi Linux:

cat /proc/sys/net/ipv4/tcp_keepalive_time

Nilai default umumnya 7200 detik (2 jam).
Dalam beberapa lingkungan jaringan (terutama yang menggunakan firewall atau NAT), koneksi idle bisa diputus jauh lebih cepat dari nilai ini, sehingga menimbulkan konflik dengan HikariCP.

2. Verifikasi dan Modifikasi Consul Key-Value Store

Pengaturan Hikari Connection Pool untuk Carbonio Files disimpan dan dikelola melalui Consul KV Store. Untuk mengaksesnya, diperlukan token Consul yang valid.

2.1 Mengambil Consul Bootstrap Password

Pada server Mesh (Node 1), jalankan perintah berikut untuk mendapatkan password bootstrap:

cat /var/lib/service-discover/password

Password ini digunakan untuk menghasilkan token Consul.

2.2 Membuat Token Consul

Gunakan password yang diperoleh untuk membuat token akses Consul:

service-discover bootstrap-token

Simpan token yang dihasilkan, karena akan digunakan pada langkah-langkah selanjutnya.

2.3 Memeriksa Pengaturan Hikari di Consul

Beberapa parameter Hikari yang umum digunakan antara lain:

• hikari-max-pool-size
  Jumlah maksimum koneksi database dalam pool
• hikari-min-idle-connections
  Jumlah minimum koneksi idle yang dipertahankan

Untuk melihat nilai saat ini, jalankan:

consul kv get -token=YOURTOKEN carbonio-files/hikari-max-pool-size
consul kv get -token=YOURTOKEN carbonio-files/hikari-min-idle-connections

Ganti YOURTOKEN dengan token Consul yang telah dibuat.
Catatan: Path key dapat berbeda tergantung pada konfigurasi environment.

2.4 Mengubah Pengaturan Hikari Connection Pool

Sebagai contoh, untuk:

• mengatur hikari-max-pool-size menjadi 10
• mengatur hikari-min-idle-connections menjadi 2

jalankan perintah berikut:

consul kv put -token=YOURTOKEN carbonio-files/hikari-max-pool-size 10
consul kv put -token=YOURTOKEN carbonio-files/hikari-min-idle-connections 2

Sesuaikan nilai dan key sesuai dengan kebutuhan dan hasil analisis sistem.

2.5 Restart Layanan Carbonio Files

Agar perubahan diterapkan, restart service Carbonio Files:

systemctl restart carbonio-files.service

3. Rekomendasi dan Best Practice

• Sesuaikan maxLifetime Hikari
  Jika error validasi koneksi sering muncul, pertimbangkan untuk menetapkan nilai maxLifetime yang lebih pendek dari idle timeout database atau jaringan.
• Uji di Environment Staging
  Selalu lakukan pengujian perubahan connection pool di environment staging sebelum diterapkan ke production.
• Kumpulkan Log untuk Troubleshooting
  Jika masalah tetap terjadi, kumpulkan:
  • log Carbonio Files
  • konfigurasi Hikari terbaru
  • informasi timeout database & OS