[MacOS][Python] 오라클 DB 모듈 사용하기

Python에서 일반적으로 사용하는 대부분의 모듈은 Python 코드로 작성되어 있으며, pip install만으로 간단히 사용할 수 있습니다.

하지만 Oracle DB 연동 모듈(oracledb, cx_Oracle)은 기본적으로 C 기반의 Oracle Client 라이브러리를 필요로 하며, 이 때문에 일반적인 Python 모듈들과는 다르게 별도의 시스템 라이브러리 설치 및 환경 변수 설정이 필요합니다.

이 글에서는 MacOS에서 Python으로 Oracle DB에 연결하기 위한 모든 과정을 정리합니다. 특히 M1/M2 칩 기반의 Apple Silicon 사용자도 문제없이 설정할 수 있도록 설명합니다.

1. Python Oracle 모듈 설치

pip install oracledb

oracledb는 Oracle에서 공식적으로 제공하는 Python용 DB 연동 모듈입니다.
내부적으로 Oracle Client C 라이브러리를 사용합니다.

2. Oracle Instant Client 설치 (Homebrew 사용)

Oracle DB 연결 시 필수로 필요한 C 라이브러리들을 설치합니다.

brew tap InstantClientTap/instantclient
brew install instantclient-basic
brew install instantclient-sdk

설치 완료 후, 위치를 확인합니다.

brew --prefix instantclient-basic

출력 예시:

/opt/homebrew/Cellar/instantclient-basic/19.8.0.0.0dbru

3. 환경 변수 설정

설치된 Oracle Instant Client를 Python에서 인식시키기 위해 환경 변수 설정이 필요합니다.

# 아래 경로는 brew 설치 경로에 따라 다를 수 있음
export DYLD_LIBRARY_PATH=/opt/homebrew/Cellar/instantclient-basic/19.8.0.0.0dbru
export PATH=$DYLD_LIBRARY_PATH:$PATH

.zshrc에 추가하여 영구 적용:

echo 'export DYLD_LIBRARY_PATH=/opt/homebrew/Cellar/instantclient-basic/19.8.0.0.0dbru' >> ~/.zshrc
echo 'export PATH=$DYLD_LIBRARY_PATH:$PATH' >> ~/.zshrc
source ~/.zshrc

4. 심볼릭 링크 생성

Oracle DB 모듈이 libclntsh.dylib 파일을 찾지 못할 경우가 많기 때문에, 아래와 같이 심볼릭 링크를 생성해줍니다.

cd $DYLD_LIBRARY_PATH
ln -s libclntsh.dylib.19.1 libclntsh.dylib

정상 생성 여부 확인:

ls -l $DYLD_LIBRARY_PATH/libclntsh.dylib*

5. Python 코드에서 Oracle Client 초기화

import oracledb

# Instant Client가 설치된 경로로 지정
oracledb.init_oracle_client(lib_dir="/opt/homebrew/Cellar/instantclient-basic/19.8.0.0.0dbru")

print("Oracle Client is successfully initialized!")

6. Oracle DB 연결 테스트

import oracledb

oracledb.init_oracle_client(lib_dir="/opt/homebrew/Cellar/instantclient-basic/19.8.0.0.0dbru")

connection = oracledb.connect(
    user="your_username",
    password="your_password",
    dsn="your_host:your_port/your_service_name"
)

cursor = connection.cursor()
cursor.execute("SELECT * FROM dual")
result = cursor.fetchone()
print("결과:", result)

cursor.close()
connection.close()

---

💡 만약 발생하는 오류가 있다면?

DPI-1047: Cannot locate a 64-bit Oracle Client library

→ Instant Client가 설치되지 않았거나 환경변수 설정이 잘못된 경우입니다.

libclntsh.dylib not found
→ ln -s로 심볼릭 링크를 생성하지 않았거나 경로가 잘못된 경우입니다.

Oracle DB를 Python에서 사용하려면 일반적인 pip 설치 외에도 C 라이브러리 설치와 환경 설정이 필요합니다.

다소 번거롭지만 위 과정을 차근차근 진행하면 Mac 환경에서도 문제없이 Oracle DB에 연결할 수 있습니다.