CUBRID Python Cookbook

Production-ready Python examples for CUBRID — from first connection to production API, with migration guides, performance patterns, and common pitfalls.

---

_{▶ Play the recording (animated GIF, 9 seconds). The images on this page are still frames of real recordings of the examples against CUBRID; select one to play it. How they were made: demos/.}

Get Started

New to CUBRID? Start here: your first CUBRID database from Python starts a local practice database, connects from Python, saves and reads rows, and shows commit, rollback and cleanup, before any framework.

Your Goal	Go Here	Time
New to CUBRID	quickstart/first-cubrid/	about 15 min once Docker and Python are installed
Start in 5 minutes	quickstart/5min-fastapi/	about 5 min once Docker is installed
Start with SQLAlchemy	quickstart/5min-sqlalchemy/	about 5 min once Docker and Python are installed
Migrate from Java	migration/java-to-python/	30 min
Move from the CUBRIDdb driver to pycubrid	migration/cubriddb-to-pycubrid/	20 min
Build a production API	templates/api-service-fastapi/	15 min

---

What's Inside

Quickstart

Get a working CUBRID + FastAPI app running with Docker in about 5 minutes, once Docker is installed and its images are downloaded:

git clone https://github.com/cubrid-lab/cubrid-cookbook-python.git
cd cubrid-cookbook-python/quickstart/5min-fastapi
docker compose up -d --build --wait
curl -sS -X POST localhost:8000/items -H 'Content-Type: application/json' -d '{"val": "hello from the quickstart"}'
# {"val":"hello from the quickstart","id":1}
# Open http://localhost:8000/docs

The FastAPI quickstart explains each step, also runs the API on your machine with Uvicorn, and shows how to stop and clean up. The SQLAlchemy quickstart does the same for one Core and ORM script.

_{▶ Play the recording (animated GIF, 12 seconds)}

Migration Guide

Side-by-side Java JDBC → Python migration with real code comparisons. Covers connections, CRUD (DB-API and ORM), transactions, and batch operations.

CUBRID's JDBC driver and Python driver use the same CAS protocol — zero data migration required.

Already on Python with the official CUBRIDdb C-extension driver? The separate CUBRIDdb → pycubrid guide is a driver-to-driver migration: connection arguments, the autocommit default, thread sharing, parameters, error attributes and LOBs, with four runnable pycubrid recipes. It is not a drop-in replacement claim.

Production Templates

Copy-and-customize starting points for real applications:

Template	Use Case
api-service-fastapi/	REST API with FastAPI, SQLAlchemy, Docker (12 recipes)
flask/	Flask + Flask-SQLAlchemy patterns (11 recipes)
django/	Django request handling with a live-tested SQLAlchemy/CUBRID bridge (not native Django ORM)
async-worker/	Background task processing with Celery
batch-etl/	Data pipeline with Pandas
ai-agent/	AI agent state store + MCP toolchain + RAG metadata (5 live-tested scripts)
dashboard/	Interactive dashboard with Streamlit

_{▶ Play the recording (animated GIF, 12 seconds)}

Performance

Benchmark-backed optimization patterns:

Pattern	Impact
Fetch optimization	fetchall() vs fetchone(), column selection and server-side pagination
Bulk insert	batch your COMMITs (~28 → ~1,279 rows/s, pycubrid 1.10.0)
Connection pooling	reuse connections (~5.9 ms vs ~0.8 ms per query, pycubrid 1.10.0)

Pitfalls

7 common anti-patterns that cause real production issues — reserved words, auto-commit differences, connection leaks, and more. See pitfalls/. The reserved-word advice is checked against a live server by pitfalls/reserved-words/.

Fundamentals

Step-by-step reference for every core operation:

Topic	File
Connecting	Basic connection, metadata, context managers (redirect to fundamentals/pycubrid/01_connect.py)
CRUD	INSERT, SELECT, UPDATE, DELETE with parameters (redirect to fundamentals/pycubrid/02_crud.py)
Transactions	Commit, rollback, savepoints, auto-commit (redirect to fundamentals/pycubrid/03_transactions.py)
Parameterized queries	Safe parameter binding (client-side, not server-side prepare)
Error handling	Exception types, retry patterns (05_error_handling.py redirects to fundamentals/pycubrid/05_error_handling.py)
LOB handling	BLOB/CLOB operations (redirect to fundamentals/pycubrid/06_lob.py)
ORM basics	SQLAlchemy engine, core, ORM, relationships
pycubrid driver	22 DB-API recipes: cursors, window functions, recursive CTEs, pagination, timezone/ENUM types
SQLAlchemy recipes	7 recipes including SET/MULTISET/SEQUENCE collection types
Pandas	6 recipes: read_sql, chunked reads, to_sql load patterns
Async I/O	pycubrid.aio and SQLAlchemy async engine
Alembic migrations	Programmatic migration setup with CubridImpl
JSON type CRUD	Native JSON columns, JSON_EXTRACT/UNQUOTE patterns
Isolation levels	3 MVCC levels, no-dirty-read demonstration

---

Framework Map

pycubrid (DB-API 2.0 driver)
├── Direct usage ─── quickstart/first-cubrid (start here), fundamentals/pycubrid (connect, crud, transactions are redirects to it)
├── SQLAlchemy ───── fundamentals/orm-basics, sqlalchemy, quickstart/5min-sqlalchemy
├── FastAPI ──────── quickstart/5min-fastapi, templates/api-service-fastapi
├── Flask ─────────── templates/flask
├── Django ────────── templates/django
├── Celery ──────── templates/async-worker
├── Pandas ──────── fundamentals/pandas, templates/batch-etl
├── AI Agent ─────── templates/ai-agent
└── Streamlit ───── templates/dashboard

Connection

All examples connect to the same CUBRID instance:

Setting	Value
Host	localhost
Port	33000
Database	testdb
User	dba
Password	(empty)

# pycubrid (direct)
import pycubrid

conn = pycubrid.connect(host="localhost", port=33000, database="testdb", user="dba")

# SQLAlchemy
from sqlalchemy import create_engine

engine = create_engine("cubrid+pycubrid://dba@localhost:33000/testdb")

Start, stop and remove the database (the root docker-compose.yml service cubrid):

make docker-up      # start CUBRID (CUBRID_VERSION=11.4 selects another image) and wait until testdb answers
make docker-down    # stop it; the database stays in the Docker volumes
make docker-clean   # DESTRUCTIVE: delete the containers and volumes, database included

Validate a checkout with the standard sequence, make test (offline, results in test-results/test/) and then make verify (the complete live validation, see CONTRIBUTING.md). The focused verify-* lanes are for debugging, print PARTIAL, and are listed under Advanced debugging lanes.

make up and make down remain aliases of make docker-up and make docker-down. The broker listens on 127.0.0.1 only. CUBRID_TEST_PORT publishes it on another host port, but the examples connect to 33000, so leave it unset for them.

Project Structure

cubrid-cookbook-python/
├── quickstart/
│   ├── first-cubrid/          # New to CUBRID: a guided first tutorial with pycubrid
│   ├── 5min-fastapi/          # Docker + FastAPI in 5 minutes
│   └── 5min-sqlalchemy/       # Docker + SQLAlchemy in 5 minutes
├── migration/
│   ├── java-to-python/        # JDBC → pycubrid/SQLAlchemy migration
│   └── cubriddb-to-pycubrid/  # Official CUBRIDdb driver → pycubrid
├── templates/
│   ├── api-service-fastapi/   # Production REST API (12 recipes)
│   ├── flask/                 # Flask + Flask-SQLAlchemy (11 recipes)
│   ├── django/                # Minimal Django app
│   ├── async-worker/          # Celery background tasks
│   ├── batch-etl/             # Pandas data pipeline
│   ├── ai-agent/              # AI agent state + MCP + RAG (5 recipes)
│   └── dashboard/             # Streamlit dashboard (5 recipes)
├── performance/
│   ├── fetch-optimization/    # SELECT tuning (benchmarked)
│   ├── bulk-insert/           # Write batching (benchmarked)
│   └── connection-pooling/    # Pool configuration
├── pitfalls/                  # 7 common anti-patterns
│   └── reserved-words/        # Live-verified reserved-word recipe
├── fundamentals/
│   ├── connect/               # Connection basics
│   ├── crud/                  # CRUD operations
│   ├── transactions/          # Transaction management
│   ├── parameterized-queries/   # Parameterized queries
│   ├── error-handling/        # Exception patterns
│   ├── lob-handling/          # BLOB/CLOB
│   ├── orm-basics/            # SQLAlchemy ORM
│   ├── pycubrid/              # 22 pycubrid DB-API recipes
│   ├── sqlalchemy/            # 7 SQLAlchemy recipes
│   ├── pandas/                # 6 Pandas recipes
│   ├── async/                 # pycubrid.aio + async SQLAlchemy
│   ├── alembic/               # Programmatic Alembic migrations
│   ├── json/                  # Native JSON column CRUD
│   └── isolation-levels/      # 3 MVCC isolation levels
└── docker-compose.yml         # CUBRID 11.2

Related Projects

• pycubrid — Pure Python DB-API 2.0 driver for CUBRID
• sqlalchemy-cubrid — SQLAlchemy 2.0/2.1 dialect for CUBRID
• CUBRID — The CUBRID database

Roadmap

See ROADMAP.md for planned additions.

For the ecosystem-wide view, see the CUBRID Labs Ecosystem Roadmap.

Contributing

PRs welcome! Each example should be self-contained and independently runnable. See CONTRIBUTING.md.

First contribution

New to CUBRID? Pick the repository that matches what you want to work on:

• Documentation and runnable examples: cubrid-cookbook-python
• Pure-Python driver fixes: pycubrid
• SQLAlchemy dialect fixes: sqlalchemy-cubrid

Most first issues can be developed and tested with the offline checks in CONTRIBUTING.md — no Docker or CUBRID server needed. Live CUBRID verification can be completed by CI and maintainers.

Browse open good first issue tasks.

Disclaimer

This project is part of CUBRID Lab, an independent open-source initiative for CUBRID developer tooling, and is not affiliated with, sponsored by, or endorsed by CUBRID Corporation or the official CUBRID project.

License

MIT