File Konfigurasi PostgreSQL

Chapter sebelumnya membahas parameter satu per satu; sekarang kita bedah wadahnya. Perilaku sebuah cluster PostgreSQL dikendalikan oleh tiga file teks — postgresql.conf, pg_hba.conf, dan pg_ident.conf — ditambah satu file hasil tulisan ALTER SYSTEM bernama postgresql.auto.conf. Kesalahan paling umum di dunia nyata justru bukan soal nilai parameter, melainkan soal file: parameter diedit di file yang salah, entri ditimpa oleh file lain tanpa disadari, atau aturan autentikasi di pg_hba.conf mengunci administrator keluar dari servernya sendiri. Chapter ini memetakan tugas setiap file, menunjukkan cara menemukan dan memeriksa isinya dari dalam SQL, serta membahas urutan prioritas antar file.

Tiga File dengan Tugas Berbeda #

Ketiga file pertama berada di data directory secara bawaan, tetapi paket instalasi kerap memisahkannya (Ubuntu menyimpannya di /etc/postgresql/17/main/). Karena lokasi itu berbeda-beda antar instalasi, cara paling andal menemukannya adalah bertanya kepada server yang sedang berjalan.

Menemukan Lokasi File #

Parameter config_file, hba_file, dan ident_file mencatat path ketiga file utama, sedangkan data_directory mencatat lokasi data. Keempatnya dibaca dengan SHOW:

-- Tanya langsung kepada server yang sedang berjalan
SHOW config_file;
SHOW hba_file;
SHOW ident_file;
SHOW data_directory;

Output yang Dihasilkan:

                config_file                
-------------------------------------------
 /home/z/my-project/pgdata/postgresql.conf
(1 row)

               hba_file                
---------------------------------------
 /home/z/my-project/pgdata/pg_hba.conf
(1 row)

               ident_file                
-----------------------------------------
 /home/z/my-project/pgdata/pg_ident.conf
(1 row)

      data_directory       
---------------------------
 /home/z/my-project/pgdata
(1 row)

Path yang tampil di atas adalah lokasi di lingkungan tempat materi ini diuji (/home/z/my-project/pgdata). Di server Anda, path tersebut mengikuti cara instalasi — /var/lib/postgresql/17/main/ untuk data directory di Ubuntu, atau folder data hasil initdb manual. Nilai data_directory juga bisa saja berbeda dari lokasi file konfigurasi, karena postgresql.conf boleh diletakkan di luar data directory lewat flag pg_ctl -D ... -o "-c config_file=...".

Membaca Aturan pg_hba.conf dari SQL #

File pg_hba.conf menentukan siapa yang boleh terhubung dan dengan metode autentikasi apa — pembahasan mendalam tentang sintaksnya ada di chapter pg_hba.conf . Yang sering terlupakan: isi file itu bisa diperiksa tanpa membuka shell, lewat view pg_hba_file_rules:

-- pg_hba.conf diparse ulang dan bisa dibaca lewat SQL
SELECT line_number, type, database, user_name, auth_method, error
FROM pg_hba_file_rules
ORDER BY line_number;

Output yang Dihasilkan:

 line_number | type  |   database    | user_name | auth_method | error 
-------------+-------+---------------+-----------+-------------+-------
         117 | local | {all}         | {all}     | trust       | 
         119 | host  | {all}         | {all}     | trust       | 
         121 | host  | {all}         | {all}     | trust       | 
         124 | local | {replication} | {all}     | trust       | 
         125 | host  | {replication} | {all}     | trust       | 
         126 | host  | {replication} | {all}     | trust       | 
(6 rows)

Enam baris di atas adalah isi asli pg_hba.conf lingkungan uji materi ini. Mari kita bedah kolomnya:

1. line_number: nomor baris di file asal — membuat baris ini bisa dilacak kembali ke editor.
2. type: jenis koneksi yang diatur — local berarti Unix domain socket, host berarti TCP/IP.
3. database dan user_name: tampil sebagai array (misalnya {all}, {replication}) karena satu aturan bisa memuat beberapa nama.
4. auth_method: metode autentikasi — di lingkungan uji ini semuanya trust, artinya koneksi lokal diterima tanpa password. Server produksi seharusnya memakai scram-sha-256.
5. error: kosong di semua baris. Kolom ini terisi pesan galat bila ada baris yang tidak bisa diparse — sesaat setelah mengedit pg_hba.conf, query ini jauh lebih aman daripada menebak dari pesan error saat reload.

pg_ident.conf: Pemetaan Nama Singkat #

File pg_ident.conf berisi baris-baris pemetaan nama_map user_os role_database. File ini hanya terpakai ketika pg_hba.conf memakai metode ident atau peer: server menanyakan nama user sistem operasi pemilik koneksi, lalu memetakan nama itu ke role PostgreSQL lewat map yang ditulis di file ini. Contoh barisnya:

# MAPNAME  SYSTEM-USERNAME  PG-USERNAME
staf       budi             budi_db
staf       siti             siti_db

Tanpa pemetaan, metode peer hanya menerima koneksi ketika nama user OS sama persis dengan nama role. Pemetaan membuat penamaan role bisa berbeda dari penamaan akun OS tanpa membuka akses untuk role lain.

include dan Konvensi conf.d #

postgresql.conf boleh memuat file lain lewat tiga directive: include 'file' (gagal bila file tidak ada), include_if_exists 'file' (diam bila tidak ada), dan include_dir 'direktori' (memuat semua file berakhiran .conf di direktori itu, dibaca sesuai urutan nama). Pola yang lazim dipakai adalah memecah konfigurasi ke folder conf.d:

# postgresql.conf
include_dir = 'conf.d'

# conf.d/10-memori.conf
shared_buffers = 256MB

# conf.d/20-logging.conf
log_min_duration_statement = 500ms

Konvensi penomoran (10-, 20-, dst.) menjaga urutan pembacaan: bila parameter yang sama muncul di beberapa file, entri yang dibaca paling akhir menang. Paket Debian/Ubuntu memakai pola ini — postgresql.conf utamanya hanya berisi include_dir = 'conf.d' dan satu baris include untuk postgresql.auto.conf. Path direktori dan file yang disertakan itu sendiri relatif terhadap lokasi postgresql.conf, bukan data directory.

postgresql.auto.conf dan Urutan Prioritas #

Setiap ALTER SYSTEM SET menulis entri ke postgresql.auto.conf, dan entri di file ini menang atas entri dengan nama yang sama di postgresql.conf. Server kita sedang membawa contoh nyatanya: parameter timezone ditulis di kedua file. File berikut menunjukkan buktinya, lalu mendemonstrasikan mekanismenya secara aktif pada work_mem:

-- Bukti 1: parameter timezone ditulis di dua file, auto.conf yang menang
SELECT sourcefile, setting, applied
FROM pg_file_settings
WHERE name = 'timezone'
ORDER BY sourcefile;

-- Tulis nilai work_mem lewat ALTER SYSTEM
ALTER SYSTEM SET work_mem = '8MB';
SELECT pg_reload_conf() AS muat_ulang, pg_sleep(0.1) AS jeda;

-- Bukti 2: sumber nilai kini postgresql.auto.conf
SELECT name, setting, source, sourcefile
FROM pg_settings
WHERE name = 'work_mem';

-- Hapus entri dari auto.conf agar contoh bisa diulang
ALTER SYSTEM RESET work_mem;
SELECT pg_reload_conf() AS muat_ulang, pg_sleep(0.1) AS jeda;

-- Tanpa entri di kedua file, nilai kembali ke bawaan
SELECT name, setting, source
FROM pg_settings
WHERE name = 'work_mem';

Output yang Dihasilkan:

                   sourcefile                   |   setting    | applied 
------------------------------------------------+--------------+---------
 /home/z/my-project/pgdata/postgresql.auto.conf | Asia/Jakarta | t
 /home/z/my-project/pgdata/postgresql.conf      | Etc/UTC      | f
(2 rows)

ALTER SYSTEM
 muat_ulang | jeda 
------------+------
 t          | 
(1 row)

   name   | setting |       source       |                   sourcefile                   
----------+---------+--------------------+------------------------------------------------
 work_mem | 8192    | configuration file | /home/z/my-project/pgdata/postgresql.auto.conf
(1 row)

ALTER SYSTEM
 muat_ulang | jeda 
------------+------
 t          | 
(1 row)

   name   | setting | source  
----------+---------+---------
 work_mem | 4096    | default
(1 row)

Dua bukti di file itu saling menguatkan:

1. Bukti 1: timezone bernilai Etc/UTC di postgresql.conf dengan applied = f (tidak diterapkan), dan Asia/Jakarta di postgresql.auto.conf dengan applied = t. Nilai SHOW timezone yang kita lihat selama ini (Asia/Jakarta) berasal dari auto.conf, bukan dari file utama.
2. Bukti 2: setelah ALTER SYSTEM SET work_mem = '8MB' dan pg_reload_conf(), kolom sourcefile pada pg_settings menunjuk ke postgresql.auto.conf. Setelah RESET, entri hilang dari auto.conf dan source kembali default karena postgresql.conf tidak pernah mengatur work_mem.

Urutan lengkap prioritas nilai sebuah parameter, dari yang paling kuat:

Restart atau Reload? #

Setelah mengubah file, server perlu membaca ulang isinya. Ada dua cara, dan pilihannya ditentukan kolom context yang kita bahas di chapter Konfigurasi Server:

pg_ctl -D /home/z/my-project/pgdata reload    # baca ulang tanpa memutus koneksi
pg_ctl -D /home/z/my-project/pgdata restart   # matikan lalu nyalakan ulang

Perintah reload mengirim sinyal SIGHUP; parameter ber-context sighup, user, dan superuser langsung berlaku pada session yang ada, tanpa satu pun klien terputus. Perintah restart diperlukan untuk parameter ber-context postmaster seperti shared_buffers dan max_connections — memorinya baru dialokasikan saat server menyala. Kedua perintah itu juga berlaku untuk pg_hba.conf dan pg_ident.conf: keduanya dibaca ulang saat reload, sehingga aturan autentikasi baru bisa aktif tanpa restart.

Tiga file itu kini peta yang jelas di tangan kita. File berikutnya yang perlu dipahami administrator bukan lagi file di disk, melainkan sambungan itu sendiri: berapa banyak koneksi yang ditampung server, bagaimana keadaannya, dan bagaimana menghentikannya — pokok bahasan chapter Connection Management.

Referensi #

• Setting Parameters
• Server Configuration
• Client Authentication
• pg_ctl Reference

-- pg_hba.conf diparse ulang dan bisa dibaca lewat SQL
SELECT line_number, type, database, user_name, auth_method, error
FROM pg_hba_file_rules
ORDER BY line_number;

-- Tanya langsung kepada server yang sedang berjalan
SHOW config_file;
SHOW hba_file;
SHOW ident_file;
SHOW data_directory;

-- Bukti 1: parameter timezone ditulis di dua file, auto.conf yang menang
SELECT sourcefile, setting, applied
FROM pg_file_settings
WHERE name = 'timezone'
ORDER BY sourcefile;

-- Tulis nilai work_mem lewat ALTER SYSTEM
ALTER SYSTEM SET work_mem = '8MB';
SELECT pg_reload_conf() AS muat_ulang, pg_sleep(0.1) AS jeda;

-- Bukti 2: sumber nilai kini postgresql.auto.conf
SELECT name, setting, source, sourcefile
FROM pg_settings
WHERE name = 'work_mem';

-- Hapus entri dari auto.conf agar contoh bisa diulang
ALTER SYSTEM RESET work_mem;
SELECT pg_reload_conf() AS muat_ulang, pg_sleep(0.1) AS jeda;

-- Tanpa entri di kedua file, nilai kembali ke bawaan
SELECT name, setting, source
FROM pg_settings
WHERE name = 'work_mem';