Skip to content

자주 묻는 질문 (한국어)

🌐 faq.md의 번역입니다. 영어 원문이 표준이며, CI가 영어 원문과의 구조 일치를 검사합니다.

pycubrid 사용 관련 자주 묻는 질문과 실용적인 답변.

원격 CUBRID 서버에는 어떻게 연결하나요?

connect()에 원격 호스트와 브로커 포트를 직접 사용하세요.

from __future__ import annotations

import pycubrid

conn = pycubrid.connect(
    host="db.example.com",
    port=33000,
    database="production",
    user="app_user",
    password="secret",
    connect_timeout=15.0,
)

Warning

배포 환경이 브로커→CAS 포트 리다이렉션을 사용한다면, 리다이렉트되는 CAS 포트가 방화벽/네트워크 규칙에서 허용되는지 확인하세요.

어떤 Python 버전을 지원하나요?

pycubrid는 Python 3.11–3.15(표준 GIL 빌드)를 지원하며, free-threaded 빌드는 지원하지 않습니다. Python 3.10에서는 pip가 1.9.x 릴리스 버전을 설치합니다.

Note

최신 호환성 표는 지원 매트릭스를 확인하세요.

LOB 데이터는 어떻게 다루나요?

대부분의 애플리케이션에서는 파라미터화 SQL에 str/bytes를 직접 전달하면 됩니다.

cur.execute(
    "INSERT INTO docs (title, content) VALUES (?, ?)",
    ["Guide", "Large CLOB text..."],
)

세밀한 제어가 필요하면 conn.create_lob(...)과 반환되는 Lob 객체를 사용하세요.

Tip

LOB 메타데이터와 수명 주기에 대한 자세한 내용은 예제를 읽어 보세요.

커넥션 풀링은 어떻게 쓰나요?

pycubrid 자체에는 내장 풀이 없습니다. 권장 옵션:

  1. SQLAlchemy 엔진 풀링 (pool_size, max_overflow, pool_pre_ping)
  2. 간단한 스크립트용 가벼운 애플리케이션 수준 큐 기반 풀
from sqlalchemy import create_engine

engine = create_engine(
    "cubrid+pycubrid://dba@localhost:33000/testdb",
    pool_size=5,
    pool_pre_ping=True,
)
어떤 문자 인코딩을 지원하나요?

기본은 UTF-8입니다. 다른 문자셋으로 만든 데이터베이스라면 charset으로 지정하세요. 예: pycubrid.connect(database="kodb", charset="euckr") (pycubrid.aio.connect도 동일). CUBRID 이름 utf8, euckr, iso88591와 ASCII 투명한 Python 코덱을 받으며, UTF-16/32, Shift_JIS, Big5, GBK, CP949처럼 멀티바이트 문자 안에 ASCII 바이트를 만들 수 있는 코덱은 거부합니다.

Note

브로커는 문자셋을 변환하지 않습니다. 클라이언트 코덱은 데이터베이스 문자셋과 같아야 하며, 모든 값은 해당 컬럼의 문자셋으로 도착합니다. EUC-KR 데이터베이스 안의 CHARSET utf8 컬럼은 charset="euckr"에서 DataError를 발생시키므로 SQL에서 CAST(col AS VARCHAR(n) CHARSET euckr)로 변환하세요. JSON은 항상 UTF-8입니다. 문자 인코딩을 참고하세요.

에러는 어떻게 제대로 처리하나요?

구체적인 DB-API 예외(IntegrityError, ProgrammingError, OperationalError)를 먼저 잡고, 그다음 Error로 폴백하세요.

import pycubrid

try:
    cur.execute("INSERT INTO users (email) VALUES (?)", ["duplicate@example.com"])
    conn.commit()
except pycubrid.IntegrityError:
    conn.rollback()
    raise
except pycubrid.Error:
    conn.rollback()
    raise

분류별 에러 진단은 문제 해결을 참고하세요.