Cara Mengompilasi Modul PostgreSQL di ServBay

Saat mengembangkan dengan ServBay sebagai lingkungan pengembangan web lokal untuk PostgreSQL, Anda mungkin membutuhkan kompilasi dan pemasangan modul tambahan PostgreSQL (juga disebut ekstensi) guna meningkatkan atau memperluas fungsionalitas database. Modul-modul ini dapat menyediakan tipe data baru, fungsi, operator, metode akses indeks, dan masih banyak lagi.

Artikel ini akan memandu Anda secara detail dalam mengompilasi dan menginstal modul PostgreSQL di lingkungan ServBay, menggunakan postgis (dukungan sistem informasi geografis) dan pg_jieba (pemotongan kata bahasa Tionghoa) sebagai contoh.

Ringkasan

ServBay menawarkan lingkungan yang fleksibel dan kaya fitur, memungkinkan developer untuk melakukan pengembangan lanjutan atau mengompilasi komponen tambahan di atas paket perangkat lunak terintegrasinya. Proses kompilasi modul PostgreSQL biasanya meliputi pengunduhan kode sumber modul, konfigurasi opsi kompilasi, penggunaan alat seperti make atau cmake untuk membangun dan memasang, lalu mengaktifkan modul di PostgreSQL.

Kunci keberhasilan terletak pada konfigurasi lingkungan kompilasi yang benar, sehingga dapat menemukan file header, library, dan dependensi spesifik PostgreSQL versi tertentu dalam ServBay.

Prasyarat

Sebelum memulai kompilasi modul PostgreSQL apa pun, Anda wajib menginisialisasi lingkungan kompilasi sesuai persyaratan ServBay. Langkah ini sangat penting karena akan mengatur toolchain (compiler, linker, dsb), variabel lingkungan (seperti $PATH, $CFLAGS, $LDFLAGS, dll) serta jalur konfigurasi build khusus ServBay.

Untuk prosedur detail menginisialisasi lingkungan kompilasi, silakan baca bagian Kompilasi Ulang Paket dengan ServBay di dokumentasi resmi ServBay. Pastikan Anda telah menyelesaikan persiapan lingkungan yang dijelaskan di sana, biasanya melibatkan menjalankan skrip inisialisasi lingkungan melalui terminal ServBay.

Pentingnya Menentukan Versi PostgreSQL

ServBay mendukung instalasi dan pengoperasian beberapa versi PostgreSQL secara bersamaan. Karena kompilasi dan eksekusi modul PostgreSQL erat kaitannya dengan versi database (misal, tergantung file header, library dan API internal spesifik versi itu), Anda harus secara eksplisit menentukan versi PostgreSQL beserta jalur konfigurasi terkait ketika menggunakan alat kompilasi.

Pemilihan jalur konfigurasi versi PostgreSQL yang sesuai memastikan proses kompilasi dapat menemukan semua dependensi dan menghasilkan file modul yang kompatibel, sehingga mencegah kesalahan build, kegagalan saat pemuatan, maupun error tak terduga saat runtime.

Sebagai contoh, di sini digunakan PostgreSQL 15 yang terinstal pada ServBay (misal versi 15.7). Silakan sesuaikan jalur dengan versi PostgreSQL yang Anda gunakan.

ServBay menyediakan variabel lingkungan dan alat pg_config untuk membantu menemukan jalur yang tepat. ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/pg_config adalah utilitas yang sangat berguna, dibundel dalam PostgreSQL, yang melaporkan jalur instalasi, info konfigurasi build, jalur library, jalur header, dsb. Saat mengompilasi modul eksternal, pg_config sangat penting untuk menentukan dependensi.

Kompilasi Modul postgis

postgis adalah salah satu ekstensi PostgreSQL paling populer dan powerful, menambahkan dukungan sistem informasi geografis (GIS) ke PostgreSQL sehingga bisa menyimpan, melakukan query, dan menganalisis data spasial. Berikut langkah-langkah kompilasi modul postgis-3.4.2:

Langkah 1: Unduh Kode Sumber

Unduh paket kode sumber postgis-3.4.2 dari situs resmi PostGIS. Pastikan Anda mengambil versi kode sumber (umumnya .tar.gz atau .zip).

wget https://download.osgeo.org/postgis/source/postgis-3.4.2.tar.gz

wget adalah utilitas baris perintah untuk mengunduh file dari URL tertentu.

Langkah 2: Ekstrak Kode Sumber

Ekstrak file postgis-3.4.2.tar.gz ke direktori lokal dan masuk ke direktori hasil ekstraksi.

tar zxvf postgis-3.4.2.tar.gz
cd postgis-3.4.2

Perintah tar zxvf digunakan untuk ekstrak file .tar.gz. Perintah cd untuk masuk ke direktori kode sumber utama postgis-3.4.2.

Langkah 3: Konfigurasi Opsi Kompilasi

PostGIS menggunakan GNU Autotools sebagai sistem build. Tahap konfigurasi akan memeriksa dependensi sistem dan menghasilkan file Makefile. Pada tahap ini, kita harus menentukan jalur instalasi PostgreSQL versi ServBay yang sesuai serta jalur library lain yang diperlukan.

./configure \
  --prefix=${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7 \
  --bindir=${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin \
  --datarootdir=${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/share \
  --with-protobufdir=${SERVBAY_BIN_PATH} \
  --disable-nls \
  --without-raster \
  --without-topology \
  --with-pgconfig=${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/pg_config \
  CFLAGS="${CFLAGS} -I${SERVBAY_COMMON_INCLUDE_PATH}/libxml2 -I${SERVBAY_COMMON_INCLUDE_PATH}" \
  CXXFLAGS="${CXXFLAGS} -std=c++17 -I${SERVBAY_COMMON_INCLUDE_PATH}/libxml2 -I${SERVBAY_COMMON_INCLUDE_PATH}" \
  LDFLAGS="${LDFLAGS} -L${SERVBAY_COMMON_LIB_PATH} -lxml2 -lz -lpthread -liconv -licui18n -licuuc -licudata -lm"

• ./configure: Menjalankan skrip konfigurasi.
• --prefix, --bindir, --datarootdir: Menentukan agar instalasi PostGIS ditempatkan di struktur direktori versi PostgreSQL yang sesuai dalam ServBay. ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7 adalah root instalasi untuk PostgreSQL 15.7 di ServBay, umumnya sudah di-set lewat skrip inisialisasi lingkungan.
• --with-protobufdir: Menetapkan jalur library Protobuf yang mungkin dibutuhkan PostGIS. ${SERVBAY_BIN_PATH} adalah jalur file biner ServBay.
• --disable-nls: Menonaktifkan dukungan multi bahasa, biasanya tak diperlukan untuk pengembangan.
• --without-raster, --without-topology: Menonaktifkan dukungan Raster/Topology guna menyederhanakan kompilasi. Anda bisa mengaktifkannya sesuai kebutuhan, tapi ini bisa membutuhkan library tambahan.
• --with-pgconfig: Ini sangat penting, menunjuk ke jalur pg_config dari versi PostgreSQL yang akan digunakan dalam kompilasi. pg_config melaporkan flag, jalur library, dan parameter build PostgreSQL sehingga modul kompatibel dengan versi target.
• CFLAGS, CXXFLAGS, LDFLAGS: Variabel standar untuk meneruskan parameter ekstra ke kompilator/linker C/C++. ${CFLAGS}, ${CXXFLAGS}, ${LDFLAGS} mewarisi pengaturan default dari lingkungan ServBay.
  • -I${SERVBAY_COMMON_INCLUDE_PATH}/libxml2 -I${SERVBAY_COMMON_INCLUDE_PATH}: Menambahkan jalur header library umum ServBay agar kompilator bisa menemukan file header seperti libxml2.
  • -L${SERVBAY_COMMON_LIB_PATH} -lxml2 -lz ...: Menambahkan dan me-link library umum ServBay (libxml2, zlib, pthread, iconv, icu, dsb). ${SERVBAY_COMMON_LIB_PATH} menunjuk ke direktori library bersama ServBay. Library ini biasanya sudah tersedia di lingkungan ServBay.
  • -std=c++17: Memaksa penggunaan standar C++17, yang sering dibutuhkan project C++ modern.

Langkah 4: Kompilasi dan Instalasi

Setelah konfigurasi sukses, gunakan make untuk mulai build dan make install untuk menempatkan file hasil kompilasi ke direktori target yang sudah diatur di --prefix.

make -j ${CPU_NUMBER}
make install

• make -j ${CPU_NUMBER}: Memulai proses kompilasi. Opsi -j ${CPU_NUMBER} secara paralel menggunakan banyak core CPU untuk mempercepat proses.
• make install: Menyalin file hasil build (library share PostGIS, script SQL, dll) ke direktori instalasi PostgreSQL 15.7 dalam ServBay, biasanya di subdirektori lib/postgresql dan share/postgresql/extension.

Langkah 5: Verifikasi Pemuatan Modul

Setelah kompilasi & instalasi selesai, aktifkan ekstensi postgis di database PostgreSQL Anda. Hubungkan ke database lewat terminal ServBay atau klien PostgreSQL favorit Anda lalu eksekusi perintah SQL berikut.

Gunakan tools baris perintah psql dari lingkungan ServBay. Pastikan Anda sudah berada di terminal ServBay agar variabel lingkungan ter-set dengan benar.

# Jalankan CREATE EXTENSION untuk mengaktifkan PostGIS
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "CREATE EXTENSION postgis;"

Jika berhasil, PostGIS siap digunakan. Untuk memastikan, cek versi:

# Cek versi PostGIS
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "SELECT PostGIS_Version();"

Jika berhasil, Anda akan melihat output nomor versi PostGIS, artinya modul sudah ter-build, terinstal, dan sudah termuat di database.

Kompilasi Modul pg_jieba

pg_jieba adalah ekstensi PostgreSQL berbasis cppjieba (C++) yang menghadirkan kemampuan pemotongan kata Tionghoa di PostgreSQL, sangat berguna untuk pencarian fulltext. pg_jieba menggunakan CMake sebagai sistem build-nya. Berikut prosedur build untuk modul ini:

Langkah 1: Dapatkan Kode Sumber

Clone repo kode sumber pg_jieba dari GitHub. pg_jieba membutuhkan submodul git cppjieba, jadi perlu juga inisialisasi submodulnya.

git clone https://github.com/jaiminpan/pg_jieba.git
cd pg_jieba
git submodule update --init --recursive

• git clone ...: Mengkloning repo pg_jieba ke direktori saat ini.
• git submodule update --init --recursive: Inisialisasi dan update semua submodul git di repo. cppjieba sebagai submodul diwajibkan agar kode sumbernya ikut diunduh.

Langkah 2: Konfigurasi Opsi Build (CMake)

pg_jieba menggunakan CMake. Serupa dengan ./configure pada Autotools, CMake akan mengkonfigurasi dan membuat berkas build berdasarkan sistem target.

cmake -S . -B builddir \
  -DCMAKE_PREFIX_PATH=${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7 \
  -DCMAKE_OSX_DEPLOYMENT_TARGET=${BUILD_OS_MIN_VERSION} \
  -DCMAKE_OSX_ARCHITECTURES=${BUILD_CPU_ARCH_CMAKE}

• cmake -S . -B builddir: Jalankan konfigurasi CMake dengan sumber di direktori saat ini dan hasil build di subdirektori builddir. Praktik ini dianjurkan agar direktori sumber tetap bersih.
• -DCMAKE_PREFIX_PATH: Sangat penting! Memerintahkan CMake mencari library, header dan dependency lain (khususnya PostgreSQL) di jalur ini—ke root instalasi PostgreSQL 15.7 dalam ServBay. CMake akan menelusuri subdirektori lib/cmake, share/cmake, dll dan gunakan info dari pg_config bila ada.
• -DCMAKE_OSX_DEPLOYMENT_TARGET: Pastikan binary build bisa berjalan di versi macOS tertentu ke atas. ${BUILD_OS_MIN_VERSION} adalah target minimum dari environment ServBay.
• -DCMAKE_OSX_ARCHITECTURES: Menentukan arsitektur CPU (misal x86_64 atau arm64). ${BUILD_CPU_ARCH_CMAKE} didapat dari pengaturan ServBay. Dua opsi terakhir penting agar binary kompatibel di sistem macOS target.

Langkah 3: Kompilasi dan Instalasi (CMake)

Setelah konfigurasi, gunakan cmake --build untuk kompilasi dan cmake --install untuk instalasi.

cmake --build builddir -j ${CPU_NUMBER}
cmake --install builddir

• cmake --build builddir: Proses build dijalankan di direktori builddir.
• -j ${CPU_NUMBER}: Paralelisasi build untuk mengoptimalkan waktu memakai multi core.
• cmake --install builddir: Instal file hasil build ke lokasi yang sudah ditentukan oleh -DCMAKE_PREFIX_PATH (dan didukung info pg_config), yaitu ke direktori instalasi PostgreSQL ServBay yang benar.

Langkah 4: Verifikasi Pemuatan Modul

Setelah build & instalasi selesai, aktifkan ekstensi pg_jieba di database PostgreSQL Anda. Hubungkan ke database dan jalankan perintah SQL berikut.

Gunakan tools baris perintah psql dari ServBay dan pastikan Anda ada pada sesi terminal ServBay.

# Jalankan CREATE EXTENSION untuk mengaktifkan pg_jieba
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "CREATE EXTENSION pg_jieba;"

Jika berhasil, pg_jieba siap digunakan. Anda dapat cek keberadaannya melalui view pg_available_extensions:

# Lihat daftar ekstensi terinstal
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "SELECT * FROM pg_available_extensions WHERE name = 'pg_jieba';"

Jika hasil tercantum di sana, berarti proses build, instalasi, dan aktivasi sudah sukses.

Pertanyaan Umum (FAQ)

• Build gagal, tidak dapat menemukan file header atau library?
  • Pastikan lingkungan kompilasi ServBay sudah diinisialisasi dengan benar. Jalankan skrip inisialisasi di terminal ServBay sehingga semua variabel lingkungan ($CFLAGS, $LDFLAGS, ${SERVBAY_COMMON_INCLUDE_PATH}, ${SERVBAY_COMMON_LIB_PATH} dst) mengarah ke jalur yang tepat.
  • Cek apakah path ke --with-pgconfig (Autotools) atau -DCMAKE_PREFIX_PATH (CMake) sudah benar menunjuk ke versi dan lokasi pg_config yang tepat, serta file tersebut memang ada dan executable.
  • Beberapa modul mungkin butuh dependensi sistem di luar library umum ServBay (misal, PostGIS dengan dukungan Raster/Topology harus ada GEOS, GDAL, dsb). Jika dependensi tidak tersedia, Anda bisa instal manual atau nonaktifkan opsionalitas terkait saat konfigurasi build.
• CREATE EXTENSION gagal, tidak dapat menemukan file modul?
  • Pastikan proses make install (Autotools) atau cmake --install (CMake) berjalan sukses tanpa error. Cek log instalasi dan periksa apakah file sudah tersalin ke jalur yang benar.
  • Cek apakah path yang ditentukan lewat --prefix (Autotools) atau -DCMAKE_PREFIX_PATH (CMake) memang mengarah ke direktori versi PostgreSQL ServBay yang diinginkan. Modul akan terinstal di subdirektori lib/postgresql.
  • Coba restart layanan PostgreSQL. Kadang database perlu restart agar modul baru bisa dideteksi (bisa lewat UI ServBay).
  • Periksa konfigurasi shared_preload_libraries PostgreSQL. Sebagian besar ekstensi bisa langsung dimuat dengan CREATE EXTENSION, namun beberapa modul khusus (yang perlu hook ke internal PostgreSQL) membutuhkan entry di shared_preload_libraries. Silakan cek dokumentasi modul terkait.
• Bagaimana cara build modul untuk versi PostgreSQL lain?
  • Ulangi seluruh langkah build di atas, tetapi pastikan pada tahap konfigurasi (./configure atau cmake) parameter --with-pgconfig (Autotools) atau -DCMAKE_PREFIX_PATH (CMake) menunjuk ke direktori pg_config versi PostgreSQL target. Misal, untuk PostgreSQL 14 gunakan ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/14/14.x/bin/pg_config atau ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/14/14.x (ganti 14.x dengan angka versi sesuai instalasi ServBay Anda).

Kesimpulan

Dengan mengikuti panduan ini dan memanfaatkan sepenuhnya lingkungan kompilasi serta tools yang disediakan ServBay, Anda dapat berhasil mengompilasi dan menginstal modul PostgreSQL yang dibutuhkan demi memperluas fungsionalitas database untuk kebutuhan pengembangan spesifik. Jangan lupa untuk selalu inisialisasi environment ServBay, menentukan versi PostgreSQL target, serta teliti saat konfigurasi dan instalasi modul.

Semoga artikel ini membantu Anda menyesuaikan lingkungan PostgreSQL di ServBay sesuai kebutuhan. Jika menemui kendala lebih lanjut, silakan rujuk dokumentasi lain dari ServBay atau sumber komunitas terkait.