Oracle DB와 SQLAlchemy: 세미콜론 문제와 ORA-00933 에러

개요

Python에서 SQLAlchemy를 통해 Oracle Database를 사용하는 개발자들은 종종 ORA-00933: SQL command not properly ended 에러를 마주하게 된다. 이 에러의 주요 원인 중 하나는 SQL 문 끝에 붙은 세미콜론이다. 대부분의 데이터베이스 시스템에서는 세미콜론이 문제를 일으키지 않지만, Oracle의 프로그래밍 인터페이스는 이를 받아들이지 않는다. 본 글에서는 이러한 문제가 발생하는 근본 원인과 SQLAlchemy를 사용할 때 주의해야 할 점들을 살펴본다.

설명

세미콜론의 역할

SQL에서 세미콜론은 전통적으로 문장 종결자(statement terminator)로 사용되어 왔다. SQL*Plus나 SQL Developer 같은 명령줄 도구에서는 세미콜론이 현재 입력한 SQL 문이 완료되었음을 알리는 신호로 작동한다. 이러한 도구들은 여러 줄에 걸친 SQL 문을 입력받을 수 있기 때문에, 사용자가 입력을 완료했음을 알리는 명시적인 구분자가 필요하다.

그러나 cx_Oracle(현재는 python-oracledb로 발전)과 같은 프로그래밍 API를 통해 SQL을 실행할 때는 상황이 다르다. 프로그래밍 인터페이스에서는 각 execute() 호출이 단일 SQL 문을 전달한다는 것이 명확하므로, 세미콜론이 필요하지 않다. 오히려 세미콜론을 포함하면 Oracle의 SQL 파서는 이를 빈 두 번째 명령의 시작으로 해석하여 에러를 발생시킨다.

SQLAlchemy에서의 문제

SQLAlchemy는 데이터베이스 독립적인 추상화 계층을 제공하는 Python ORM이다. SQLAlchemy는 다양한 데이터베이스 시스템(PostgreSQL, MySQL, SQLite 등)을 지원하며, 이들 대부분은 SQL 문 끝의 세미콜론을 허용하거나 무시한다. 이로 인해 개발자들은 자연스럽게 세미콜론을 SQL 문에 포함시키는 습관을 갖게 되는데, 이것이 Oracle에서는 문제가 된다.

더욱이 LangChain의 SQLDatabaseChain과 같은 일부 라이브러리는 생성된 SQL 문에 자동으로 세미콜론을 추가하는 경우가 있다. Oracle 데이터베이스와 함께 사용할 때 이러한 동작은 즉각적인 에러를 발생시킨다.

ORA-00933 에러의 발생 메커니즘

Oracle의 SQL 파서는 프로그래밍 인터페이스를 통해 전달된 SQL 문을 받으면, 해당 문이 완전하고 적절히 종료되었는지 검증한다. 세미콜론이 포함된 경우:

1. Oracle은 세미콜론을 문장 구분자로 해석
2. 세미콜론 이후의 내용(비어있음)을 새로운 SQL 문으로 간주
3. 빈 SQL 문 또는 불완전한 구문으로 판단하여 ORA-00933 에러 발생

이는 SQL*Plus와 프로그래밍 API 간의 동작 차이에서 비롯된 일관성 없는 행동처럼 보이지만, 실제로는 각각의 컨텍스트에 맞는 설계 결정이다.

특징

Oracle SQL 실행 방식의 특징

1. 컨텍스트 의존적 처리: Oracle은 SQL 실행 컨텍스트(명령줄 도구 vs 프로그래밍 API)에 따라 세미콜론을 다르게 처리한다.
2. PL/SQL과의 구분: SQL 문과 달리 PL/SQL 블록은 세미콜론을 필수로 요구한다. 이는 PL/SQL 블록 내부에서 여러 SQL 문을 포함할 수 있기 때문이다.
3. 엄격한 구문 검증: Oracle의 SQL 파서는 다른 데이터베이스 시스템에 비해 구문 검증이 엄격한 편이다.

다른 데이터베이스와의 차이점

• PostgreSQL/MySQL/SQLite: 프로그래밍 API를 통한 실행 시에도 세미콜론을 허용하거나 자동으로 제거
• SQL Server: ODBC 드라이버에 따라 세미콜론 처리가 다를 수 있으나, 대체로 관대함
• Oracle: 프로그래밍 API에서 세미콜론을 엄격히 거부

예제

문제가 발생하는 경우

cx_Oracle 직접 사용:

import cx_Oracle

# 연결 설정
connection = cx_Oracle.connect('username', 'password', 'localhost:1521/ORCL')
cursor = connection.cursor()

# 잘못된 예 - 세미콜론으로 인해 에러 발생
try:
    cursor.execute('SELECT * FROM employees;')
except cx_Oracle.DatabaseError as e:
    print(f"에러: {e}")
    # 출력: ORA-00933: SQL command not properly ended

SQLAlchemy 사용:

from sqlalchemy import create_engine, text

# Oracle 연결
engine = create_engine('oracle+cx_oracle://user:pass@localhost:1521/ORCL')

# 잘못된 예
with engine.connect() as conn:
    try:
        result = conn.execute(text("SELECT COUNT(*) FROM employees;"))
    except Exception as e:
        print(f"에러: {e}")
        # sqlalchemy.exc.DatabaseError: (cx_Oracle.DatabaseError) 
        # ORA-00933: SQL command not properly ended

LangChain SQLDatabaseChain의 경우:

from langchain import OpenAI, SQLDatabase, SQLDatabaseChain

# Oracle 데이터베이스 연결
db = SQLDatabase.from_uri("oracle://user:pass@localhost:1521/ORCL")
llm = OpenAI(temperature=0)

# SQLDatabaseChain이 자동으로 세미콜론을 추가하여 문제 발생
db_chain = SQLDatabaseChain(llm=llm, database=db, verbose=True)

# 실행 시 ORA-00933 에러 발생 가능
result = db_chain.run("How many employees are there?")

올바른 사용 방법

cx_Oracle 직접 사용:

import cx_Oracle

connection = cx_Oracle.connect('username', 'password', 'localhost:1521/ORCL')
cursor = connection.cursor()

# 올바른 예 - 세미콜론 제거
cursor.execute('SELECT * FROM employees')
rows = cursor.fetchall()

for row in rows:
    print(row)

cursor.close()
connection.close()

SQLAlchemy 사용:

from sqlalchemy import create_engine, text

engine = create_engine('oracle+cx_oracle://user:pass@localhost:1521/ORCL')

# 올바른 예 - 세미콜론 없이 실행
with engine.connect() as conn:
    result = conn.execute(text("SELECT COUNT(*) FROM employees"))
    count = result.scalar()
    print(f"직원 수: {count}")

SQLAlchemy ORM 사용:

from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

Base = declarative_base()

class Employee(Base):
    __tablename__ = 'employees'

    id = Column(Integer, primary_key=True)
    name = Column(String(100))
    department = Column(String(50))

engine = create_engine('oracle+cx_oracle://user:pass@localhost:1521/ORCL')
Base.metadata.create_all(engine)

Session = sessionmaker(bind=engine)
session = Session()

# ORM을 통한 쿼리는 내부적으로 세미콜론 없이 처리됨
employees = session.query(Employee).filter(Employee.department == 'IT').all()

for emp in employees:
    print(f"{emp.name} - {emp.department}")

session.close()

동적 SQL 처리:

from sqlalchemy import create_engine, text

def execute_safe_query(engine, query):
    """Oracle에 안전하게 쿼리를 실행하는 함수"""
    # 쿼리 끝의 세미콜론 제거
    clean_query = query.rstrip(';').strip()

    with engine.connect() as conn:
        result = conn.execute(text(clean_query))
        return result.fetchall()

engine = create_engine('oracle+cx_oracle://user:pass@localhost:1521/ORCL')

# 세미콜론이 있든 없든 안전하게 처리
query1 = "SELECT * FROM employees WHERE department = 'IT';"
query2 = "SELECT * FROM departments"

results1 = execute_safe_query(engine, query1)
results2 = execute_safe_query(engine, query2)

결론

Oracle Database를 SQLAlchemy나 cx_Oracle과 함께 사용할 때 세미콜론 문제는 자주 발생하는 함정이다. 이는 Oracle의 설계 철학과 다른 데이터베이스 시스템 간의 차이에서 비롯된다. 핵심 해결 방법은 다음과 같다:

1. 프로그래밍 API를 통한 SQL 실행 시 세미콜론을 포함하지 않는다: 명령줄 도구에서만 세미콜론이 필요하다.
2. 자동 생성 쿼리 검증: LangChain 같은 라이브러리를 사용할 때는 생성된 SQL 문을 검증하고 필요시 세미콜론을 제거하는 로직을 추가한다.
3. 유틸리티 함수 활용: 쿼리 실행 전 세미콜론을 자동으로 제거하는 래퍼 함수를 만들어 사용한다.
4. 데이터베이스 간 이식성 고려: 여러 데이터베이스 시스템을 지원해야 하는 애플리케이션에서는 세미콜론을 일관되게 제외하는 것이 가장 안전한 접근법이다.
5. PL/SQL은 예외: PL/SQL 블록을 실행할 때는 세미콜론이 필수임을 기억해야 한다.

이러한 이해를 바탕으로 Oracle Database와 Python 애플리케이션 간의 원활한 통합을 구현할 수 있으며, 예상치 못한 ORA-00933 에러를 예방할 수 있다. 특히 다양한 데이터베이스 백엔드를 지원하는 애플리케이션을 개발할 때, Oracle의 이러한 특성을 고려한 방어적 프로그래밍이 중요하다.

참고문헌

1. Stack Overflow - "cx_Oracle.DatabaseError: ORA-00933: SQL command not properly ended", https://stackoverflow.com/questions/47349768/cx-oracle-databaseerror-ora-00933-sql-command-not-properly-ended
2. Oracle Documentation - "ORA-00933: SQL command not properly ended", https://docs.oracle.com/en/error-help/db/ora-00933/
3. GitHub Issue - "extra semicolon with SQLDatabaseChain when used with Oracle", https://github.com/langchain-ai/langchain/issues/6016
4. SQLAlchemy Documentation - "Oracle — SQLAlchemy 2.0 Documentation", https://docs.sqlalchemy.org/en/20/dialects/oracle.html
5. DbVisualizer - "How to Fix Oracle ORA-00933 Error: SQL Command Not Properly Ended", https://www.dbvis.com/thetable/how-to-fix-oracle-ora-00933-error-sql-command-not-properly-ended/
6. Stack Overflow - "Why I do not need semicolon after some of Oracle SQL commands?", https://stackoverflow.com/questions/44730980/why-i-do-not-need-semicolon-after-some-of-oracle-sql-commands
7. GitHub Issue - "[RFC] Supporting Oracle databases as backing stores", https://github.com/mlflow/mlflow/issues/1475