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/.
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 |
| Build a production API | templates/api-service-fastapi/ |
15 min |
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/docsThe 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)
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.
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)
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) |
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/.
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 |
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
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 the database:
docker compose up -dcubrid-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
├── 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
- pycubrid — Pure Python DB-API 2.0 driver for CUBRID
- sqlalchemy-cubrid — SQLAlchemy 2.0/2.1 dialect for CUBRID
- CUBRID — The CUBRID database
See ROADMAP.md for planned additions.
For the ecosystem-wide view, see the CUBRID Labs Ecosystem Roadmap.
PRs welcome! Each example should be self-contained and independently runnable. See CONTRIBUTING.md.
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.
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.