[프로젝트] PC 자산관리 프로그램 개발기 #4 : FastAPI와 오라클 11g 연동! (cx_Oracle 말고 python-oracledb 쓰세요)

파이썬 오라클 11g 연동 개발기

1. 서론: 레거시(Legacy) 시스템과의 전쟁

지난 포스팅에서 우리는 파이썬 가상환경(venv)을 구축하고 FastAPI를 설치해 'Hello World'를 띄우는 데 성공했습니다. 이제 연습 게임은 끝났습니다. 진짜 게임, 바로 사내 시스템의 심장인 오라클 데이터베이스(Oracle Database)와 웹 서버를 연결하는 작업을 시작할 차례입니다.

하지만 전산 실무자라면 여기서 한 가지 큰 벽에 부딪히게 됩니다.

"우리 회사 DB는 10년 넘은 오라클 11g인데, 요즘 나온 파이썬 라이브러리랑 붙을까?"

결론부터 말씀드리면 "그냥은 안 붙지만, 방법이 있다"입니다. 오늘은 더 이상 업데이트되지 않는 구형 라이브러리인 cx_Oracle 대신, 오라클의 새로운 표준인 python-oracledb를 사용하여 구형 11g DB와 완벽하게 연동하는 방법을 정리해 드립니다.

---

2. 왜 cx_Oracle이 아니라 python-oracledb인가?

오랫동안 파이썬에서 오라클을 연결할 때 cx_Oracle은 국룰과도 같았습니다. 하지만 2022년, 오라클은 공식적으로 python-oracledb라는 새로운 라이브러리를 출시하며 세대교체를 선언했습니다.

 

그렇다면 우리 같은 11g 사용자도 굳이 갈아타야 할까요? 네, 그렇습니다.

구분	cx_Oracle (구형)	python-oracledb (신형)	비고
상태	유지보수 중단	공식 표준 (Active)	최신 기능 지원
작동 방식	Thick 모드만 지원	Thin(기본) / Thick 모드	11g는 Thick 필요
클라이언트	Instant Client 필수	선택 사항	가벼워짐
설치 편의성	복잡함 (DLL 에러 빈번)	매우 간편 (pip install)	개발 생산성 향상

 

구형 DB를 쓰더라도 라이브러리는 최신 표준을 따라가는 것이, 향후 유지보수나 비동기(Async) 처리를 위해 훨씬 유리합니다.

---

3. 핵심: 11g를 위한 'Thick Mode' 이해하기

python-oracledb의 가장 큰 장점은 오라클 클라이언트(Instant Client) 설치 없이도 작동하는 'Thin Mode'입니다. 하지만 안타깝게도 Thin Mode는 Oracle 12c (12.1) 이상의 DB만 지원합니다.

 

저희처럼 Oracle 11g (혹은 그 이하) 버전을 사용 중이라면, 'Thick Mode'를 강제로 활성화해 줘야 합니다. 이 과정을 거치지 않으면 연결 시 다음과 같은 에러를 마주하게 됩니다.

• DPY-3010: Connections to this database server version require Oracle Client library...
• ORA-28040: No matching authentication protocol (프로토콜 불일치)

💡 요약: 11g 사용자는 python-oracledb를 설치하되, Instant Client를 다운받아 경로를 지정해 줘야 한다!

---

4. 준비물: Oracle Instant Client 다운로드

먼저 오라클 공식 홈페이지에서 버전에 맞는 Instant Client를 다운로드합니다. 11g DB라도 19c 버전의 클라이언트를 사용하면 호환이 잘 됩니다. (공식적으로 19c 클라이언트는 11.2 버전을 지원합니다.)

 

오라클 Instant Client 다운로드 페이지 캡처 (Windows 64-bit 선택 화면)

 

압축을 푼 폴더(예: C:\oracle\instantclient)의 경로를 잘 기억해 두세요. 예전처럼 윈도우 환경변수(Path)에 등록할 필요는 없습니다. 우리는 파이썬 코드 안에서 직접 경로를 주입할 것이기 때문입니다. 이 방식이 배포할 때 훨씬 깔끔합니다.

C드라이브 밑에 oracle 폴더를 만들고 압축을 푼 탐색기 화면

---

5. 실전 코드: database.py 작성

이제 프로젝트 폴더에 DB 연결을 담당할 database.py 파일을 생성합니다. 먼저 필요한 라이브러리를 가상환경에 설치합니다. (SQLAlchemy 2.0 이상 버전을 권장합니다.)

pip install "sqlalchemy>=2.0" python-oracledb

 

그리고 아래 코드를 작성합니다. 주석 처리된 부분이 11g 연결 및 실무 팁의 핵심입니다.

import sys
import oracledb
from sqlalchemy import create_engine
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

# ==========================================
# [중요] Oracle 11g 사용자를 위한 Thick 모드 설정
# ==========================================
# 11g는 Thin 모드(기본값)를 지원하지 않으므로
# Instant Client 경로를 지정해 Thick 모드로 초기화해야 합니다.
try:
    # 본인이 설치한 인스턴트 클라이언트 경로 입력 (r"경로" 형태 권장)
    oracledb.init_oracle_client(lib_dir=r"C:\oracle\instantclient")
    print("Oracle Client Initialized (Thick Mode)")
except Exception as e:
    print("오라클 클라이언트 초기화 오류:", e)

# ==========================================
# DB 접속 정보 설정 (DSN)
# ==========================================
# [보안 Tip] 실무 배포 시에는 ID/PW를 소스코드에 적지 말고 
# .env 파일(환경변수)로 관리하는 것이 정석입니다. (여기선 학습용으로 명시함)

# [연결 Tip] 11g XE 버전 등 일부 구버전은 service_name 대신 SID를 써야 할 수 있습니다.
# Case 1. Service Name 사용 시 (일반적)
# SQLALCHEMY_DATABASE_URL = "oracle+oracledb://admin:1234@192.168.0.100:1521/?service_name=XE"

# Case 2. SID 사용 시 (접속 에러 시 시도)
SQLALCHEMY_DATABASE_URL = "oracle+oracledb://admin:1234@192.168.0.100:1521/?sid=xe"

# 엔진 생성
engine = create_engine(
    SQLALCHEMY_DATABASE_URL,
    # echo=True : 실행되는 SQL 쿼리를 로그창에 보여줍니다 (개발 시 유용, 운영 시 False)
    echo=True
)

# 세션 생성 (실제 DB와 대화하는 객체)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

# 모델 상속용 Base 클래스
Base = declarative_base()

# 의존성 주입(Dependency Injection)을 위한 함수
def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

---

6. 마무리 및 다음 예고

과거 엑셀로 자산 관리를 할 때는 파일을 열 때마다 "누가 수정 중입니다" 경고창을 봐야 했지만, 이제 우리는 동시 접속이 가능한 강력한 오라클 DB와 연결된 고속도로를 뚫었습니다.

 

특히 구형 시스템(11g) 때문에 cx_Oracle과 python-oracledb 사이에서 고민하던 분들에게 이 'Thick Mode' 설정법이 도움이 되었으면 합니다. 환경변수 설정하느라 재부팅할 필요 없이 코드 몇 줄로 해결되니 얼마나 편합니까?

 

다음 시간에는 이 연결된 DB 세션을 이용해, 실제 자산 테이블(Table)을 파이썬 객체로 정의하는 SQLAlchemy 모델링(Model)과 Pydantic 스키마에 대해 다뤄보겠습니다. 본격적으로 데이터를 조회(SELECT)하고 넣는(INSERT) 작업이 시작됩니다.

 

[함께 보면 좋은 글] 

2025.12.03 - [IT & TECH/개발기록] - [프로젝트] PC 자산관리 프로그램 개발기 #3 : 왜 FastAPI인가? & 파이썬 가상환경 구축 완벽 가이드

[프로젝트] PC 자산관리 프로그램 개발기 #3 : 왜 FastAPI인가? & 파이썬 가상환경 구축 완벽 가이드