Repository navigation
Expand file tree
/
Copy pathllms.txt
More file actions
72 lines (57 loc) · 9.19 KB
/
Copy pathllms.txt
File metadata and controls
72 lines (57 loc) · 9.19 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
# pycubrid
> Pure-Python DB-API 2.0 (PEP 249) driver for the CUBRID database, with an asyncio API (`pycubrid.aio`). No C extensions and no runtime dependencies except `tzdata` on Windows (for time zone names); Python 3.11+, PEP 561 typed.
pycubrid implements the CUBRID CAS (broker) wire protocol in Python. It provides synchronous `pycubrid.connect()` and asynchronous `pycubrid.aio.connect()` connections, declares Python 3.11–3.15 and CUBRID 10.2, 11.0, 11.2 and 11.4 support, and is the recommended driver for sqlalchemy-cubrid. Routine CI validates representative combinations; the full supported matrix is validated for exact release candidates and explicit manual runs, not every main or PR head.
This index and `llms-full.txt` describe the `main` branch (development documentation), which can be ahead of the latest published release; `pycubrid.__version__` on `main` is not proof of publication. A published version's documentation is the `docs/` folder at its tag on the [release list](https://github.com/cubrid-lab/pycubrid/releases).
Key facts:
- PEP 249 globals: `apilevel = "2.0"`, `threadsafety = 1` (threads may share the module, not connections), `paramstyle = "qmark"`
- Connect: `pycubrid.connect(host="localhost", port=33000, database="testdb", user="dba", password="")`; async: `await pycubrid.aio.connect(...)` with the same arguments
- Charset: `connect(..., charset="utf-8")` (sync and async) sets the codec for SQL text, credentials, character values, column names and error text; use the database charset, e.g. `charset="euckr"`. CUBRID names `utf8`/`euckr`/`iso88591` are accepted, codecs that are not ASCII-transparent are rejected, JSON is always UTF-8, and the broker does no conversion, so a mismatch raises `DataError`
- Autocommit is off by default; toggle with `conn.autocommit = True` (async: `await conn.set_autocommit(True)`) or `connect(..., autocommit=True)`
- Parameter binding is driver-side: `cursor.execute(sql, params)` renders `?` placeholders into escaped SQL literals on the client and sends one complete SQL string per execute. Ordinary sync and async cursors send no typed value payload, keep no driver-side statement-handle cache and have no `cursor.prepare()`; server-side plan caching is outside the driver contract
- Binding limits: parameters must be a sequence (mappings are rejected); `None`, `bool`, `int`, `float`, `Decimal`, `str`, `bytes`/`bytearray`, `date`, `time` and `datetime` are supported, plus the typed collections `pycubrid.types.Set`/`Multiset`/`Sequence` (rendered as `SET{...}`/`MULTISET{...}`/`SEQUENCE{...}` with scalar elements, no nesting); anything else raises `ProgrammingError`; a plain list, tuple or set is neither bound nor expanded for `IN (...)`; identifiers (including `callproc` names) are never bound
- The only prepared API is the opt-in, sync-only `pycubrid.compat.native` cursor (`prepare()` / `bind_param()` for INT32, string and NULL values; strings use the connection charset); it is a bounded compatibility subset, not a general DB-API cursor
- `executemany()` sends INSERT/UPDATE/DELETE/MERGE rows as one batch request (other statements fall back to a per-row loop); `executemany_batch(sql_list)` sends a list of SQL strings in one request
- `callproc()` runs `CALL name(?, ...)` and returns the input parameters unchanged; the function's return value is the single row of the result (`fetchone()`), decoded like a column value (`CALL`/`EVALUATE` cells carry their own type, #542); `nextset()` raises `NotSupportedError`
- Exceptions: `Warning`, `Error`, `InterfaceError`, `DatabaseError`, `DataError`, `OperationalError`, `IntegrityError`, `InternalError`, `ProgrammingError`, `NotSupportedError`, with `errno` / `sqlstate` on database errors
- Type objects `STRING`, `BINARY`, `NUMBER`, `DATETIME`, `ROWID` and the PEP 249 constructors (`Date`, `Time`, `Timestamp`, `Binary`, `*FromTicks`)
- Also: LOBs via `conn.create_lob()`, schema introspection via `get_schema_info()`, `get_last_insert_id()`, `ping()`, `get_server_version()`, opt-in TLS (`ssl=True` or an `ssl.SSLContext`), opt-in collection decoding (`decode_collections=True`) and JSON decoding (`json_deserializer=`), context managers and cursor iteration (sync and async)
- Install: `pip install pycubrid`
## Docs
- [Your First CUBRID Connection](https://cubrid-lab.github.io/pycubrid/quickstart/): Lesson 1: prepare a database (your own or a disposable Docker lab) and Python; first-connection problems
- [Run Your First Query](https://cubrid-lab.github.io/pycubrid/first-query/): Lesson 2: connect, execute one statement, read one row, close; the connect timeout default
- [Save a Row and Read It Back](https://cubrid-lab.github.io/pycubrid/save-a-row/): Lesson 3: create a marked tutorial table, insert with `?` parameters, commit, read from a new connection
- [Commit and Roll Back](https://cubrid-lab.github.io/pycubrid/commit-and-rollback/): Lesson 4: uncommitted rows, rollback, autocommit off by default
- [Finish Safely](https://cubrid-lab.github.io/pycubrid/finish-safely/): Lesson 5: owner- and comment-checked cleanup, removing the Docker lab, recovering from interrupted or repeated runs
- [Connection Guide](https://cubrid-lab.github.io/pycubrid/CONNECTION/): `connect()` parameters, TLS, context managers, autocommit, broker handshake, pooling
- [API Reference](https://cubrid-lab.github.io/pycubrid/API_REFERENCE/): `connect()`, `pycubrid.aio`, Connection, Cursor, Lob, exceptions, type objects, the explicit native compatibility subset
- [Parameter Binding](https://cubrid-lab.github.io/pycubrid/PARAMETER_BINDING/): Authoritative driver-side binding contract, type-to-literal mapping, escaping and limits
- [Type Mapping](https://cubrid-lab.github.io/pycubrid/TYPES/): CUBRID types to Python, type objects and constructors, LOB and collection types
- [Examples](https://cubrid-lab.github.io/pycubrid/EXAMPLES/): TLS, CRUD, transactions, parameterized queries, batches, LOBs, schema introspection, stored procedures
## Reference
- [Protocol](https://cubrid-lab.github.io/pycubrid/PROTOCOL/): CAS wire protocol, packets and function codes
- [CAS Concepts](https://cubrid-lab.github.io/pycubrid/CAS_OVERVIEW/): Advanced overview of the Broker, CAS process, CAS wire protocol and CCI; pure-Python versus CUBRIDdb/CCI paths; DB-API calls mapped to function codes
- [Architecture](https://cubrid-lab.github.io/pycubrid/ARCHITECTURE/): Module structure, CAS reconnection, public API boundary
- [Support Matrix](https://cubrid-lab.github.io/pycubrid/SUPPORT_MATRIX/): Python and CUBRID version compatibility and per-feature status
- [Official Driver API Inventory](https://cubrid-lab.github.io/pycubrid/UPSTREAM_COMPATIBILITY/): Differences from the official CUBRIDdb driver and the selected compatibility contract
- [Source — cursor.py](https://github.com/cubrid-lab/pycubrid/blob/main/pycubrid/cursor.py): Cursor — execute, executemany, executemany_batch, fetch, callproc, iterator
- [Source — connection.py](https://github.com/cubrid-lab/pycubrid/blob/main/pycubrid/connection.py): Connection — connect, commit, rollback, cursor, autocommit, LOB, schema info
- [Source — aio](https://github.com/cubrid-lab/pycubrid/tree/main/pycubrid/aio): AsyncConnection and AsyncCursor
## Examples
- [README Quick Start](https://github.com/cubrid-lab/pycubrid/blob/main/README.md#quick-start): Connection, context managers, parameter binding, async
- [Cookbook — pycubrid fundamentals](https://github.com/cubrid-lab/cubrid-cookbook-python/tree/main/fundamentals/pycubrid): Numbered pycubrid examples from connect to cascade delete
- [Cookbook — Parameterized queries](https://github.com/cubrid-lab/cubrid-cookbook-python/tree/main/fundamentals/parameterized-queries): `?` placeholders with driver-side binding
- [Cookbook — Async](https://github.com/cubrid-lab/cubrid-cookbook-python/tree/main/fundamentals/async): `pycubrid.aio` and the SQLAlchemy async engine
- [Cookbook — LOB handling](https://github.com/cubrid-lab/cubrid-cookbook-python/tree/main/fundamentals/lob-handling): BLOB/CLOB with `conn.create_lob()`
## Ecosystem
- [sqlalchemy-cubrid](https://github.com/cubrid-lab/sqlalchemy-cubrid): SQLAlchemy 2.0/2.1 dialect for CUBRID (`cubrid+pycubrid://`, `cubrid+aiopycubrid://`)
- [cubrid-cookbook-python](https://github.com/cubrid-lab/cubrid-cookbook-python): Runnable Python examples for CUBRID
- [CUBRID](https://www.cubrid.org/): The CUBRID database
## Optional
- [Performance](https://cubrid-lab.github.io/pycubrid/PERFORMANCE/): Benchmark methodology, regression checks, profiling, timing hooks
- [Troubleshooting](https://cubrid-lab.github.io/pycubrid/TROUBLESHOOTING/): Common issues and solutions
- [FAQ](https://cubrid-lab.github.io/pycubrid/faq/): Frequently asked questions
- [Development](https://cubrid-lab.github.io/pycubrid/DEVELOPMENT/): Development setup, tests, CI
- [Full documentation in one file](https://cubrid-lab.github.io/pycubrid/llms-full.txt): All user docs concatenated for LLM context
- [Contributing Guide](https://github.com/cubrid-lab/pycubrid/blob/main/CONTRIBUTING.md): Contribution guidelines
- [Changelog](https://github.com/cubrid-lab/pycubrid/blob/main/CHANGELOG.md): Release history
- [CI execution policy](https://github.com/cubrid-lab/pycubrid/blob/main/docs/CI_POLICY.md): minimum PR checks, representative validation and exact manual/release full-matrix evidence.