Metadata-Version: 2.4
Name: pyoceanbase
Version: 1.0.1
Summary: Pure Python OceanBase Driver (PyMySQL fork with Oracle tenant support)
Author-email: Inada Naoki <songofacandy@gmail.com>, Yutaka Matsubara <yutaka.matsubara@gmail.com>
License-Expression: MIT
Project-URL: Project, https://github.com/oceanbase-driver/python-oceanbase-driver
Project-URL: Changelog, https://github.com/oceanbase-driver/python-oceanbase-driver/blob/master/CHANGELOG.md
Keywords: MySQL
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Intended Audience :: Developers
Classifier: Topic :: Database
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: rsa
Requires-Dist: cryptography>=46.0.7; extra == "rsa"
Provides-Extra: ed25519
Requires-Dist: PyNaCl>=1.6.2; extra == "ed25519"
Dynamic: license-file

# python-oceanbase-driver

Python 的 OceanBase 驱动，基于 `PyMySQL 1.2.0`，纯 Python，用法与 PyMySQL 完全一致，
区别是默认置上握手包 capability bit27，可直连 OceanBase **Oracle 租户**。
未打补丁的 MySQL 协议驱动连 Oracle 租户会被服务端拒绝：

```text
pyoceanbase.err.NotSupportedError: (1235, 'Oracle tenant for current client driver is not supported')
```

原理：OceanBase 登录时检查该位（`OB_CLIENT_SUPPORT_ORACLE_MODE`，
与 MySQL 8.0 的 `CLIENT_QUERY_ATTRIBUTES` 同一位），mysql 8.0 客户端默认置位，
PyMySQL 默认没置。本驱动默认置上，对 MySQL / MariaDB / OB MySQL 租户无副作用。

## 安装

```shell
pip install pyoceanbase
```

注意：顶层包名为 `pyoceanbase`，可与上游 PyMySQL 共存于同一环境，按需选用。

## 用法

```python
import pyoceanbase

conn = pyoceanbase.connect(
    host="HOST",
    port=9090,
    user="USER@TENANT#CLUSTER",
    password="PASSWORD",
    database="DBNAME",
)
with conn.cursor() as cur:
    cur.execute("SELECT USER FROM DUAL")
    print(cur.fetchone())
conn.close()
```

## 注意事项

1. 业务 SQL 须用 Oracle 方言（如 `FROM DUAL`、`SYSDATE`）。
2. 默认 `autocommit=False`，写入后记得 `conn.commit()`（标准 PyMySQL 行为）。
3. 数字类型默认返回 `Decimal`（标准 PyMySQL 行为），可用 `conv` 覆盖。
4. DSN 参数等细节见上游文档：https://github.com/PyMySQL/PyMySQL

## 协议

MIT，与上游一致。
