ConnectorX、Ibis 与数据库驱动读取保真¶
读取角色与版本¶
参考 ConnectorX0.4.6、Ibis12.0.0、SQLAlchemy2.1.4、PyMySQL1.2.3、mysql-connector-python26.7.0。此前 read-only 矩阵使用真实读取 API;5000读取组合不能认证写入、CDC 或 bulk load。先完成共用样例。安装 connectorx pandas ibis-framework[mysql] sqlalchemy pymysql packaging。在 Debian 上,安装 Ibis 的 MySQL extra 可能需要从源码编译 mysqlclient;若构建提示缺少 MySQL/MariaDB 头文件,先安装 pkg-config 和 libmariadb-dev。若 Ibis backend 导入时提示缺少 packaging,请在运行 Ibis 的同一 Python 环境中安装。
原始读取与显式 CAST/HEX profile 分开。UInt64/BIT、精确小数、负 TIME、宽日期范围的默认推断可能与目标库不同;精确表示通过不等于原始类型推断通过。Ibis UInt64 metadata 历史问题见 matrixone#29846。
ConnectorX 精确读取¶
下面将 ID/金额转为文本、二进制转 HEX;SQL NULL 保持 None。示例 URL 来自结构化连接,不在日志中打印。对于远程 TLS 使用所选 ConnectorX 后端确实支持的连接参数并独立验证,这份最小示例用于本机连接。
原始 ConnectorX 查询读取 X'00FF80' 这类非 UTF-8 二进制值时,客户端转换可能抛出 pyo3_runtime.PanicException。原始读取探针应放在独立进程,保存错误与退出状态;下面的 CAST/HEX 查询作为另一条显式适配路径运行。适配路径成功不能覆盖原始路径失败。SQL NULL 与零长度二进制不同:HEX(NULL) 为 NULL,HEX(X'') 为空字符串。
import connectorx as cx
from mo_common import engine
query = ("SELECT CAST(id AS CHAR) AS id_text,CAST(amount AS CHAR) AS amount_text,"
"HEX(payload) AS payload_hex,label,rev FROM lake_demo WHERE id IN (2,9007199254740993) ORDER BY id")
e = engine()
try:
uri = e.url.set(drivername="mysql").render_as_string(hide_password=False)
frame = cx.read_sql(uri,query,return_type="pandas")
rows = frame.to_dict("records")
r = next(x for x in rows if x["id_text"]=="9007199254740993")
assert r["amount_text"]=="12345678901234567890.123456789012345678"
assert r["payload_hex"]=="00FF80" and r["label"]=="中文😀"
finally:
e.dispose()
Ibis backend 与 SQLAlchemy 读取¶
下面使用同一 query(先保存上段 query 定义),分别读两条 API。Ibis 构建表达式不等于执行,必须调用 execute 并核对结果。使用 table 反射时记录 schema() 与实际 SQL,另测 unsigned/BOOL 反射;不要仅靠成功的自定义 SQL 推定反射正确。
import os
import ibis
import pandas as pd
import sqlalchemy as sa
from mo_common import options, engine
kw = options()
ssl_args = {}
if os.environ.get("MO_SSL_CA"):
ssl_args = {"ssl":{"ca":os.environ["MO_SSL_CA"]},"ssl_mode":"VERIFY_IDENTITY"}
backend = ibis.mysql.connect(host=kw["host"],port=kw["port"],user=kw["user"],
password=kw["password"],database=kw["database"],charset="utf8mb4",**ssl_args)
try:
expression = backend.sql(query)
result = expression.execute()
print(result.dtypes)
finally:
backend.disconnect()
e = engine()
try:
with e.connect() as c:
result = pd.read_sql_query(sa.text(query),c,coerce_float=False)
assert result.loc[result.id_text=="9007199254740993","payload_hex"].iloc[0]=="00FF80"
finally:
e.dispose()
若样例包含 NULL payload,请使用 pd.isna(value) 检查,再将非 NULL 的零长度 payload 与 "" 比较。在本次文本查询中,ConnectorX 对 NULL 返回 Python None,pandas 和 Ibis .execute() 返回浮点 NaN。coerce_float=False 可避免把精确小数强制转成浮点数,但不会强制 pandas 用 Python None 表示 SQL NULL。
JDBC、ODBC、SDK 和完整验收¶
沿用 JDBC 教程、ODBC 教程、Python 驱动教程 的真实连接步骤,再运行相同类型样例。JDBC 对精确值使用 getBigDecimal/getBytes,负 TIME 与宽日期另验;ODBC 保存 SQL 类型、column size、decimal digits;MatrixOne SDK 的读取、写入、提交/回滚 API 分方向检查。驱动返回 BOOL metadata 的反射生成 DDL 问题见 #29879。
使用原始源值作 oracle,比较新连接完整回读、NULL/空值、重复行与列顺序。分页需要稳定排序键和一致输入范围;并行 partition 查询不自动获得同一 SQL 快照。读端吞吐要报告连接、分区、实际传输量和内存,不能将缓存/小样例测速当成整个湖仓容量认证。