pycubrid

🌐 Community translation of README.md — English is canonical; this translation may lag behind the original. The translation-sync CI check flags drift, and maintainers open resync PRs.

Reiner Python-DB-API-2.0-Treiber für die CUBRID-Datenbank — ohne C-Erweiterungen, ohne Kompilierung, implementiert die PEP-249-(DB-API-2.0)-Schnittstelle.

🇰🇷 한국어 · 🇺🇸 English · 🇨🇳 中文 · 🇮🇳 हिन्दी · 🇩🇪 Deutsch · 🇷🇺 Русский

---

Status: Stable (1.x). Die öffentliche API folgt Semantic Versioning: Minor-Releases ergänzen abwärtskompatible Funktionen, Patch-Releases liefern ausschließlich Fehlerbehebungen; Breaking Changes sind dem nächsten Major-Release (2.0+) vorbehalten und werden durch einen automatisierten compat-check-CI-Job gegen api-baseline.json abgesichert. Die Entwicklung läuft aktiv weiter — der vollständige Vertrag findet sich in RELEASE_POLICY.md.

Warum pycubrid?

CUBRID ist eine leistungsstarke relationale Open-Source-Datenbank, die in koreanischen Behörden und Unternehmensanwendungen weit verbreitet ist. Der bestehende C-Erweiterungstreiber (CUBRIDdb) hatte Build-Abhängigkeiten und Probleme bei der Plattformkompatibilität.

pycubrid löst diese Probleme:

• Reine Python-Implementierung — keine C-Build-Abhängigkeiten, Installation nur mit pip install
• Implementiert PEP 249 (DB-API 2.0) — Standard-Ausnahmehierarchie, Typobjekte und Cursor-Schnittstelle
• Offline-Regressionstests mit 95 % Mindestabdeckung bei vollständigen Coverage-Läufen — siehe gemessene Abdeckung und CI-Ausführungsrichtlinie; reguläre PR-Smoke-Tests messen keine Abdeckung
• TLS/SSL für synchrone und asynchrone Verbindungen — optional ssl=True (verifizierter Kontext, TLS 1.2 Minimum) oder ein benutzerdefiniertes ssl.SSLContext bei connect() und pycubrid.aio.connect().
• Native asyncio-Unterstützung — Async/Await-API über pycubrid.aio für Anwendungen mit hoher Parallelität
• PEP-561-typisiertes Paket — py.typed-Marker für moderne IDEs und statische Analysewerkzeuge
• Direkte Implementierung des CUBRID-CAS-Protokolls — keine zusätzliche Middleware erforderlich
• LOB-Unterstützung (CLOB/BLOB) — Verarbeitung großer Text- und Binärdaten

Anforderungen

Ende der Unterstützung für Python 3.10: Python 3.10 hat am 2026-10-01 das Ende seiner Upstream-Lebensdauer erreicht (PEP 619). Die Versionslinien 1.8.x und 1.9.x unterstützen Python 3.10; 1.9.0 enthielt die Vorankündigung. Ab 1.10.0 benötigt das Paket Python 3.11 oder neuer, daher installiert pip unter Python 3.10 weiterhin 1.9.x. Aktualisieren Sie Ihren Interpreter, erstellen Sie Ihre virtuelle Umgebung neu und prüfen Sie Ihre Anwendung, bevor Sie aktualisieren.

• Python 3.11 oder neuer
• CUBRID-Datenbankserver 10.2+

Installation

pip install pycubrid

Schnellstart

Grundlegende Verbindung

import 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()

Kontextmanager

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 users (id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(100))")
        cur.execute("INSERT INTO users (name) VALUES (?)", ("Alice",))
        conn.commit()

        cur.execute("SELECT * FROM users")
        for row in cur:
            print(row)

Async

import asyncio
import pycubrid.aio

async def main():
    conn = await pycubrid.aio.connect(
        host="localhost", port=33000, database="testdb", user="dba"
    )
    cur = conn.cursor()
    await cur.execute("SELECT 1 + 1")
    print(await cur.fetchone())  # (2,)
    await cur.close()
    await conn.close()

asyncio.run(main())

Praktische Beispiele

Führen Sie Vorbereitung, drei Beispiele und Bereinigung der Reihe nach in derselben Python-Sitzung in einer Testdatenbank aus. Passen Sie die Verbindungsdaten an Ihren Server an. Die eigene Tabelle darf noch nicht existieren: Die Vorbereitung schlägt dann fehl, statt eine vorhandene Tabelle zu verwenden oder zu löschen. Der manuelle Commit-Modus und der anfängliche DDL-Commit begrenzen den folgenden Rollback auf DML.

Vorbereitung

import pycubrid

conn = pycubrid.connect(host="localhost", port=33000, database="testdb", user="dba")
conn.autocommit = False
cur = conn.cursor()
cur.execute("CREATE TABLE pycubrid_quickstart_327 (id INT PRIMARY KEY, name VARCHAR(100))")
conn.commit()

Grundlegendes CRUD

cur.execute("INSERT INTO pycubrid_quickstart_327 (id, name) VALUES (?, ?)", (1, "Alice"))
cur.execute("SELECT name FROM pycubrid_quickstart_327 WHERE id = ?", (1,))
print(cur.fetchone())  # ('Alice',)
cur.execute("UPDATE pycubrid_quickstart_327 SET name = ? WHERE id = ?", ("Alicia", 1))
cur.execute("SELECT name FROM pycubrid_quickstart_327 WHERE id = ?", (1,))
print(cur.fetchone())  # ('Alicia',)
cur.execute("DELETE FROM pycubrid_quickstart_327 WHERE id = ?", (1,))
conn.commit()

Transaktionen: Commit und Rollback

cur.execute("INSERT INTO pycubrid_quickstart_327 (id, name) VALUES (?, ?)", (2, "Bob"))
conn.commit()
cur.execute("UPDATE pycubrid_quickstart_327 SET name = ? WHERE id = ?", ("Temporary", 2))
conn.rollback()
cur.execute("SELECT name FROM pycubrid_quickstart_327 WHERE id = ?", (2,))
print(cur.fetchone())  # ('Bob',)
conn.rollback()

Fehlerbehandlung

from pycubrid.exceptions import ProgrammingError

try:
    cur.execute("SELECT missing_column FROM pycubrid_quickstart_327 WHERE id = ?", (2,))
except ProgrammingError as exc:
    conn.rollback()
    print(f"Query failed: {exc}")

Bereinigung

Führen Sie nach erfolgreicher Vorbereitung die Bereinigung auch aus, wenn ein Beispiel fehlschlägt; sie löscht nur die oben erstellte Tabelle. Weitere Beispiele: EXAMPLES.md.

conn.rollback()
cur.execute("DROP TABLE pycubrid_quickstart_327")
conn.commit()
cur.close()
conn.close()

PEP-249-Konformität

Attribut	Wert
apilevel	"2.0"
threadsafety	1 (Verbindungen dürfen nicht zwischen Threads geteilt werden)
paramstyle	"qmark" (Positionsparameter ?)

• Vollständige Standard-Ausnahmehierarchie: Warning, Error, InterfaceError, DatabaseError, OperationalError, IntegrityError, InternalError, ProgrammingError, NotSupportedError
• Standard-Typobjekte: STRING, BINARY, NUMBER, DATETIME, ROWID
• Standard-Konstruktoren: Date(), Time(), Timestamp(), Binary(), DateFromTicks(), TimeFromTicks(), TimestampFromTicks()

Funktionen

• Reines Python — keine C-Erweiterungen, keine Kompilierung, läuft überall dort, wo Python läuft
• Vollständiges DB-API 2.0 — connect(), Cursor, fetchone/many/all, executemany, callproc
• Parametrisierte Abfragen — cursor.execute(sql, params) mit treiberseitiger Parameterbindung (?-Platzhalter werden lokal maskiert und eingesetzt)
• Batch-Operationen — executemany() und executemany_batch() für Masseneinfügungen
• LOB-Unterstützung — create_lob(), Lesen/Schreiben von CLOB- und BLOB-Spalten
• Schema-Introspektion — get_schema_info() für Tabellen, Spalten, Indizes und Constraints
• Auto-Commit-Steuerung — Eigenschaft connection.autocommit für das Transaktionsmanagement
• Serverversionserkennung — connection.get_server_version() liefert einen Versionsstring (z. B. "11.2.0.0378")
• Iterator-Protokoll — Cursor-Ergebnisse mit for row in cursor durchlaufen
• Kontextmanager — with-Anweisungen für Verbindungen und Cursor
• Async-Unterstützung — pycubrid.aio.connect() mit AsyncConnection und AsyncCursor für asyncio-Event-Loops

Unterstützte CUBRID-Versionen

Das Projekt richtet sich an CUBRID 10.x und 11.x und wird in CI gegen folgende Versionen validiert:

• 10.2
• 11.0
• 11.2
• 11.4

SQLAlchemy-Integration

pycubrid funktioniert als Treiber für sqlalchemy-cubrid — den SQLAlchemy-2.0-Dialekt für 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())

SQLAlchemy-Funktionen (ORM, Core, Alembic-Migrationen, Schema-Reflexion) sind über den pycubrid-Treiber verfügbar, wenn er mit sqlalchemy-cubrid verwendet wird.

Dokumentation

Leitfaden	Beschreibung
Verbindung	Verbindungszeichenfolgen, URL-Format, Konfiguration
Typzuordnung	Vollständige Typzuordnung, CUBRID-spezifische Typen, Sammlungstypen
API-Referenz	Vollständige API-Dokumentation — Module, Klassen, Funktionen
Protokoll	Referenz zum CAS-Wire-Protokoll
Entwicklung	Entwicklungsumgebung, Tests, Docker, Abdeckung, CI/CD
Beispiele	Praktische Anwendungsbeispiele mit Code
Fehlerbehebung	Verbindungsfehler, Abfrageprobleme, LOB-Behandlung, Debugging

Kompatibilität

Unterstützt: Python 3.11–3.15 und CUBRID 10.2, 11.0, 11.2, 11.4. Gewöhnliche PRs verwenden einen Offline-Smoke-Lauf unter Ubuntu/Python 3.12; Änderungen mit hohem Risiko fügen Python 3.14/CUBRID 11.4 hinzu. Die Validierung auf main und die wöchentliche Validierung bei Änderungen führen zusätzlich Python 3.11/CUBRID 10.2 live sowie die vollständige Offline-Suite unter Python 3.11 und 3.15 aus. Die vollständige 5 × 4-Live-Matrix läuft bei ausdrücklichem Start und bei jedem Release. Siehe CI-Ausführungsrichtlinie und Support-Matrix.

Architektur

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 (20 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
    root --> aio
    aio["aio/ - AsyncConnection, AsyncCursor, async connect()"]

FAQ

Wie verbinde ich mich mit Python zu CUBRID?

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

Wie installiere ich pycubrid?

pip install pycubrid — keine C-Erweiterungen oder Build-Werkzeuge erforderlich.

Welchen Parameterstil verwendet pycubrid?

Fragezeichenstil (qmark): cursor.execute("SELECT * FROM users WHERE id = ?", (1,))

Funktioniert pycubrid mit SQLAlchemy?

Ja. Installieren Sie pip install "sqlalchemy-cubrid[pycubrid]" und verwenden Sie die Verbindungs-URL cubrid+pycubrid://dba@localhost:33000/testdb.

Welche Python-Versionen werden unterstützt?

Python 3.11, 3.12, 3.13, 3.14 und 3.15 (Standard-Builds mit GIL).

Unterstützt pycubrid LOBs (CLOB/BLOB)?

Ja. Zeichenketten/Bytes können direkt in CLOB-/BLOB-Spalten eingefügt werden. Beim Lesen geben LOB-Spalten Daten zurück, auf die über den Cursor zugegriffen werden kann.

Ist pycubrid threadsicher?

pycubrid hat threadsafety = 1; das bedeutet, dass Verbindungen nicht zwischen Threads geteilt werden können. Erstellen Sie pro Thread eine eigene Verbindung.

Welche CUBRID-Versionen werden unterstützt?

CUBRID 10.2, 11.0, 11.2 und 11.4 werden in CI getestet.

Unterstützt pycubrid async/await?

Ja. Verwenden Sie pycubrid.aio.connect() für native asyncio-Unterstützung. Die Async-Oberfläche ist der Sync-API ähnlich: Mit await conn.ping(reconnect=...) steht derselbe native CHECK_CAS-Health-Check wie bei Connection.ping() zur Verfügung, create_lob() bleibt weiterhin nur synchron verfügbar, und Änderungen am Auto-Commit erfolgen mit await conn.set_autocommit(...) statt über einen Property-Setter.

Verwandte Projekte

• sqlalchemy-cubrid — SQLAlchemy-2.0-Dialekt für CUBRID
• cubrid-cookbook-python — Produktionsreife Python-Beispiele für CUBRID

Roadmap

Siehe ROADMAP.md für die Ausrichtung des Projekts und die nächsten Meilensteine.

Für die Ökosystem-Perspektive siehe die CUBRID Labs Ecosystem Roadmap.

Mitwirken

Hinweise finden Sie in CONTRIBUTING.md, die Entwicklungsumgebung in docs/DEVELOPMENT.md.

Sicherheit

Melden Sie Schwachstellen vertraulich über GitHubs Private Vulnerability Reporting (alternativ per E-Mail) — siehe SECURITY.md. Erstellen Sie keine öffentlichen Issues für Sicherheitsprobleme.

Lizenz

MIT — siehe LICENSE.