RockyLinux 10 Oracle Instant Client 및 PHP OCI8 연동

본 문서는 RockyLinux 10 환경에서 Oracle Instant Client를 설치하고 PHP OCI8 확장을 연동하는 방법을 정리한 서버 구축 매뉴얼입니다. 이전 글에서 PHP 8.5와 PHP-FPM까지 구성했다면, 이번 글에서는 PHP 애플리케이션에서 Oracle Database에 접속할 수 있도록 Oracle Client와 OCI8 확장을 설치합니다.

Oracle 연동은 일반적인 MySQL, MariaDB 연동보다 신경 써야 할 부분이 많습니다. 단순히 PHP 확장만 설치한다고 끝나는 것이 아니라, Oracle Instant Client 라이브러리 경로가 시스템에 정상 등록되어야 하고, PHP CLI와 PHP-FPM 양쪽에서 OCI8 확장이 정상적으로 로드되는지도 확인해야 합니다.

특히 공공기관, 도서관, 대학, 내부 업무 시스템에서는 Oracle Database를 사용하는 경우가 많습니다. PHP 기반 시스템에서 이러한 Oracle DB와 연동해야 한다면 이 글의 절차를 기준으로 환경을 구성할 수 있습니다.

1. Oracle Instant Client가 필요한 이유

PHP에서 Oracle Database에 접속하려면 OCI8 확장이 필요합니다. 그런데 OCI8 확장은 Oracle Database와 직접 통신하는 모든 기능을 자체적으로 포함하고 있지 않습니다. Oracle에서 제공하는 클라이언트 라이브러리, 즉 Oracle Instant Client가 시스템에 설치되어 있어야 합니다.

구조를 단순화하면 다음과 같습니다.

PHP 애플리케이션: 실제 웹 애플리케이션 코드가 실행됩니다.
PHP OCI8 확장: PHP에서 Oracle 접속 함수를 사용할 수 있게 해줍니다.
Oracle Instant Client: Oracle 서버와 통신하는 실제 클라이언트 라이브러리입니다.
Oracle Database: 실제 데이터가 저장되어 있는 Oracle DB 서버입니다.

즉, PHP에서 oci_connect() 같은 함수를 사용하려면 PHP OCI8 확장과 Oracle Instant Client가 모두 필요합니다.

2. 설치 전 확인 사항

이 글은 앞선 시리즈에서 PHP 8.5가 이미 설치되어 있다는 전제에서 진행합니다. 먼저 PHP가 정상적으로 설치되어 있는지 확인합니다.

php -v

PHP-FPM 서비스도 사용 중이라면 상태를 확인합니다.

systemctl status php-fpm

Oracle 연동은 PHP CLI에서만 동작하고 PHP-FPM에서는 동작하지 않는 경우가 종종 있습니다. 따라서 설치 후에는 php --ri oci8만 확인하지 말고, 웹에서 실행되는 PHP 환경에서도 확장이 로드되는지 확인해야 합니다.

3. Oracle Instant Client 다운로드

Oracle Instant Client는 Oracle 공식 사이트에서 다운로드합니다. PHP OCI8 연동에는 일반적으로 아래 두 가지 패키지가 필요합니다.

Oracle Instant Client Basic: Oracle 접속에 필요한 기본 런타임 라이브러리입니다.
Oracle Instant Client Development: OCI8 확장 빌드 또는 연동에 필요한 개발 헤더와 라이브러리를 포함합니다.

Oracle 공식 다운로드 페이지에서 Linux x86-64용 RPM 파일을 다운로드합니다.

https://www.oracle.com/database/technologies/instant-client/linux-x86-64-downloads.html

다운로드 파일명은 Oracle 버전에 따라 달라질 수 있습니다. 예를 들어 다음과 같은 형태입니다.

oracle-instantclient-basic-linuxx64.rpm
oracle-instantclient-devel-linuxx64.rpm

실제 파일명에는 버전 번호가 포함될 수 있으므로, 다운로드한 파일명을 기준으로 명령어를 조정해야 합니다.

4. Oracle Instant Client RPM 설치

다운로드한 RPM 파일을 서버로 업로드한 뒤 설치합니다. 여기서는 현재 디렉터리에 RPM 파일이 있다고 가정합니다.

dnf install -y \
    ./oracle-instantclient-basic-linuxx64.rpm \
    ./oracle-instantclient-devel-linuxx64.rpm

파일명이 실제와 다르다면 아래처럼 ls 명령으로 확인한 뒤 맞춰서 설치합니다.

ls -al oracle-instantclient*.rpm

설치가 완료되면 Oracle Client 라이브러리는 일반적으로 /usr/lib/oracle/버전/client64/lib 형태의 경로에 설치됩니다.

5. Oracle 라이브러리 경로 확인

Oracle Instant Client 설치 후에는 시스템 동적 링커가 Oracle 라이브러리 경로를 인식해야 합니다. 먼저 아래 파일을 확인합니다.

vi /etc/ld.so.conf.d/oracle-instantclient.conf

파일 안에 Oracle Client 라이브러리 경로가 들어 있어야 합니다. 예시는 다음과 같습니다.

/usr/lib/oracle/23/client64/lib

여기서 23은 예시 버전입니다. 실제 설치한 Oracle Instant Client 버전에 맞는 경로인지 반드시 확인해야 합니다. 경로가 잘못되어 있으면 PHP OCI8 확장이 설치되어 있어도 Oracle 라이브러리를 찾지 못해 오류가 발생할 수 있습니다.

경로를 확인하거나 수정한 뒤에는 ldconfig를 실행합니다.

ldconfig

ldconfig는 시스템의 공유 라이브러리 캐시를 갱신하는 명령입니다. Oracle Client를 설치하거나 라이브러리 경로를 수정한 뒤에는 반드시 실행하는 것이 좋습니다.

6. PHP OCI8 확장 설치

Oracle Instant Client 설치가 완료되었다면 PHP OCI8 확장을 설치합니다. Remi Repository를 통해 PHP를 설치한 환경이라면 다음 명령으로 설치할 수 있습니다.

dnf install -y php-pecl-oci8

설치 후 PHP에서 OCI8 확장이 로드되는지 확인합니다.

php --ri oci8

정상적으로 로드되면 OCI8 확장 정보가 출력됩니다. 출력 내용에서 OCI8 Support 항목이 enabled 상태인지 확인합니다.

OCI8 Support => enabled

만약 확장이 로드되지 않는다면 Oracle Client 라이브러리 경로, PHP 버전, 설치된 php-pecl-oci8 패키지의 호환성을 다시 확인해야 합니다.

7. PHP-FPM 재시작

PHP 확장을 설치한 뒤에는 PHP-FPM을 재시작해야 웹 애플리케이션에서도 새 확장을 사용할 수 있습니다.

systemctl restart php-fpm

재시작 후 상태를 확인합니다.

systemctl status php-fpm

PHP-FPM이 정상적으로 올라오지 않는다면 확장 로드 과정에서 오류가 발생했을 가능성이 있습니다. 이 경우 PHP-FPM 로그 또는 systemd 로그를 확인합니다.

journalctl -u php-fpm -n 100 --no-pager

8. PHP 웹 환경에서 OCI8 확인

CLI에서 php --ri oci8가 정상이라고 해서 웹에서도 항상 정상이라고 볼 수는 없습니다. PHP CLI와 PHP-FPM이 서로 다른 설정 파일을 참조하거나, PHP-FPM 재시작이 누락된 경우 웹에서는 확장이 보이지 않을 수 있습니다.

웹 루트에 임시로 phpinfo() 파일을 생성해 확인합니다.

<?php
phpinfo();

브라우저에서 해당 파일에 접속한 뒤 oci8 항목이 있는지 확인합니다. 확인이 끝난 뒤에는 보안상 반드시 파일을 삭제해야 합니다.

rm -f /home/USER/src/phpinfo.php

운영 서버에 phpinfo() 파일을 남겨두면 PHP 버전, 확장, 경로, 서버 정보가 노출될 수 있으므로 절대 그대로 두면 안 됩니다.

9. 간단한 Oracle 접속 테스트

OCI8 확장이 정상적으로 로드되었다면 간단한 PHP 코드로 Oracle 접속을 테스트할 수 있습니다.

<?php

$username = 'DB_USER';
$password = 'DB_PASSWORD';
$connectionString = '127.0.0.1:1521/ORCLPDB1';

$conn = oci_connect($username, $password, $connectionString, 'AL32UTF8');

if (!$conn) {
    $error = oci_error();
    echo 'Oracle connection failed: ' . $error['message'];
    exit;
}

echo 'Oracle connection success';

oci_close($conn);

여기서 $connectionString은 Oracle 서버 환경에 맞게 수정해야 합니다. 일반적으로 다음과 같은 형식을 사용합니다.

호스트:포트/서비스명

예를 들면 다음과 같습니다.

192.168.0.10:1521/ORCL

한글 데이터를 다루는 경우에는 네 번째 인자로 문자셋을 명시하는 것이 좋습니다. 일반적으로 AL32UTF8을 사용합니다.

10. tnsnames.ora를 사용하는 경우

접속 문자열을 직접 쓰는 방식 대신 tnsnames.ora를 사용하는 환경도 있습니다. 이 경우 Oracle 네트워크 설정 파일 경로를 지정해야 할 수 있습니다.

예를 들어 /usr/lib/oracle/network/admin 디렉터리를 만들고 tnsnames.ora를 배치할 수 있습니다.

mkdir -p /usr/lib/oracle/network/admin
vi /usr/lib/oracle/network/admin/tnsnames.ora

예시 설정은 다음과 같습니다.

ORCL =
    (DESCRIPTION =
        (ADDRESS = (PROTOCOL = TCP)(HOST = 192.168.0.10)(PORT = 1521))
        (CONNECT_DATA =
            (SERVICE_NAME = ORCL)
        )
    )

이후 PHP에서는 다음처럼 접속할 수 있습니다.

$conn = oci_connect('DB_USER', 'DB_PASSWORD', 'ORCL', 'AL32UTF8');

서버 환경에 따라 TNS_ADMIN 환경 변수를 지정해야 할 수 있습니다. PHP-FPM 환경에서 환경 변수를 사용할 경우에는 PHP-FPM pool 설정 또는 systemd 서비스 환경 설정까지 함께 확인해야 합니다.

11. 자주 발생하는 오류

1) libclntsh.so 파일을 찾지 못하는 경우

OCI8 확장이 Oracle Client 라이브러리를 찾지 못할 때 발생합니다. Oracle 라이브러리 경로가 /etc/ld.so.conf.d/oracle-instantclient.conf에 정상 등록되어 있는지 확인하고 ldconfig를 다시 실행합니다.

cat /etc/ld.so.conf.d/oracle-instantclient.conf
ldconfig

2) PHP CLI에서는 되는데 웹에서는 안 되는 경우

PHP-FPM 재시작이 누락되었거나, PHP CLI와 PHP-FPM이 서로 다른 설정을 사용하는 경우입니다. 먼저 PHP-FPM을 재시작합니다.

systemctl restart php-fpm

그래도 해결되지 않으면 웹에서 phpinfo()를 확인해 OCI8 확장이 로드되어 있는지 확인합니다.

3) 한글이 깨지는 경우

접속 시 문자셋을 지정하지 않았거나, Oracle DB의 문자셋과 애플리케이션 문자셋이 맞지 않는 경우입니다. 일반적으로 PHP에서 접속할 때 네 번째 인자로 AL32UTF8을 지정합니다.

oci_connect($username, $password, $connectionString, 'AL32UTF8');

4) ORA-12154 오류

TNS alias를 해석하지 못할 때 발생합니다. tnsnames.ora 경로, TNS_ADMIN 설정, alias 이름을 확인해야 합니다. 직접 접속 문자열 방식으로 먼저 접속 테스트를 해보는 것도 좋습니다.

5) ORA-12514 또는 ORA-12505 오류

Oracle Listener는 접근되지만 서비스명 또는 SID가 맞지 않을 때 발생할 수 있습니다. 이 경우 Oracle 서버의 서비스명, SID, Listener 설정을 확인해야 합니다.

12. 운영 서버에서의 권장 사항

Oracle Client 버전 관리: 운영 서버에서는 설치한 Instant Client RPM 파일과 버전을 별도로 기록해두는 것이 좋습니다.
PHP-FPM 재시작 절차 포함: PHP 확장 설치 또는 변경 후에는 반드시 PHP-FPM 재시작을 배포 절차에 포함해야 합니다.
문자셋 명시: 한글 데이터를 다루는 경우 oci_connect()에서 문자셋을 명시하는 것이 안전합니다.
접속 정보 분리: DB 계정, 비밀번호, 접속 문자열은 소스코드에 직접 작성하지 말고 환경 설정 파일이나 보안 설정 파일로 분리하는 것이 좋습니다.
phpinfo 파일 삭제: 확인용으로 만든 phpinfo() 파일은 테스트 직후 반드시 삭제해야 합니다.

13. 전체 설치 명령 요약

전체 과정을 간단히 정리하면 다음과 같습니다.

# Oracle Instant Client RPM 설치
    dnf install -y \
        ./oracle-instantclient-basic-linuxx64.rpm \
        ./oracle-instantclient-devel-linuxx64.rpm

# 라이브러리 경로 확인
vi /etc/ld.so.conf.d/oracle-instantclient.conf

# 라이브러리 캐시 갱신
ldconfig

# PHP OCI8 확장 설치
dnf install -y php-pecl-oci8

# OCI8 확장 확인
php --ri oci8

# PHP-FPM 재시작
systemctl restart php-fpm

마무리

RockyLinux 10에서 PHP와 Oracle Database를 연동하려면 Oracle Instant Client와 PHP OCI8 확장이 모두 필요합니다. 설치 자체는 복잡하지 않지만, 라이브러리 경로 등록, ldconfig 실행, PHP-FPM 재시작, 웹 환경에서의 확장 로드 확인까지 빠짐없이 점검해야 합니다.

특히 PHP CLI에서는 정상인데 웹에서 동작하지 않는 문제가 자주 발생하므로, 설치 후에는 반드시 PHP-FPM 기준으로도 OCI8 로드 여부를 확인해야 합니다. 한글 데이터를 다루는 시스템이라면 AL32UTF8 문자셋 지정도 함께 적용하는 것이 좋습니다.

다음 글에서는 RockyLinux 10 + PHP + Nginx + MariaDB 운영 서버 구축 최종 정리를 통해 지금까지 구성한 내용을 하나의 실전 서버 구성 흐름으로 정리합니다.

RockyLinux 10 Oracle Instant Client 및 PHP OCI8 연동

Usefull Links

Question?