通用 Python SDK:连接、精确取数与事务实验

本实验使用 matrixone-python-sdk==0.1.16,不是 mo-vector。先按SDK 安装与版本说明固定依赖,使用专用库;表 sdk_basics_lab 必须不存在。脚本只清理自己成功创建的表,不能在业务库运行。

创建库与设置连接

CREATE DATABASE mo_python_sdk_lab;

设置 MO_HOST、MO_PORT、MO_USER、MO_PASSWORD、MO_DATABASE;本实验 MO_DATABASE 为 mo_python_sdk_lab。本地常用端口 6001,密码放在环境配置中。需要同步 TLS 时设置 MO_SSL_CA;本地验收不证明远端 TLS 已通过。

原样运行完整脚本

保存为 sdk_basics.py,用 Python 运行。DDL 在数据事务之外;参数和值通过 SQLAlchemy text 与 Session 绑定,包含单引号、问号、Unicode、零字节及高精度数值。

import os
from datetime import datetime
from decimal import Decimal
from importlib.metadata import version
from matrixone import Client
from sqlalchemy import text

client = Client(sql_log_mode="off", pool_size=2, max_overflow=0)
created = False
options = dict(host=os.getenv("MO_HOST", "127.0.0.1"),
               port=int(os.getenv("MO_PORT", "6001")),
               user=os.environ["MO_USER"], password=os.environ["MO_PASSWORD"],
               database=os.environ["MO_DATABASE"], on_connect=[])
if os.getenv("MO_SSL_CA"):
    options.update(ssl_mode="required", ssl_ca=os.environ["MO_SSL_CA"])
try:
    client.connect(**options)
    print("SDK:", version("matrixone-python-sdk"))
    print("Server:", client.execute("SELECT VERSION()").scalar())
    client.execute("CREATE TABLE sdk_basics_lab(id BIGINT PRIMARY KEY,"
                   "amount DECIMAL(38,18),label VARCHAR(100),raw_value VARBINARY(16),"
                   "event_at DATETIME(6))")
    created = True
    values = dict(id=1, amount=Decimal("12345678901234567890.123456789012345678"),
                  label="quote' question? Unicode😀", raw_value=bytes.fromhex("005CFF"),
                  event_at=datetime(2026, 1, 1, 8, 0, 0, 123456))
    with client.session() as session:
        session.execute(text("INSERT INTO sdk_basics_lab VALUES"
                             "(:id,:amount,:label,:raw_value,:event_at)"), values)
    result = client.execute("SELECT * FROM sdk_basics_lab ORDER BY id")
    assert tuple(result.fetchone()) == tuple(values.values())
    assert result.fetchone() is None
    try:
        with client.session() as session:
            session.execute(text("INSERT INTO sdk_basics_lab(id) VALUES(:id)"), {"id": 2})
            raise RuntimeError("intentional rollback")
    except RuntimeError as error:
        assert str(error) == "intentional rollback"
    assert client.execute("SELECT COUNT(*) FROM sdk_basics_lab").scalar() == 1
    with client.session() as session:
        session.execute(text("UPDATE sdk_basics_lab SET label=:label WHERE id=:id"),
                        {"label": "updated", "id": 1})
        assert session.execute(text("SELECT label FROM sdk_basics_lab WHERE id=:id"),
                               {"id": 1}).scalar() == "updated"
        session.execute(text("DELETE FROM sdk_basics_lab WHERE id=:id"), {"id": 1})
    assert client.execute("SELECT COUNT(*) FROM sdk_basics_lab").scalar() == 0
    print("exact values / rollback / update / delete verified")
finally:
    try:
        if created:
            client.execute("DROP TABLE sdk_basics_lab")
    finally:
        client.disconnect()

成功输出包括 SDK 0.1.16、服务器版本及 exact values / rollback / update / delete verified。故意抛出的错误证明 id=2 的写入被回滚;UPDATE/DELETE 随后单独验证。不是仅检查“没有异常”。

异步读数

以下独立脚本在 SDK 0.1.16、SQLAlchemy 2.0.43、aiomysql 0.3.2、PyMySQL 1.1.1 的组合上通过。不要将 SQLAlchemy 2.0.43 / PyMySQL 1.2.3 组合的 ping 错误写成数据库 SQL 不支持;错误发生在客户端连接检查。此简短脚本没有验证异步 TLS、并发写入或取消/重试语义。

import asyncio
import os
from matrixone import AsyncClient

async def main():
    client = AsyncClient(sql_log_mode="off")
    try:
        await client.connect(host=os.getenv("MO_HOST", "127.0.0.1"),
                             port=int(os.getenv("MO_PORT", "6001")),
                             user=os.environ["MO_USER"], password=os.environ["MO_PASSWORD"],
                             database=os.environ["MO_DATABASE"], on_connect=[])
        result = await client.execute("SELECT VERSION()")
        print(result.scalar())
    finally:
        await client.disconnect()

asyncio.run(main())

Notebook 已有事件循环时执行 await main(),不再嵌套 asyncio.run。异步 ResultSet 的 fetch/scalar 方法读取已完成取数的内存结果,并非每调用一次就 await 网络请求。

继续使用与排查

连接失败先区分库不存在、认证、TLS 与依赖问题;查询失败区分绑定、类型、权限和 SQL。记录发行包和数据库版本,保护错误日志中的 SQL/数据。不要忽略异常后继续将批次标为成功。

多条普通 client.execute 会各自提交;使用一个 Session 才能验证本实验的共同 DML 回滚。Notebook 重跑会拒绝已存在的同名表,不使用 drop_existing_table 或 if_exists=replace 覆盖数据。大结果先聚合/分页,fetchmany 不把完整 ResultSet 变成服务端游标。

SDK 的其他能力与验证边界见SDK 指南。本页代码于 2026-10-14 在 Python 3.12.14 / MO v4.2.5 实际执行;没有认证所有依赖版本。