Klien basis data

Driver basis data adalah paket Node yang membuka koneksi TCP ke server basis data, mengirim perintah sesuai protokol server, dan mengembalikan hasil sebagai objek JavaScript. Dua driver yang dibahas pada topik ini adalah pg untuk PostgreSQL dan mongodb untuk MongoDB. Keduanya mendukung pola connection pool yang meminjamkan koneksi yang sudah terbuka kepada kueri, sehingga biaya handshake TCP tidak dibayar pada setiap pemanggilan. Setelah membaca topik ini, pembaca dapat menulis kode yang membuka pool, menjalankan kueri, menangani error koneksi, dan memutus pool dengan benar pada penutupan aplikasi.

Driver PostgreSQL#

Paket pg adalah driver resmi PostgreSQL untuk Node. Kelas Pool membuat sekelompok koneksi yang dapat dipinjam oleh kueri, sedangkan kelas Client membuka satu koneksi mandiri yang cocok untuk skrip pendek. Konfigurasi pool mencakup connectionString untuk URL basis data, max untuk jumlah koneksi maksimum, dan connectionTimeoutMillis untuk batas waktu penungguan koneksi. Pemanggilan pool.query(sql) meminjam satu koneksi dari pool, menjalankan kueri, dan mengembalikan koneksi tersebut ke pool setelah selesai.

Berkas pg-pool.js berikut membuka pool dengan target server PostgreSQL pada porta 5432 lokal, lalu menjalankan kueri SELECT 1. Karena tidak ada server PostgreSQL yang berjalan pada sandbox, koneksi ditolak dan error ditangkap pada blok .catch. Penanganan ini menunjukkan perilaku nyata driver ketika server tidak tersedia, sekaligus membuktikan bahwa kode struktur pool dapat dieksekusi tanpa server hidup.

// tidak-dijalankan: butuh pg yang dipasang di /tmp/klien-basis-data
const { Pool } = require('pg');

const pool = new Pool({
  connectionString: 'postgres://localhost:5432/app_dev',
  connectionTimeoutMillis: 2000,
  max: 10
});

pool.query('SELECT 1')
  .then((res) => console.log('terhubung, baris:', res.rows))
  .catch((err) => {
    console.error('kode error:', err.code);
    console.error('tipe:', err.toString().split('\n')[0]);
  })
  .finally(() => pool.end());

# pasang pg sekali untuk demo topik ini: cd /tmp/klien-basis-data && npm install pg
# jalankan pg-pool.js dari direktori topik, NODE_PATH mengarah ke node_modules demo
NODE_PATH=/tmp/klien-basis-data/node_modules node pg-pool.js

kode error: ECONNREFUSED
tipe: AggregateError

Kode error ECONNREFUSED berasal dari lapisan sistem operasi yang menandakan tidak ada proses mendengarkan pada alamat dan porta tujuan. Driver pg membungkus error ini sebagai AggregateError karena pool dapat mencoba beberapa alamat sekaligus, misalnya IPv6 ::1 dan IPv4 127.0.0.1, lalu menggabungkan kegagalan masing-masing. Pemanggilan pool.end() pada blok .finally menutup pool agar proses Node dapat keluar, sebab pool yang terbuka mempertahankan socket yang menjaga event loop tetap hidup.

Connection pooling#

Connection pool mempertahankan sejumlah koneksi yang sudah terbuka ke server basis data, sehingga kueri berikutnya tidak perlu membayar biaya handshake TCP, autentikasi, dan negosiasi parameter. Ketiga biaya tersebut masing-masing memakan puluhan milidetik. Pool juga membatasi jumlah koneksi simultan ke server, sebab setiap koneksi memakan memori pada sisi server dan terlalu banyak koneksi dapat membuat server kelelahan. Diagram berikut menggambarkan posisi pool di antara aplikasi dan server basis data.

Konfigurasi pool yang lazim dipakai pada aplikasi produksi adalah max antara 10 hingga 20 koneksi per instance Node, disesuaikan dengan batas koneksi yang diberikan server basis data. Bila aplikasi dijalankan pada beberapa instance, jumlah total koneksi adalah max dikalikan jumlah instance, sehingga batas server harus cukup untuk akumulasi tersebut. Koneksi yang idle tetap memakan sumber daya pada server, sehingga idleTimeoutMillis dapat dipasang agar koneksi yang lama tidak dipakai ditutup otomatis.

Driver MongoDB#

Paket mongodb adalah driver resmi MongoDB untuk Node. Kelas MongoClient membuka koneksi ke replica set atau standalone server, dan sekali terhubung, koneksi dipakai bersama oleh seluruh operasi pada basis data serta koleksi. Konfigurasi serverSelectionTimeoutMS menentukan batas waktu penungguan sebelum driver menyatakan tidak ada server yang dapat dijangkau. Skrip mongo-client.js berikut mencoba membuka koneksi ke server lokal pada porta 27017, dan karena tidak ada server yang berjalan pada sandbox, error ditangkap dan dicetak.

// tidak-dijalankan: butuh mongodb yang dipasang di /tmp/klien-basis-data
const { MongoClient } = require('mongodb');

const client = new MongoClient('mongodb://localhost:27017', {
  serverSelectionTimeoutMS: 2000
});

async function main() {
  try {
    await client.connect();
    console.log('terhubung');
  } catch (err) {
    console.error('nama:', err.name);
    console.error('pesan:', err.message);
  } finally {
    await client.close();
  }
}

main();

# pasang mongodb sekali untuk demo topik ini: cd /tmp/klien-basis-data && npm install mongodb
# jalankan mongo-client.js dari direktori topik
NODE_PATH=/tmp/klien-basis-data/node_modules node mongo-client.js

nama: MongoServerSelectionError
pesan: connect ECONNREFUSED ::1:27017, connect ECONNREFUSED 127.0.0.1:27017

Driver MongoDB membungkus kegagalan koneksi sebagai MongoServerSelectionError, sebab driver menjalankan tahap server selection yang mencoba beberapa kandidat server sebelum menyerah. Pesan error menyebut dua upaya, yaitu ke alamat IPv6 ::1 dan IPv4 127.0.0.1, keduanya pada porta 27017. Pesan ini mengonfirmasi bahwa driver mencoba IPv6 lebih dahulu lalu jatuh ke IPv4, dan kedua upaya menemui ECONNREFUSED karena tidak ada server MongoDB yang berjalan.

Penanganan error koneksi#

Error koneksi dapat dibedakan berdasarkan kode dan pesannya. Kode ECONNREFUSED menandakan tidak ada server mendengarkan pada alamat tujuan, biasanya karena server tidak berjalan atau porta salah. Kode ETIMEDOUT menandakan paket terkirim tetapi tidak ada respons dalam batas waktu, biasanya karena firewall yang menjatuhkan paket atau server terlalu lambat. Kode ENOTFOUND menandakan nama host tidak dapat diuraikan ke alamat IP, biasanya karena DNS salah atau nama host salah ketik.

Pemisahan kode error memungkinkan strategi pemulihan yang berbeda. ECONNREFUSED biasanya berakhir dengan menghentikan proses dan memunculkan notifikasi, sebab server basis data yang tidak tersedia tidak dapat ditangani dengan retry singkat. ETIMEDOUT dapat ditangani dengan retry beriring backoff, sebab kemacetan jaringan sering sementara. ENOTFOUND mengindikasikan kesalahan konfigurasi yang harus diperbaiki pada variabel lingkungan, bukan dilakukan retry.

Kesalahan umum#

Membuka Client baru untuk setiap kueri. Pola ini membuang biaya handshake TCP pada setiap kueri dan dapat dengan cepat menghabiskan slot koneksi server. Client mandiri hanya tepat untuk skrip pendek satu kali, sedangkan aplikasi yang melayani permintaan harus memakai Pool yang dipertahankan sepanjang siklus hidup proses.

Lupa memanggil pool.end() atau client.close() pada penutupan aplikasi. Socket yang masih terbuka menjaga event loop tetap hidup, sehingga proses Node tampak menggantung padahal seluruh handler sudah selesai. Pasang penangan SIGTERM dan SIGINT yang menutup pool sebelum process.exit dipanggil, agar penutupan graceful dapat diandalkan pada lingkungan produksi.

Menangkap error tanpa memeriksa kodenya. Blok catch yang hanya mencatat err.message kehilangan informasi kode error yang sebenarnya menentukan tindakan pemulihan. Akses err.code pada driver pg dan err.name pada driver mongodb memberikan sinyal yang dapat dipakai untuk memilih antara retry, penghentian, atau pemetaan ke respons HTTP.

Ringkasan#

• Driver pg menyediakan kelas Pool untuk PostgreSQL dan Client untuk koneksi mandiri, dengan pool.query(sql) meminjam koneksi dari pool secara otomatis.
• Driver mongodb menyediakan MongoClient yang membuka koneksi terbagi ke replica set atau standalone, dengan serverSelectionTimeoutMS mengatur batas waktu penungguan server.
• Pool mempertahankan koneksi sudah terbuka agar kueri tidak membayar biaya handshake TCP pada setiap pemanggilan, dan max membatasi jumlah koneksi simultan ke server.
• Kode error ECONNREFUSED, ETIMEDOUT, dan ENOTFOUND dibedakan karena masing-masing menuntut strategi pemulihan yang berbeda, dan pool wajib ditutup pada penutupan aplikasi.

Referensi#

• node-postgres — Pool — node-postgres — Dokumentasi resmi kelas Pool pada driver pg, mencakup opsi max, connectionTimeoutMillis, dan idleTimeoutMillis.
• MongoDB Node Driver — MongoDB — Dokumentasi resmi driver MongoDB untuk Node beserta MongoClient dan opsi serverSelectionTimeoutMS.
• node-postgres — GitHub — Repositori sumber driver pg dengan contoh pemakaian Pool dan Client serta penjelasan penanganan error koneksi.