ServBay

Tiếng Việt

English
简体中文
繁體中文
Español
العربية
Português
Русский
日本語
Deutsch
Français
Türkçe
Italiano

Tiếng Việt

English
简体中文
繁體中文
Español
العربية
Português
Русский
日本語
Deutsch
Français
Türkçe
Italiano

Appearance

Cách Biên Dịch Module PostgreSQL Trong ServBay ​

Khi phát triển với môi trường web cục bộ ServBay và sử dụng PostgreSQL, bạn có thể cần biên dịch và cài đặt các module (extension) bổ sung cho PostgreSQL nhằm nâng cao hoặc mở rộng chức năng của cơ sở dữ liệu. Những module này có thể bổ sung kiểu dữ liệu mới, hàm, toán tử, phương pháp truy cập chỉ mục, v.v.

Bài viết này sẽ hướng dẫn chi tiết cách biên dịch và cài đặt module PostgreSQL trong môi trường ServBay, cùng ví dụ thực tế với hai module phổ biến: postgis (hỗ trợ hệ thống thông tin địa lý) và pg_jieba (phân tách từ tiếng Trung).

Tổng Quan ​

ServBay cung cấp một môi trường linh hoạt, mạnh mẽ, cho phép lập trình viên phát triển mở rộng hoặc biên dịch thêm các thành phần dựa trên những gói phần mềm được tích hợp sẵn. Quá trình biên dịch module PostgreSQL thường bao gồm tải về mã nguồn module, cấu hình tùy chọn biên dịch, sử dụng công cụ xây dựng (như make hoặc cmake) để biên dịch và cài đặt, cuối cùng là kích hoạt module trong PostgreSQL.

Yếu tố quan trọng để thành công là cấu hình chính xác môi trường biên dịch để hệ thống nhận diện được thư mục header, file thư viện cùng các phụ thuộc của đúng phiên bản PostgreSQL cài đặt trong ServBay.

Các Yêu Cầu Trước Khi Bắt Đầu ​

Trước khi biên dịch bất kỳ module PostgreSQL nào, bạn bắt buộc phải khởi tạo môi trường biên dịch theo hướng dẫn của ServBay. Bước này sẽ thiết lập chuỗi công cụ (compiler, linker…), biến môi trường cần thiết (như $PATH, $CFLAGS, $LDFLAGS, v.v.) cùng các đường dẫn cấu hình dành riêng cho ServBay.

Hãy tham khảo phần Biên dịch lại gói với ServBay trong tài liệu chính thức của ServBay để thực hiện khởi tạo môi trường. Hãy đảm bảo hoàn thành bước chuẩn bị này, thường là chạy script khởi tạo môi trường bằng terminal ServBay.

Tầm Quan Trọng Của Việc Xác Định Phiên Bản PostgreSQL ​

ServBay cho phép cài đặt và chạy đồng thời nhiều phiên bản PostgreSQL. Việc biên dịch module PostgreSQL phụ thuộc chặt chẽ vào phiên bản cụ thể (ví dụ, phụ thuộc vào file header, thư viện và API nội bộ của version đó), do đó khi biên dịch bạn cần chỉ định rõ thư mục cấu hình tương ứng với đúng phiên bản PostgreSQL mà bạn sẽ sử dụng.

Chọn đúng đường dẫn cấu hình phiên bản PostgreSQL giúp quá trình biên dịch nhận diện chính xác các phụ thuộc, tạo ra file module tương thích với phiên bản mục tiêu, qua đó ngăn ngừa lỗi biên dịch, lỗi tải module hoặc sự cố bất ổn khi chạy.

Trong hướng dẫn này, chúng ta lấy ví dụ với PostgreSQL 15 (ví dụ như phiên bản 15.7) đã cài trong ServBay. Bạn hãy điều chỉnh các đường dẫn cho phù hợp với phiên bản thực tế đang sử dụng.

ServBay cung cấp các biến môi trường và công cụ pg_config để bạn dễ dàng tìm đúng đường dẫn. ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/pg_config là công cụ tiện ích đi kèm với PostgreSQL, giúp báo cáo đường dẫn cài đặt, thông tin biên dịch, thư viện và thư mục header cho phiên bản cụ thể. Khi biên dịch module ngoài, pg_config đóng vai trò then chốt để chỉ định các phụ thuộc cần thiết.

Biên Dịch Module postgis ​

Module postgis là một trong những extension mạnh mẽ, phổ biến nhất của PostgreSQL, giúp cơ sở dữ liệu có thể lưu trữ, truy vấn và phân tích dữ liệu không gian (GIS). Dưới đây là hướng dẫn biên dịch postgis-3.4.2:

Bước 1: Tải Về Mã Nguồn ​

Tải mã nguồn module postgis-3.4.2 từ website chính thức của PostGIS. Hãy đảm bảo bạn lấy gói mã nguồn (thường là file .tar.gz hoặc .zip).

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

wget là công cụ dòng lệnh phổ biến dùng để tải file từ một URL được chỉ định.

Bước 2: Giải nén Gói Mã Nguồn ​

Giải nén gói postgis-3.4.2.tar.gz ra thư mục hiện tại và chuyển vào thư mục code.

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

tar zxvf giúp giải nén file .tar.gz. Lệnh cd chuyển sang thư mục gốc chứa mã nguồn đã giải nén.

Bước 3: Cấu Hình Tùy Chọn Biên Dịch ​

PostGIS sử dụng hệ thống xây dựng GNU Autotools. Bước cấu hình sẽ kiểm tra các phụ thuộc hệ thống, xác định các tính năng sẽ biên dịch và sinh ra file Makefile. Ở bước này, bạn cần thông qua tham số cấu hình để xác định đường dẫn cài đặt PostgreSQL mong muốn trong ServBay và các thư viện cần thiết khác.

bash
./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: Chạy script cấu hình.
  • --prefix, --bindir, --datarootdir: Chỉ định vị trí cài đặt module postgis tương ứng với đúng cấu trúc thư mục của PostgreSQL trong ServBay. ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7 là thư mục gốc cài đặt của PostgreSQL 15.7 do script môi trường ServBay thiết lập.
  • --with-protobufdir: Chỉ định thư mục thư viện Protobuf mà PostGIS có thể cần. ${SERVBAY_BIN_PATH} là đường dẫn chứa file nhị phân các gói trong ServBay.
  • --disable-nls: Vô hiệu hóa hỗ trợ đa ngôn ngữ, giúp đơn giản hóa trong môi trường phát triển.
  • --without-raster, --without-topology: Vô hiệu hóa hỗ trợ Raster/Topology để giảm phụ thuộc, bạn có thể bật lại nếu cần nhưng sẽ phải cài thêm các thư viện hỗ trợ.
  • --with-pgconfig: Tham số quan trọng nhất, chỉ định chính xác đường dẫn công cụ pg_config cho phiên bản PostgreSQL mục tiêu. pg_config sẽ cung cấp các thông tin cần thiết về cờ biên dịch, thư viện cho script cấu hình PostGIS, đảm bảo module tương thích với PostgreSQL bạn định sử dụng.
  • CFLAGS, CXXFLAGS, LDFLAGS: Biến môi trường chuẩn truyền thêm tham số cho trình biên dịch/link. ${CFLAGS}, ${CXXFLAGS}, ${LDFLAGS} giữ các giá trị mặc định được khởi tạo bởi môi trường ServBay.
    • -I${SERVBAY_COMMON_INCLUDE_PATH}/libxml2 -I${SERVBAY_COMMON_INCLUDE_PATH}: Thêm các thư mục chứa header của libxml2 và những thư viện chung do ServBay cung cấp.
    • -L${SERVBAY_COMMON_LIB_PATH} -lxml2 -lz ...: Thêm thư mục chứa thư viện động và liên kết các thư viện cần thiết (libxml2, zlib, pthread, iconv, icu ...).
    • -std=c++17: Chỉ định chuẩn C++17 cho trình biên dịch C++ khi cần thiết.

Bước 4: Biên Dịch và Cài Đặt ​

Khi cấu hình thành công, hãy chạy lệnh make để biên dịch và make install để cài đặt module vào đúng vị trí của PostgreSQL đã chọn.

bash
make -j ${CPU_NUMBER}
make install
  • make -j ${CPU_NUMBER}: Bắt đầu biên dịch nguồn. Tham số -j ${CPU_NUMBER} tận dụng đa nhân CPU (giá trị ${CPU_NUMBER} do ServBay xác định), giúp rút ngắn thời gian biên dịch.
  • make install: Các file sinh ra (thư viện PostGIS, script SQL…) sẽ được copy vào đúng thư mục cài đặt của PostgreSQL 15.7 trong ServBay (lib/postgresql, share/postgresql/extension...).

Bước 5: Kiểm Tra Module đã Được Nạp ​

Sau khi cài đặt, bạn cần kích hoạt extension postgis trong cơ sở dữ liệu PostgreSQL. Hãy kết nối với database qua dòng lệnh ServBay hoặc qua tool client và chạy lệnh SQL sau.

Sử dụng tool psql kèm theo ServBay, lưu ý đảm bảo bạn đang trong session terminal đã thiết lập môi trường ServBay.

bash
# Tạo Extension PostGIS trong cơ sở dữ liệu
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "CREATE EXTENSION postgis;"

Nếu lệnh này không báo lỗi, extension đã cài đặt thành công. Bạn có thể kiểm tra thông tin version:

bash
# Kiểm tra version PostGIS
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "SELECT PostGIS_Version();"

Nếu thấy thông tin version trả về, tức là module đã biên dịch, cài đặt và nạp vào database thành công.

Biên Dịch Module pg_jieba ​

pg_jieba là một extension PostgreSQL dựa trên thư viện C++ cppjieba, dùng để phân tách từ tiếng Trung trong PostgreSQL (hay cho tìm kiếm toàn văn…). pg_jieba sử dụng CMake làm hệ thống xây dựng. Sau đây là các bước cài đặt:

Bước 1: Tải Mã Nguồn ​

Dùng Git để clone repo pg_jieba và khởi tạo các submodule (phải tải luôn thư viện cppjieba làm submodule).

bash
git clone https://github.com/jaiminpan/pg_jieba.git
cd pg_jieba
git submodule update --init --recursive
  • git clone ...: Tải repo về thư mục hiện tại.
  • git submodule update --init --recursive: Khởi tạo & cập nhật tất cả submodule Git trong repository. Đây là bước giúp code thư viện cppjieba được tải về đầy đủ.

Bước 2: Cấu Hình Tùy Chọn Biên Dịch (CMake) ​

Module này dùng công cụ CMake để cấu hình và sinh file build. Bạn cần cung cấp đường dẫn cài đặt PostgreSQL, version macOS và kiến trúc CPU tương ứng.

bash
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: Cấu hình CMake, -S . là thư mục mã nguồn hiện tại, -B builddir là vị trí thư mục build. Cách này giữ cho folder code nguồn sạch, toàn bộ file sinh ra nằm trong builddir.
  • -DCMAKE_PREFIX_PATH: Tham số quan trọng, giúp CMake nhận diện đúng thư viện và thư mục header của PostgreSQL 15.7 được cài trong ServBay (và các phụ thuộc khác). CMake sẽ dựa trên thông tin này cùng pg_config để xác định file/link đúng version PostgreSQL.
  • -DCMAKE_OSX_DEPLOYMENT_TARGET: Đặt version tối thiểu macOS mà module hỗ trợ, ${BUILD_OS_MIN_VERSION} do ServBay cấu hình.
  • -DCMAKE_OSX_ARCHITECTURES: Kiến trúc CPU (ví dụ x86_64 hoặc arm64), giá trị từ ${BUILD_CPU_ARCH_CMAKE}, giúp module tương thích với nền tảng đang sử dụng.

Bước 3: Biên Dịch và Cài Đặt (CMake) ​

Sau khi cấu hình thành công, dùng lệnh dưới đây để build và cài đặt.

bash
cmake --build builddir -j ${CPU_NUMBER}
cmake --install builddir
  • cmake --build builddir: Biên dịch toàn bộ code trong thư mục builddir.
  • -j ${CPU_NUMBER}: Build song song để tăng tốc quá trình biên dịch.
  • cmake --install builddir: Cài đặt file sinh ra vào vị trí PostgreSQL mà -DCMAKE_PREFIX_PATH chỉ định (thường là mục lib/postgresql và share/postgresql/extension).

Bước 4: Kiểm Tra Module đã Được Nạp ​

Sau khi cài đặt, cần kích hoạt extension pg_jieba trong database PostgreSQL. Sử dụng dòng lệnh trong môi trường ServBay như sau:

bash
# Tạo Extension pg_jieba
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "CREATE EXTENSION pg_jieba;"

Nếu lệnh này thành công, có thể kiểm tra thông tin về extension vừa cài bằng lệnh:

bash
# Xem danh sách extension, kiểm tra module pg_jieba
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "SELECT * FROM pg_available_extensions WHERE name = 'pg_jieba';"

Nếu module xuất hiện trong kết quả trả về, toàn bộ quá trình biên dịch, cài đặt và kích hoạt đã hoàn tất.

Câu Hỏi Thường Gặp (FAQ) ​

  • Biên dịch bị lỗi vì không tìm thấy file header hoặc thư viện?
    • Hãy kiểm tra lại bạn đã khởi tạo môi trường biên dịch ServBay đúng cách chưa. Đảm bảo đã chạy script khởi động môi trường cần thiết để set các biến như $CFLAGS, $LDFLAGS, ${SERVBAY_COMMON_INCLUDE_PATH}, ${SERVBAY_COMMON_LIB_PATH}… về đúng thư mục của ServBay.
    • Kiểm tra kỹ lệnh --with-pgconfig (Autotools) hoặc -DCMAKE_PREFIX_PATH (CMake) chỉ đúng thư mục PostgreSQL mục tiêu và đã tồn tại file pg_config khả dụng trong đó.
    • Một số module có thể có thêm phụ thuộc ngoài bộ thư viện ServBay (ví dụ PostGIS khi bật Raster/Topology sẽ cần thêm GEOS, GDAL...). Dù ServBay đã cung cấp khá nhiều thư viện dùng chung, vẫn có trường hợp cần tự cài thêm hoặc tắt bớt tính năng để tránh lỗi.
  • Chạy CREATE EXTENSION bị lỗi không tìm thấy module?
    • Đảm bảo lệnh make install (Autotools) hoặc cmake --install (CMake) đã thực thi không gặp vấn đề gì và file đã được copy đúng vị trí.
    • Kiểm tra kỹ đường dẫn cấu hình đặt cho --prefix (Autotools) hoặc -DCMAKE_PREFIX_PATH (CMake) trỏ về chính xác PostgreSQL tương ứng của ServBay. Thư viện module sẽ nằm trong lib/postgresql.
    • Thử khởi động lại dịch vụ PostgreSQL vì đôi khi phải restart mới nhận diện extension mới. Có thể restart qua giao diện ứng dụng ServBay.
    • Kiểm tra thiết lập shared_preload_libraries trong PostgreSQL. Đa số extension chỉ cần CREATE EXTENSION, không cần can thiệp file config, nhưng một số module đặc biệt có thể cần được thêm vào biến này trong file cấu hình rồi mới dùng được. Tham khảo tài liệu riêng về module bạn định biên dịch nếu gặp vấn đề.
  • Muốn build module cho nhiều version PostgreSQL thì làm thế nào?
    • Lặp lại các bước hướng dẫn trên, nhưng thay đổi đường dẫn cho --with-pgconfig (Autotools) hoặc -DCMAKE_PREFIX_PATH (CMake) trỏ đúng tới phiên bản PostgreSQL mong muốn (VD: ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/14/14.x/bin/pg_config với 14.x chính là version PostgreSQL 14 bạn cài trong ServBay).

Tổng Kết ​

Bằng cách áp dụng chính xác từng bước trên, kết hợp với môi trường và công cụ do ServBay cung cấp, bạn hoàn toàn có thể biên dịch, cài đặt các module PostgreSQL để mở rộng tính năng cơ sở dữ liệu trong môi trường phát triển cục bộ của mình. Những điểm mấu chốt quan trọng là: khởi tạo môi trường biên dịch đầy đủ, chọn đúng version PostgreSQL và kiểm tra kỹ thông số cấu hình, đường dẫn cài đặt khi build.

Hy vọng bài viết đã giúp bạn tự tin tùy biến môi trường PostgreSQL trên ServBay. Nếu gặp vướng mắc khác, hãy tham khảo thêm tài liệu chính thức hoặc nguồn cộng đồng ServBay.