Pure Python DB-API 2.0 driver for the CUBRID database — no C extensions, no compilation, PEP 249 compliant database connector.
🇰🇷 한국어 · 🇺🇸 English · 🇨🇳 中文 · 🇮🇳 हिन्दी · 🇩🇪 Deutsch · 🇷🇺 Русский
CUBRID is a high-performance open-source relational database, widely adopted in
Korean public-sector and enterprise applications. The existing C-extension driver
(CUBRIDdb) had build dependencies and platform compatibility issues.
pycubrid solves these problems:
- Pure Python implementation — no C build dependencies, install with
pip installonly - Full PEP 249 (DB-API 2.0) compliance — standard exception hierarchy, type objects, cursor interface
- 471 offline tests with 99%+ code coverage — no database required to run them
- PEP 561 typed package —
py.typedmarker for modern IDE and static analysis support - Direct CUBRID CAS protocol implementation — no additional middleware required
- LOB (CLOB/BLOB) support — handle large text and binary data
- Python 3.10+
- CUBRID database server 10.2+
pip install pycubridimport pycubrid
conn = pycubrid.connect(
host="localhost",
port=33000,
database="testdb",
user="dba",
password="",
)
cur = conn.cursor()
cur.execute("SELECT 1 + 1")
print(cur.fetchone()) # (2,)
cur.close()
conn.close()import pycubrid
with pycubrid.connect(host="localhost", port=33000, database="testdb", user="dba") as conn:
with conn.cursor() as cur:
cur.execute("CREATE TABLE IF NOT EXISTS cookbook_users (id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(100))")
cur.execute("INSERT INTO cookbook_users (name) VALUES (?)", ("Alice",))
conn.commit()
cur.execute("SELECT * FROM cookbook_users")
for row in cur:
print(row)# qmark style (question marks)
cur.execute("SELECT * FROM users WHERE name = ? AND age > ?", ("Alice", 25))
# Batch insert with executemany
data = [("Alice", 30), ("Bob", 25), ("Charlie", 35)]
cur.executemany("INSERT INTO users (name, age) VALUES (?, ?)", data)
conn.commit()sql = "SELECT * FROM users WHERE department = ?"
cur.execute(sql, ("Engineering",))
engineers = cur.fetchall()
cur.execute(sql, ("Marketing",))
marketers = cur.fetchall()| Attribute | Value |
|---|---|
apilevel |
"2.0" |
threadsafety |
1 (connections cannot be shared between threads) |
paramstyle |
"qmark" (positional parameters ?) |
- Full standard exception hierarchy:
Warning,Error,InterfaceError,DatabaseError,OperationalError,IntegrityError,InternalError,ProgrammingError,NotSupportedError - Standard type objects:
STRING,BINARY,NUMBER,DATETIME,ROWID - Standard constructors:
Date(),Time(),Timestamp(),Binary(),DateFromTicks(),TimeFromTicks(),TimestampFromTicks()
- Pure Python — no C extensions, no compilation, works everywhere Python runs
- Complete DB-API 2.0 —
connect(),Cursor,fetchone/many/all,executemany,callproc - Parameterized queries —
cursor.execute(sql, params)with server-sidePREPARE_AND_EXECUTE - Batch operations —
executemany()andexecutemany_batch()for bulk inserts - LOB support —
create_lob(), read/write CLOB and BLOB columns - Schema introspection —
get_schema_info()for tables, columns, indexes, constraints - Auto-commit control —
connection.autocommitproperty for transaction management - Server version detection —
connection.get_server_version()returns version string (e.g.,"11.2.0.0378") - Iterator protocol — iterate over cursor results with
for row in cursor - Context managers —
withstatements for both connections and cursors
The project targets CUBRID 11.x series and is validated in CI against:
- 11.2
- 11.4
pycubrid works as a driver for sqlalchemy-cubrid — the SQLAlchemy 2.0 dialect for CUBRID:
pip install "sqlalchemy-cubrid[pycubrid]"from sqlalchemy import create_engine, text
engine = create_engine("cubrid+pycubrid://dba@localhost:33000/testdb")
with engine.connect() as conn:
result = conn.execute(text("SELECT 1"))
print(result.scalar())All SQLAlchemy features (ORM, Core, Alembic migrations, schema reflection) work transparently with the pycubrid driver.
| Guide | Description |
|---|---|
| Connection | Connection strings, URL format, configuration, connection pool |
| Type Mapping | Full type mapping, CUBRID-specific types, collection types |
| API Reference | Complete API documentation — modules, classes, functions |
| Protocol | CAS wire protocol reference |
| Development | Dev setup, testing, Docker, coverage, CI/CD |
| Examples | Practical usage examples with code |
| Troubleshooting | Connection errors, query problems, LOB handling, debugging |
| Python 3.10 | Python 3.11 | Python 3.12 | Python 3.13 | |
|---|---|---|---|---|
| Offline Tests | ✅ | ✅ | ✅ | ✅ |
| CUBRID 11.4 | ✅ | -- | ✅ | -- |
| CUBRID 11.2 | ✅ | -- | ✅ | -- |
graph TD
app[Application]
pycubrid[pycubrid Connection/Cursor]
cas[CAS Protocol]
server[CUBRID Server]
app --> pycubrid
pycubrid --> cas
cas --> server
graph TD
root[pycubrid/]
init[__init__.py - Public API connect(), types, exceptions, __version__]
connection[connection.py - Connection class connect/commit/rollback/cursor/LOB]
cursor[cursor.py - Cursor class execute/fetch/executemany/callproc/iterator]
types[types.py - DB-API 2.0 type objects and constructors]
exceptions[exceptions.py - PEP 249 exception hierarchy]
constants[constants.py - CAS function codes, data types, protocol constants]
protocol[protocol.py - CAS wire protocol packet classes (18 packet types)]
packet[packet.py - Low-level packet reader/writer]
lob[lob.py - LOB support]
typed[py.typed - PEP 561 marker]
root --> init
root --> connection
root --> cursor
root --> types
root --> exceptions
root --> constants
root --> protocol
root --> packet
root --> lob
root --> typed
import pycubrid
conn = pycubrid.connect(host="localhost", port=33000, database="testdb", user="dba")pip install pycubrid — no C extensions or build tools required.
Question mark (qmark) style: cursor.execute("SELECT * FROM users WHERE id = ?", (1,))
Yes. Install pip install "sqlalchemy-cubrid[pycubrid]" and use the connection URL cubrid+pycubrid://dba@localhost:33000/testdb.
Python 3.10, 3.11, 3.12, and 3.13.
Yes. Insert strings/bytes directly into CLOB/BLOB columns. For reading, LOB columns return data that can be accessed through the cursor.
pycubrid has threadsafety = 1, meaning connections cannot be shared between threads. Create a separate connection per thread.
CUBRID 10.2, 11.0, 11.2, and 11.4 are tested in CI.
Environment: Intel Core i5-9400F @ 2.90GHz · Linux x86_64 · CUBRID 11.2 · MySQL 8.0 · Docker localhost
Test Parameters: 1000 rows × 5 rounds
| Operation | pycubrid (CUBRID) | PyMySQL (MySQL) | Ratio |
|---|---|---|---|
| insert_sequential | 10.47s | 1.74s | 6.0× |
| select_by_pk | 15.99s | 3.52s | 4.5× |
| select_full_scan | 10.31s | 1.86s | 5.5× |
| update_indexed | 10.70s | 2.19s | 4.9× |
| delete_sequential | 10.75s | 2.10s | 5.1× |
Note: pycubrid is a pure-Python driver; overhead reflects Python-level protocol parsing. A C-extension driver would close the gap.
Full benchmark suite: cubrid-benchmark
- sqlalchemy-cubrid — SQLAlchemy 2.0 dialect for CUBRID
- cubrid-client — Native TypeScript client for CUBRID (CAS protocol)
- drizzle-cubrid — Drizzle ORM dialect for CUBRID
- cubrid-go — Pure Go database/sql driver for CUBRID
- gorm-cubrid — GORM dialect for CUBRID
- cubrid-rs — Native Rust database driver for CUBRID (sync + async, pure Rust)
- sea-orm-cubrid — SeaORM backend for CUBRID
- cubrid-cookbook — Production-ready examples for all CUBRID drivers
- cubrid-benchmark — Multi-language benchmark suite for CUBRID
See ROADMAP.md for this project's direction and next milestones.
For the ecosystem-wide view, see the CUBRID Labs Ecosystem Roadmap and Project Board.
See CONTRIBUTING.md for guidelines and docs/DEVELOPMENT.md for development setup.
Report vulnerabilities via email — see SECURITY.md. Do not open public issues for security concerns.
MIT — see LICENSE.