sqlalchemy-cubrid

🌐 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.

SQLAlchemy-2.0–2.1-Dialekt für die CUBRID-Datenbank — Python-ORM, Schema-Reflexion, Alembic-Migrationen und Typzuordnung für SQLAlchemy und CUBRID-spezifische Typen.

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

---

Status: Production/Stable — Stabiler, gewarteter SQLAlchemy-Dialekt für CUBRID 10.2–11.4. Jeder PR wird durch Live-Datenbank-Integrations-CI validiert.

Warum sqlalchemy-cubrid?

CUBRID ist eine leistungsstarke relationale Open-Source-Datenbank, die in koreanischen Behörden und Unternehmensanwendungen weit verbreitet ist. Bislang gab es keinen aktiv gepflegten SQLAlchemy-Dialekt, der die moderne 2.0–2.1-API unterstützt.

sqlalchemy-cubrid schließt diese Lücke:

• Vollständiger SQLAlchemy-2.0–2.1-Dialekt mit Statement-Caching und PEP-561-Typisierung
• Umfangreiche Offline-Testsuite — zum Ausführen ist keine Datenbank erforderlich; CI erzwingt im offline-tests-Job eine Mindestabdeckung von 95 % (--cov-fail-under=95)
• Nebenläufigkeits-Stresstests — QueuePool-basierte synchrone Threads + asyncio.gather-Workloads gegen echtes CUBRID validiert
• SQLAlchemy-2.1-fähiger Compat-Shim — Zugriff auf private APIs in _compat.py gekapselt (bis zur vollständigen SA-2.1-Validierung weiterhin auf <2.2 festgelegt)
• Gegen 4 CUBRID-Versionen (10.2, 11.0, 11.2, 11.4) auf Python 3.11 -- 3.15 getestet
• CUBRID-spezifische DML-Konstrukte: ON DUPLICATE KEY UPDATE, MERGE, REPLACE INTO
• Alembic-Migrationsunterstützung sofort einsatzbereit
• Drei Treiberoptionen — C-Erweiterung (cubrid://), reines Python (cubrid+pycubrid://) oder asynchrones reines Python (cubrid+aiopycubrid://)

Architektur

flowchart TD
    app["Application"] --> sa["SQLAlchemy Core/ORM"]
    sa --> dialect["CubridDialect"]
    dialect --> pycubrid["pycubrid driver"]
    dialect --> cext["CUBRIDdb driver"]
    dialect --> aio["pycubrid.aio async driver"]
    pycubrid --> server["CUBRID Server"]
    cext --> server
    aio --> server

Siehe vollständige Kommunikationsarchitektur für den Weg über Broker, CAS und CCI (auf Englisch).

flowchart TD
    expr["SQL Expression"] --> compiler["CubridSQLCompiler"] --> sql["SQL String"]

Anforderungen

• Python 3.11 oder neuer
• SQLAlchemy 2.0 – 2.1
• CUBRID-Python (C-Erweiterung) oder pycubrid (reines Python)

Installation

pip install sqlalchemy-cubrid

Mit dem Pure-Python-Treiber (synchron und asynchron):

pip install "sqlalchemy-cubrid[pycubrid]"

Das Extra [pycubrid] unterstützt cubrid+pycubrid:// und cubrid+aiopycubrid:// und enthält SQLAlchemys asyncio-Extra (greenlet). Wenn kein kompatibles Wheel verfügbar ist, benötigt die Installation von greenlet möglicherweise Build-Werkzeuge.

Mit Alembic-Unterstützung:

pip install "sqlalchemy-cubrid[alembic]"

Schnellstart

Core (Verbindungsebene)

from sqlalchemy import create_engine, text

engine = create_engine("cubrid://dba:password@localhost:33000/demodb")

with engine.connect() as conn:
    result = conn.execute(text("SELECT 1"))
    print(result.scalar())

ORM (Sitzungsebene)

from sqlalchemy import create_engine, String
from sqlalchemy.orm import DeclarativeBase, Mapped, Session, mapped_column


class Base(DeclarativeBase):
    pass


class User(Base):
    __tablename__ = "users"

    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
    name: Mapped[str] = mapped_column(String(100))
    email: Mapped[str] = mapped_column(String(200), unique=True)


engine = create_engine("cubrid://dba:password@localhost:33000/demodb")
Base.metadata.create_all(engine)

with Session(engine) as session:
    user = User(name="Alice", email="[email protected]")
    session.add(user)
    session.commit()

Async

import asyncio

from sqlalchemy import text
from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine


async def main() -> None:
    # Create the engine inside the running event loop, and always dispose of it.
    engine = create_async_engine("cubrid+aiopycubrid://dba:password@localhost:33000/demodb")
    try:
        async with AsyncSession(engine) as session:
            result = await session.execute(text("SELECT 1 + 1"))
            print(result.scalar())
    finally:
        await engine.dispose()


if __name__ == "__main__":
    asyncio.run(main())

Funktionen

• Typzuordnung für SQLAlchemy-Standardtypen und CUBRID-spezifische Typen — numerische, String-, Datum/Zeit-, Bit-, LOB-, Collection- und JSON-Typen
• SQL-Kompilierung -- SELECT, JOIN, CAST, LIMIT/OFFSET, Unterabfragen, CTEs, Fensterfunktionen
• DML-Erweiterungen -- ON DUPLICATE KEY UPDATE, MERGE, REPLACE INTO, FOR UPDATE, TRUNCATE
• DDL-Unterstützung -- COMMENT, IF NOT EXISTS / IF EXISTS, AUTO_INCREMENT
• Schema-Reflexion -- Tabellen, Views, Spalten, PKs, FKs, Indizes, Unique-Constraints, Kommentare
• Alembic-Migrationen über CubridImpl (wird beim Laden des Dialekts automatisch registriert)
• Drei CUBRID-MVCC-Isolationsstufen — READ COMMITTED (Standard), REPEATABLE READ, SERIALIZABLE
• Async-Unterstützung — create_async_engine("cubrid+aiopycubrid://...") über pycubrid.aio

Bekannte Einschränkungen

• Kein RETURNING — INSERT/UPDATE/DELETE ... RETURNING wird nicht unterstützt; stattdessen cursor.lastrowid oder LAST_INSERT_ID() verwenden
• Keine Sequenzen — CUBRID verwendet ausschließlich AUTO_INCREMENT
• Kein Multi-Schema — ein einzelnes Schema pro Datenbank
• Nicht committetes DDL hält Schemasperren — DDL ist in CUBRID transaktional (ROLLBACK macht es rückgängig; vorzeitig committet es nur das Client-Autocommit, das der Dialekt abschaltet), daher ist ein Alembic-Upgrade standardmäßig eine einzige Transaktion (transactional_ddl = True) und hält die betroffenen Tabellen bis zum Commit gesperrt; für lange Migrationen oder große Tabellen transaction_per_migration=True verwenden
• Nur SQLAlchemy 2.0–2.1 — wegen interner API-Abhängigkeiten auf <2.2 festgelegt (Details)
• Async erfordert pycubrid >= 1.8.0,<2.0 — der Treiber cubrid+aiopycubrid:// benötigt die von diesem Projekt aktuell unterstützte async-fähige pycubrid-Paketlinie

Dokumentation

Leitfaden	Beschreibung
Verbindung	Verbindungszeichenfolgen, URL-Format, Treibereinrichtung, Pool-Tuning
Typzuordnung	Vollständige Typzuordnung, CUBRID-spezifische Typen, Sammlungstypen
DML-Erweiterungen	ON DUPLICATE KEY UPDATE, MERGE, REPLACE INTO, Query-Trace
Isolationsstufen	Die drei CUBRID-MVCC-Isolationsstufen, Konfiguration
Alembic-Migrationen	Einrichtung, Konfiguration, Einschränkungen, Batch-Workarounds
Feature-Unterstützung	Vergleich mit MySQL, PostgreSQL, SQLite
ORM-Kochbuch	Praktische ORM-Beispiele, Beziehungen, Abfragen
Entwicklung	Entwicklungsumgebung, Tests, Docker, Abdeckung, CI/CD
Treiberkompatibilität	CUBRID-Python-Treiberversionen und bekannte Probleme
Fehlerbehebung	Häufige Probleme, Fehlerlösungen, Debugging-Techniken
Asynchrone Verbindung	Einrichtung einer Async-Engine mit cubrid+aiopycubrid://

Kompatibilitätsmatrix

Komponente	Unterstützte Versionen
Python	3.11, 3.12, 3.13, 3.14, 3.15
CUBRID	10.2, 11.0, 11.2, 11.4
SQLAlchemy	2.0–2.1
Alembic	>=1.7.2
pycubrid (sync)	>=1.8.0,<2.0
pycubrid (async)	>=1.8.0,<2.0

FAQ

Wie verbinde ich mich mit SQLAlchemy zu CUBRID?

from sqlalchemy import create_engine
engine = create_engine("cubrid://dba:password@localhost:33000/demodb")

Für den Pure-Python-Treiber (keine nativen CUBRID-Bibliotheken erforderlich): create_engine("cubrid+pycubrid://dba@localhost:33000/demodb"). Die greenlet-Abhängigkeit des [pycubrid]-Extras benötigt möglicherweise Build-Werkzeuge, wenn kein kompatibles Wheel verfügbar ist.

Unterstützt sqlalchemy-cubrid SQLAlchemy 2.0–2.1?

Ja. sqlalchemy-cubrid wurde für SQLAlchemy 2.0–2.1 entwickelt und unterstützt die API im 2.0-Stil einschließlich Session.execute(), typisierter Mapped[]-Spalten und Statement-Caching.

Unterstützt sqlalchemy-cubrid Alembic-Migrationen?

Ja. Installieren Sie mit pip install "sqlalchemy-cubrid[alembic]". Die CUBRID-Migrationsimplementierung registriert sich beim Laden des Dialekts selbst, daher funktioniert die Standard-env.py mit synchronen URLs unverändert; für cubrid+aiopycubrid:// verwenden Sie Alembics async-Vorlage (alembic init -t async). DDL ist in CUBRID transaktional, daher wird ein fehlgeschlagenes alembic upgrade standardmäßig vollständig zurückgerollt, einschließlich der Versionsänderung; für lange Migrationen oder große Tabellen setzen Sie transaction_per_migration=True, um nach jeder Revision zu committen.

Welche Python-Versionen werden unterstützt?

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

Unterstützt CUBRID RETURNING-Klauseln?

Nein. CUBRID unterstützt weder INSERT ... RETURNING noch UPDATE ... RETURNING. Verwenden Sie stattdessen cursor.lastrowid oder SELECT LAST_INSERT_ID().

Wie verwende ich ON DUPLICATE KEY UPDATE mit CUBRID?

from sqlalchemy_cubrid import insert
stmt = insert(users).values(name="Alice").on_duplicate_key_update(name="Alice Updated")

Was ist der Unterschied zwischen cubrid:// und cubrid+pycubrid://?

cubrid:// verwendet den C-Erweiterungstreiber (CUBRIDdb), der eine Kompilierung erfordert. cubrid+pycubrid:// verwendet den Pure-Python-Treiber ohne native CUBRID-Bibliotheken. Das [pycubrid]-Extra enthält greenlet; ohne kompatibles Wheel werden möglicherweise Build-Werkzeuge benötigt. cubrid+aiopycubrid:// verwendet die asynchrone Variante des Pure-Python-Treibers für die Verwendung mit create_async_engine und AsyncSession.

Unterstützt sqlalchemy-cubrid Async?

Ja. Verwenden Sie create_async_engine("cubrid+aiopycubrid://...") mit dem pycubrid-Async-Treiber. Erfordert pycubrid>=1.8.0,<2.0. Beide pycubrid-Dialekte verwenden für pool_pre_ping das native Connection.ping(False) / AsyncConnection.ping(False), und alle Core- und ORM-Funktionen arbeiten mit AsyncSession.

Verwandte Projekte

• pycubrid — Reiner Python-DB-API-2.0-Treiber 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

Siehe CONTRIBUTING.md für Hinweise und docs/DEVELOPMENT.md für die Entwicklungsumgebung.

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.