Koneksi ke Database Server

Setiap perintah yang kita jalankan lewat psql, pgAdmin, atau driver aplikasi bermuara pada satu hal yang sama: membuka koneksi ke server PostgreSQL. Koneksi itu dibangun dari lima parameter — host, port, user, database, dan kata sandi — dan sebagian besar kebingungan pemula (“psql: connection refused”, “role does not exist”) sebenarnya adalah kekeliruan parameter koneksi yang tersamar. Pada chapter ini kita bedah kelima parameter itu, urutan bagaimana nilainya ditentukan, dan cara membaca pesan error ketika koneksi gagal.

Lima Parameter Koneksi #

Nilai bawaan kolom terakhir menjelaskan keajaiban kecil yang sering kita alami: cukup mengetik psql, koneksi langsung terbentuk. Itu karena tanpa parameter apa pun, psql masuk lewat unix socket di mesin yang sama, memakai nama user sistem operasi kita sebagai role, dan memilih database yang namanya sama. Di komputer tempat user sistem operasi bernama budi, perintah psql polos akan mencoba masuk sebagai role budi ke database budi — dan gagal dengan pesan database “budi” does not exist bila database itu belum dibuat.

Urutan Sumber Nilai Parameter #

Satu parameter bisa diisi dari banyak sumber, dan psql menentukan nilainya dengan urutan prioritas berikut:

1. Parameter eksplisit pada flag CLI atau connection string — misalnya psql -p 5433 atau psql "host=localhost port=5433".
2. Entri pada connection service file — bila koneksi dibuat lewat nama service; kita bahas penuh di chapter Konfigurasi Koneksi.
3. Environment variable — PGHOST, PGPORT, PGUSER, PGDATABASE, dan kawan-kawannya.
4. Nilai bawaan libpq — socket lokal, port 5432, user sistem operasi, database senama.

Urutan ini penting dihafal kasarnya karena menjelaskan gejala yang sering membingungkan: mengapa psql -p 5432 tetap masuk ke server yang benar walau PGPORT di environment berisi angka lain (flag menang), atau mengapa mengubah PGHOST saja tidak cukup ketika connection string menyebut host secara eksplisit. Sumber yang lebih tinggi selalu menimpa yang lebih rendah untuk parameter yang sama; parameter yang tidak diisi jatuh ke sumber berikutnya.

Koneksi Lokal: Unix Socket #

Ketika host tidak disebut, client PostgreSQL di Linux dan macOS terhubung lewat unix socket — sebuah file khusus di direktori sistem yang berfungsi sebagai pintu masuk server di mesin yang sama. Koneksi ini lebih ringan daripada TCP karena tidak melewati tumpukan jaringan, dan lokasi socket-nya bisa dilihat pada output \conninfo di chapter Menggunakan psql.

Direktori socket bawaannya berbeda-beda per platform: /var/run/postgresql di Linux, /tmp di macOS dengan Homebrew. Server yang dikonfigurasi dengan listen_addresses kosong hanya melayani koneksi socket seperti ini — sama seperti server yang dipakai menguji materi course ini. Untuk kerja lokal sehari-hari, socket adalah jalur paling praktis: tanpa kata sandi bila pg_hba.conf mengizinkan, tanpa firewall, tanpa nama host.

Koneksi TCP: Menyebut Host secara Eksplisit #

Ketika server berada di mesin lain — server produksi, komputer rekan, container, atau virtual machine — kita menyebut hostnya secara eksplisit dan koneksi berpindah ke TCP:

psql -h localhost -p 5432 -U postgres -d latihan

Host localhost berarti “mesin ini sendiri”, tetapi lewat jalur TCP sehingga tetap tersentuh pengaturan jaringan. Server jaringan hanya mau menerima koneksi TCP bila listen_addresses pada konfigurasinya mengizinkan alamat tersebut — di chapter Konfigurasi PostgreSQL Server kita sudah melihat parameter ini ber-context postmaster, sehingga mengubahnya menuntut restart server.

Port pada contoh di atas adalah port bawaan 5432. Port yang berbeda dipakai ketika beberapa server PostgreSQL berjalan berdampingan di satu mesin — skenario yang umum di komputer pengembangan.

Menanyakan Identitas Koneksi #

Setelah tersambung, kita bisa meminta server memperkenalkan dirinya. Tiga function berikut menjawab tiga pertanyaan dasar: sebagai siapa kita masuk, ke database apa, dan lewat port yang mana:

SELECT current_user        AS pengguna,
       current_database()  AS database,
       current_setting('port') AS port;

Output yang Dihasilkan:

 pengguna |      database      | port  
----------+--------------------+-------
 postgres | pgtutor_1661a8b30c | 54329
(1 row)

Query seperti ini layak ditempatkan di awal skrip yang dijalankan di banyak lingkungan — satu baris kecil yang mencegah kita menjalankan migrasi ke database yang salah. Dua nilai pada output di atas mengikuti lingkungan pengujian materi ini: port 54329, dan database sementara khusus chapter (bernama pgtutor_...) tempat contoh course ini dijalankan; di instalasi Anda umumnya tampil port 5432 dan nama database Anda sendiri.

Koneksi dari Skrip Shell #

Ketika psql dipanggil dari skrip, environment variable menjadi cara alami menyuplai parameter. Skrip berikut memeriksa ketersediaan server dengan pg_isready, lalu menunjukkan bagaimana nilai PGDATABASE mengganti database tujuan tanpa mengubah perintah psqlnya:

# pg_isready memeriksa apakah server menerima koneksi
pg_isready

# psql memakai parameter koneksi dari environment
psql -X -c "SELECT current_user, current_database();"

# PGDATABASE menimpa database tujuan untuk perintah ini saja
PGDATABASE=postgres psql -X -c "SELECT current_database();"

Output yang Dihasilkan:

/home/z/my-project/pgrun:54329 - accepting connections
 current_user |  current_database  
--------------+--------------------
 postgres     | pgtutor_1661a8b30c
(1 row)

 current_database 
------------------
 postgres
(1 row)

Mari kita bedah tiga perintah di skrip tersebut:

1. pg_isready: menghubungi server dan hanya melaporkan statusnya — baris pertama output menunjukkan alamat socket dan port yang diperiksa. Alamat tersebut mengikuti PGHOST dan PGPORT di lingkungan skrip dijalankan.
2. psql -X -c "SELECT ...": membuka koneksi penuh, lalu menjalankan satu query. Nama database yang tampil adalah database yang dipilih environment — di lingkungan pengujian materi ini berupa database sementara khusus chapter, sedangkan di komputer Anda akan tampil database yang sedang Anda pakai.
3. PGDATABASE=postgres psql ...: prefix VARIABEL=nilai pada bash menetapkan environment variable untuk satu perintah itu saja, sehingga query yang sama dijalankan ke database postgres tanpa flag -d.

Ketika Koneksi Gagal #

Koneksi yang gagal memberi pesan yang cukup jujur kalau kita tahu cara membacanya. Skrip berikut sengaja menyebut port yang tidak dipakai server mana pun:

# Port 59999 tidak dipakai server mana pun
psql -X -p 59999 -c "SELECT 1;"

Output yang Dihasilkan:

psql: error: connection to server on socket "/home/z/my-project/pgrun/.s.PGSQL.59999" failed: No such file or directory
	Is the server running locally and accepting connections on that socket?

Pesan errornya berisi dua bagian: baris pertama menyebut alamat yang dicoba — jalur socket ditambah nomor port — dan alasannya (No such file or directory, artinya tidak ada server yang mendengarkan di sana); baris kedua adalah saran diagnosis. Nilai exit code juga informatif: psql keluar dengan kode 2 untuk kegagalan koneksi, 3 untuk error perintah SQL (yang kita lihat di chapter Menggunakan psql), dan 0 untuk sukses — pembedaan yang berguna ketika skrip shell perlu bereaksi berbeda pada tiap kegagalan.

Bila koneksi gagal, periksa daftar singkat ini secara berurutan:

1. Apakah server berjalan? (pg_isready, atau systemctl status postgresql.)
2. Apakah host dan port sudah benar — bawaannya localhost dan 5432?
3. Apakah pg_hba.conf mengizinkan kombinasi user, database, dan alamat kita?

Autentikasi di pg_hba.conf #

Pemeriksaan ketiga pada daftar di atas merujuk ke file pg_hba.conf yang sudah kita temui di chapter konfigurasi. File ini menyimpan daftar aturan: dari alamat mana, user mana, ke database mana boleh masuk, dan dengan metode apa identitasnya diverifikasi. Tiga metode yang paling sering dijumpai:

Server latihan untuk materi ini memakai trust supaya contoh-contoh course dapat berjalan tanpa kata sandi — kenyamanan yang hanya pantas untuk komputer pribadi yang terisolasi. Instalasi bawaan Linux umumnya memakai peer untuk socket lokal, sedangkan server produksi seharusnya memakai scram-sha-256. Pembahasan lengkap pengaturannya ada di Section User Management dan Keamanan.

Lima parameter koneksi itu akan kita pakai terus-menerus, dan mengetiknya berulang kali menjadi cepat membosankan. PostgreSQL menyediakan tiga alat penyimpanan yang menjawab kebosanan itu — environment variable, connection string, dan file service — dan itulah topik chapter berikutnya: Konfigurasi Koneksi.

Referensi #

• Client Connection Strings
• psql Reference
• Client Authentication

SELECT current_user        AS pengguna,
       current_database()  AS database,
       current_setting('port') AS port;

# pg_isready memeriksa apakah server menerima koneksi
pg_isready

# psql memakai parameter koneksi dari environment
psql -X -c "SELECT current_user, current_database();"

# PGDATABASE menimpa database tujuan untuk perintah ini saja
PGDATABASE=postgres psql -X -c "SELECT current_database();"

# Port 59999 tidak dipakai server mana pun
psql -X -p 59999 -c "SELECT 1;"