Skip to content

Frequently Asked Questions

Common pycubrid usage questions with practical answers.

How do I connect to a remote CUBRID server?

Use the remote host and broker port directly in 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

If your deployment uses broker-to-CAS port redirection, ensure network rules allow the redirected CAS port(s).

What Python versions are supported?

pycubrid supports Python 3.11–3.15 (standard GIL builds; free-threaded builds are not supported). On Python 3.10, pip installs the 1.9.x release line.

Note

Check the latest compatibility table in Support Matrix.

How do I handle LOB data?

For most applications, pass str/bytes directly in parameterized SQL.

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

For advanced control, use conn.create_lob(...) and the returned Lob object.

Tip

Read LOB metadata and lifecycle details in Examples.

How do I use connection pooling?

pycubrid itself does not ship a built-in pool. Recommended options:

  1. SQLAlchemy engine pooling (pool_size, max_overflow, pool_pre_ping)
  2. A lightweight application-level queue-based pool for simple scripts
from sqlalchemy import create_engine

engine = create_engine(
    "cubrid+pycubrid://dba@localhost:33000/testdb",
    pool_size=5,
    pool_pre_ping=True,
)
What character encodings are supported?

UTF-8 by default. For a database created with another charset, pass it as charset, for example pycubrid.connect(database="kodb", charset="euckr") (also pycubrid.aio.connect). CUBRID names utf8, euckr and iso88591 and ASCII-transparent Python codecs are accepted; UTF-16/32, Shift_JIS, Big5, GBK, CP949 and other codecs that can emit ASCII bytes inside a multibyte character are rejected.

Note

The broker does no charset conversion: the client codec must match the database charset, and every value arrives in its column's charset. A CHARSET utf8 column inside an EUC-KR database raises DataError under charset="euckr"; convert it in SQL with CAST(col AS VARCHAR(n) CHARSET euckr). JSON is always UTF-8. See Character Encoding.

How do I handle errors properly?

Catch specific DB-API exceptions first (IntegrityError, ProgrammingError, OperationalError) and fall back to 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

See Troubleshooting for categorized error diagnosis.