ServBay에서 PostgreSQL 모듈 컴파일하기

ServBay 로컬 웹 개발 환경에서 PostgreSQL 개발을 진행하다 보면 데이터베이스의 기능을 확장하거나 강화하기 위해 추가적인 PostgreSQL 모듈(확장, extension)을 컴파일 및 설치하는 일이 잦습니다. 이들 확장은 새로운 데이터 타입, 함수, 연산자, 인덱스 접근 방법 등 다양한 기능을 제공합니다.

본 가이드에서는 ServBay 환경에서 PostgreSQL 모듈을 컴파일 및 설치하는 방법을 설명하며, 대표적인 GIS 확장인 postgis와 중국어 형태소 분석기를 지원하는 pg_jieba 모듈의 빌드 사례를 통해 절차를 안내합니다.

개요

ServBay는 개발자가 사전 패키지된 소프트웨어들 위에 추가적인 구성 요소를 빌드하거나 직접 재컴파일할 수 있는 유연하고 강력한 환경을 제공합니다. PostgreSQL 모듈을 빌드하려면 보통 모듈의 소스 코드를 다운로드하고, 컴파일 설정을 잡고, 필요한 빌드 도구(예: make, cmake)를 사용해서 컴파일/설치하며, 마지막으로 PostgreSQL 데이터베이스에서 모듈을 활성화해야 합니다.

성공적인 빌드를 위해서는 ServBay에 설치된 해당 PostgreSQL 버전의 헤더, 라이브러리, 기타 의존성 라이브러리 등에 환경이 올바로 맞춰져 있어야 합니다.

사전 준비사항

모든 PostgreSQL 확장(모듈) 컴파일 전에 반드시 ServBay가 제공하는 빌드 환경을 초기화해야 합니다. 이 과정에서 필요한 툴체인(컴파일러, 링커 등) 및 빌드 환경 변수($PATH, $CFLAGS, $LDFLAGS 등), ServBay 전용 경로 등이 세팅됩니다.

초기화 절차는 ServBay 공식 문서의 ServBay로 2차 컴파일 하기 섹션을 참고하세요. 이 서류에 안내된 환경 스크립트 실행 등 기본적인 준비 과정을 반드시 선행하시기 바랍니다.

PostgreSQL 버전 지정의 중요성

ServBay는 여러 버전의 PostgreSQL을 동시에 설치·운영할 수 있습니다. PostgreSQL 모듈은 컴파일/동작 시 해당 버전에 맞는 헤더, 라이브러리, 내부 API에 강하게 의존하므로 컴파일 타겟이 될 DB의 버전 및 경로를 반드시 정확히 지정해야만 올바르게 동작하는 확장 파일을 만들 수 있습니다.

올바른 버전의 경로를 지정하지 않으면 빌드 과정에서 의존성 미스매치로 인한 오류나, 모듈 미탑재, 예기치 못한 런타임 문제가 발생할 수 있습니다.

이 예시에서는 ServBay에 설치된 PostgreSQL 15(예: 15.7 버전)을 기준으로 설명하나, 실제로 사용하는 PostgreSQL 버전에 따라 경로나 버전을 맞춰 주세요.

경로 설정은 ServBay의 환경 변수 및 pg_config 도구의 도움을 받아 진행합니다. ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/pg_config는 PostgreSQL이 제공하는 진단용 유틸리티로, 해당 버전의 설치 경로와 컴파일/헤더/라이브러리 정보 등을 제공합니다. 외부 모듈 컴파일에서는 반드시 이 경로를 활용해야 빌드가 성공합니다.

PostGIS 모듈 컴파일

PostGIS는 PostgreSQL에서 가장 널리 쓰이고 강력한 공간(GIS) 확장 모듈입니다. 공간 데이터를 저장·검색·분석할 수 있도록 GIS 오브젝트와 함수를 제공합니다. 아래는 postgis-3.4.2 모듈의 빌드 및 설치 가이드입니다.

1단계: 소스코드 다운로드

먼저 PostGIS 공식 사이트에서 postgis-3.4.2 소스 패키지를 다운로드합니다. 반드시 소스파일(보통 .tar.gz, .zip)을 받아야 합니다.

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

wget은 터미널에서 URL로 파일을 다운로드하는 표준 도구입니다.

2단계: 소스 압축 해제

다운로드한 postgis-3.4.2.tar.gz 파일을 적절한 위치에 압축 해제하고, 소스 디렉토리로 이동합니다.

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

tar zxvf는 .tar.gz 파일의 압축을 해제하며, cd로 해제된 postgis-3.4.2 디렉토리로 이동합니다.

3단계: 컴파일 옵션 설정

PostGIS는 GNU Autotools를 빌드 시스템으로 사용합니다. 설정 단계에서는 시스템 의존성 체크, 빌드 특성 확정, Makefile 생성 등이 이뤄지며, 이 과정에서 ServBay 내 지정 PostgreSQL 버전의 경로 및 필요 라이브러리 경로를 명확하게 지정해야 합니다.

./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: 빌드 환경 설정 스크립트 실행
• --prefix, --bindir, --datarootdir: 컴파일 후 PostGIS를 ServBay 내 PostgreSQL 특정 버전 경로에 설치하도록 지정. ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7는 ServBay의 PostgreSQL 15.7 루트 디렉토리(초기화 스크립트에서 자동 지정)입니다.
• --with-protobufdir: PostGIS에서 필요로 할 수 있는 Protobuf 라이브러리 경로 지정. ${SERVBAY_BIN_PATH}는 ServBay 실행 바이너리 위치입니다.
• --disable-nls: 다국어(NLS) 지원 비활성화(개발 용도로 권장)
• --without-raster, --without-topology: 지오래스터/토폴로지 기능 비활성화하여 빌드 간소화. 필요시 활성화 가능하나 추가 라이브러리 필요
• --with-pgconfig: 핵심 옵션. 빌드 시 사용할 pg_config 경로 지정. PostGIS 빌드 스크립트가 해당 PostgreSQL 버전의 컴파일 플래그/헤더/라이브러리 경로 정보를 자동으로 가져옵니다.
• CFLAGS, CXXFLAGS, LDFLAGS: C/C++ 컴파일러/링커 추가 옵션. ${CFLAGS}, ${CXXFLAGS}, ${LDFLAGS}는 ServBay 환경 초기화 시 세팅된 기본값을 유지합니다.
  • -I${SERVBAY_COMMON_INCLUDE_PATH}/libxml2 -I${SERVBAY_COMMON_INCLUDE_PATH}: libxml2 등 공용 헤더 경로 포함
  • -L${SERVBAY_COMMON_LIB_PATH} -lxml2 -lz ...: 공용 라이브러리 디렉토리 및 필수 라이브러리 연계. ServBay 환경에 기본 포함된 라이브러리 활용
  • -std=c++17: C++17 표준 사용(현대 C++ 프로젝트에 요구됨)

4단계: 컴파일 및 설치

설정이 정상적으로 끝나면, make를 통해 실제 소스 코드를 빌드하고, make install로 PostGIS 확장 파일을 지정된 ServBay PostgreSQL 경로에 설치합니다.

make -j ${CPU_NUMBER}
make install

• make -j ${CPU_NUMBER}: 병렬 컴파일 실행. ${CPU_NUMBER}는 ServBay가 환경에 맞게 세팅한 CPU 코어수로 빌드 속도를 최적화
• make install: 빌드된 확장(공유 라이브러리, SQL 스크립트 등)을 ServBay 내 PostgreSQL 15.7의 설치 경로(lib/postgresql, share/postgresql/extension 등)에 배치

5단계: 모듈 로드 검증

PostGIS를 성공적으로 설치했다면, 데이터베이스에서 확장(Extension)을 활성화해야 실제로 쓸 수 있습니다. ServBay 제공 커맨드라인 툴 또는 선호하는 PostgreSQL 클라이언트로 접속해 다음 SQL을 실행합니다.

ServBay 환경 터미널에서 psql을 사용하여 확인(ServBay 환경 변수가 올바로 적용된 상태에서 진행):

# PostGIS 확장 활성화
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "CREATE EXTENSION postgis;"

명령이 성공하면 PostGIS가 정상적으로 등록된 것입니다. 추가로 버전 정보를 조회할 수 있습니다.

# PostGIS 버전 확인
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "SELECT PostGIS_Version();"

PostGIS 버전 정보가 출력된다면 컴파일, 설치, 등록이 모두 정상적으로 완료된 상태입니다.

pg_jieba 모듈 컴파일

pg_jieba는 C++ 라이브러리 cppjieba 기반의 PostgreSQL 확장으로, DB 레벨에서 중국어 형태소 분석(분절/토큰화)을 지원합니다. CMake 기반 빌드 시스템을 사용합니다. 아래는 pg_jieba 모듈 컴파일 절차입니다.

1단계: 소스코드 확보

먼저 GitHub에서 pg_jieba 저장소를 클론하고, 내장 서브모듈인 cppjieba도 초기화해야 합니다.

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

• git clone ...: pg_jieba 저장소를 현재 디렉토리에 복사
• git submodule update --init --recursive: 모든 서브모듈(여기서는 cppjieba)까지 다운로드하여 소스 디렉토리 구조 완성

2단계: 빌드 옵션 설정 (CMake)

pg_jieba는 CMake 빌드 시스템을 사용합니다. cmake 명령을 통해 빌드 구성을 지정하고, PostgreSQL 경로 및 macOS 타겟 등을 명시합니다.

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: 현재 디렉토리(-S .)를 소스, builddir 하위 디렉토리를 빌드 디렉토리로 사용해 CMake 설정
• -DCMAKE_PREFIX_PATH: 중요 옵션. PostgreSQL 설치 경로 정보 제공. Postgres/pg_config 정보 기반으로 의존 경로 탐지
• -DCMAKE_OSX_DEPLOYMENT_TARGET: macOS 최소 타깃 버전 지정. ServBay 환경 변수인 ${BUILD_OS_MIN_VERSION} 적용
• -DCMAKE_OSX_ARCHITECTURES: 빌드 CPU 아키텍처(x86_64/arm64) 지정. ServBay가 세팅한 ${BUILD_CPU_ARCH_CMAKE}값 사용

3단계: 컴파일 및 설치 (CMake)

구성이 끝나면 CMake 커맨드로 실제 빌드를 수행하고, 빌드 결과물을 PostgreSQL에 설치합니다.

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

• cmake --build builddir: builddir 디렉토리에서 컴파일 진행
• -j ${CPU_NUMBER}: 병렬 컴파일 수행
• cmake --install builddir: 빌드 결과물을 PostgreSQL 확장 경로에 설치(CMake와 pg_config 정보에 따라 자동 위치 설정)

4단계: 모듈 로딩 검증

설치가 완료되면 PostgreSQL에 접속해서 확장을 활성화합니다. ServBay 터미널에서 커맨드라인을 실행합니다.

# pg_jieba 확장 활성화
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "CREATE EXTENSION pg_jieba;"

성공적으로 적용됐다면 아래처럼 설치 모듈을 확인할 수 있습니다.

# 설치된 확장 목록 확인
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "SELECT * FROM pg_available_extensions WHERE name = 'pg_jieba';"

모듈 정보가 정상적으로 조회된다면 빌드, 설치, 활성화가 모두 완료된 것입니다.

자주 묻는 질문 (FAQ)

• 컴파일 과정에서 헤더파일 또는 라이브러리를 찾지 못한다는 에러가 발생합니다.
  • ServBay 빌드 환경을 올바르게 초기화했는지 확인하세요. ServBay 터미널에서 환경 스크립트가 실행됐고, 모든 관련 환경 변수 ($CFLAGS, $LDFLAGS, ${SERVBAY_COMMON_INCLUDE_PATH}, ${SERVBAY_COMMON_LIB_PATH} 등)가 올바른 위치를 가리키는지 점검합니다.
  • 설정 명령(Autotools: --with-pgconfig, CMake: -DCMAKE_PREFIX_PATH)에서 PostgreSQL 버전 및 경로가 정확한지, 해당 경로에 pg_config가 존재하고 실행 가능한지 확인합니다.
  • 일부 모듈(PostGIS 등)은 ServBay가 기본 제공하는 공용 라이브러리 이외에 별도 시스템 라이브러리(예: GEOS, GDAL 등)가 필요할 수 있습니다. 이 경우 직접 의존 패키지를 설치하거나, 빌드 시 특정 기능을 비활성화(--without-raster 등) 하세요.
• CREATE EXTENSION 명령이 실패하며 모듈 파일을 찾을 수 없다고 나옵니다.
  • make install 또는 cmake --install이 정상적으로 완료됐는지, 에러가 없는지 확인하고, 설치 로그에서 파일이 올바른 경로에 복사됐는지 점검합니다.
  • 설정 과정에서(--prefix 또는 -DCMAKE_PREFIX_PATH) 지정한 설치 경로가 원하는 PostgreSQL 버전 경로와 정확히 일치하는지 확인합니다. 확장 파일은 주로 해당 경로의 lib/postgresql 하위에 설치됩니다.
  • PostgreSQL 서버를 한번 재시작 하세요. 경우에 따라 신규 확장은 재시작 시 인식될 수 있습니다. ServBay 앱의 UI로 쉽게 재시작할 수 있습니다.
  • PostgreSQL의 shared_preload_libraries 설정을 확인하세요. 대부분의 일반 확장은 별도 설정 없이 바로 불러올 수 있으나, 내부 훅킹이 필요한 특수 확장은 명시적으로 해당 옵션에 등록하고 서버 부팅 시 로딩이 필요합니다. 각각의 모듈 공식 문서를 별도로 참고하세요.
• 다른 버전의 PostgreSQL에 모듈을 빌드하고 싶을 때는 어떻게 하나요?
  • 동일한 절차를 반복하되, 설정 명령(Autotools: --with-pgconfig, CMake: -DCMAKE_PREFIX_PATH)에서 반드시 원하는 버전의 pg_config 경로나 설치 경로로 수정하세요. 예를 들어 PostgreSQL 14에 설치할 경우 ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/14/14.x/bin/pg_config 또는 ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/14/14.x (여기서 14.x는 실제 버전) 경로로 세팅하면 됩니다.

요약

이 가이드의 절차와 ServBay에서 제공하는 빌드 환경·도구를 적절히 사용한다면, ServBay 로컬 개발 환경 내에서 PostgreSQL의 다양한 확장 모듈을 직접 빌드하고, 맞춤형 데이터베이스 환경을 구축할 수 있습니다. 빌드 환경 초기화, 타깃 PostgreSQL 버전 지정, 빌드/설치 경로 점검이 성공의 핵심입니다.

추가적인 질문이나 어려움이 있다면 ServBay의 다른 문서나 커뮤니티를 참고하시기 바랍니다.