通用 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 实际执行;没有认证所有依赖版本。