使用 ODBC 连接 MatrixOne¶

MatrixOne 提供基于 MySQL Connector/ODBC 9.7.0 的实验性 ODBC 驱动，用于将 ODBC 应用和 Power BI 等 BI 工具连接到 MatrixOne。本文介绍安装方式、DSN 与连接串参数、默认端口 6001、诊断方法以及当前的预览版限制。

概述¶

MatrixOne ODBC 是基于 MySQL Connector/ODBC 9.7.0 的预览版实验性分支。它保留 MySQL 客户端协议，并注册两个公开驱动名：

MatrixOne ODBC 9.7 Unicode Driver（myodbc9w）
MatrixOne ODBC 9.7 ANSI Driver（myodbc9a）

当省略 PORT 时，驱动连接到 MatrixOne 的 MySQL 兼容监听端口 6001。驱动通过 SQL_DBMS_NAME 上报 MatrixOne。在 v9.7.0-mo.3 中，只有原生认证错误 1044 和 1045 会映射为 ODBC SQLSTATE 28000；不能据此认为所有 MatrixOne 认证失败都会得到该 SQLSTATE。

兼容性行为¶

针对 MatrixOne，驱动还会应用以下目录和 SQL 行为：

MatrixOne 的 BOOL 在目录和结果描述符中统一上报为 ODBC SQL_BIT，普通 TINYINT 仍保持 SQL_TINYINT。
SQLColumns 不会暴露 MatrixOne 的物理辅助列 __mo_fake_pk_col 和 __mo_cpkey_col。
ODBC 标量函数 escape（如 {fn function(...)}）会在发送到 MatrixOne 前重写为普通函数调用。

开始前准备¶

已完成安装并启动 MatrixOne。
在 Windows x64 上需要 Visual C++ 2022 x64 运行库，MSI 安装程序会检查该运行库。

语法结构¶

DSN-less ODBC 连接串使用分号分隔的 keyword=value 键值对：

DRIVER={MatrixOne ODBC 9.7 Unicode Driver};SERVER=host;PORT=6001;DATABASE=db;UID=user;PWD=password;SSLMODE=DISABLED

你也可以注册 DSN 后按名称连接。在 Windows 上可以使用 64 位 ODBC 数据源管理器或 Add-OdbcDsn cmdlet。

参数说明¶

参数	是否必填	说明
`DRIVER`	是	已注册的驱动名：`MatrixOne ODBC 9.7 Unicode Driver` 或 `MatrixOne ODBC 9.7 ANSI Driver`。
`SERVER`	是	MatrixOne 主机名或 IP 地址。
`PORT`	否	MatrixOne 监听端口，省略时默认为 `6001`。
`DATABASE`	否	连接后打开的数据库。
`UID`	否	用户名。
`PWD`	否	密码。
`SSLMODE`	否	TLS 模式。MatrixOne 默认本地部署使用 `DISABLED`；需要优先使用 TLS 时使用 `PREFERRED`。

示例¶

使用默认端口 6001 直接通过连接串连接：

DRIVER={MatrixOne ODBC 9.7 Unicode Driver};SERVER=127.0.0.1;DATABASE=test;UID=root;PWD=111;SSLMODE=DISABLED

在 Windows 上创建名为 MatrixOne 的 64 位系统 DSN：

Add-OdbcDsn -Name 'MatrixOne' -DriverName 'MatrixOne ODBC 9.7 Unicode Driver' -DsnType System -Platform '64-bit' -SetPropertyValue @("SERVER=127.0.0.1", "PORT=6001")

安装¶

Windows x64¶

从 MatrixOne ODBC 的 GitHub Releases 下载 Windows x64 MSI 或便携 ZIP。MSI 会安装：

Unicode 与 ANSI 两个驱动。
随包携带的客户端运行库 DLL 和认证插件（libmysql.dll、OpenSSL、Kerberos 和 SASL）。
Power BI 连接器 MatrixOne.mez。

默认安装会把连接器写入 Documents\Power BI Desktop\Custom Connectors 和 Documents\Microsoft Power BI Desktop\Custom Connectors 两个目录。客户无需安装 MySQL SDK 或 MySQL Server。MSI 安装到独立的 Matrix Origin\MatrixOne ODBC 目录，因此不会升级或卸载 Oracle 的 MySQL ODBC 安装。每个 -mo.N 包拥有独立的 MSI 产品版本（9.7.N），而 ODBC 驱动版本仍保持 9.7.0。

v9.7.0-mo.3 的 MSI 和 Unicode/ANSI 驱动 DLL 未进行 Authenticode 签名，可能影响 UAC、AppLocker、企业软件分发和安全审批。MatrixOne.mez 是未签名的 Power Query 扩展，但 Authenticode 不是 MEZ 的信任模型；Power Query 的签名/受信任连接器分发使用 PQX。请使用该版本的 SHA256SUMS.txt 校验下载文件；MSI 的 SHA-256 为 203c0ba7866333a9f1094dcbd960f48e8e77082267fa1e56706a482af23d3543。

使用便携 ZIP 时，在解压目录中打开管理员终端并运行随包提供的 Install.bat。该脚本会定位 bin\myodbc-installer.exe，并同时注册 ANSI 和 Unicode 驱动。注册系统驱动需要管理员权限。

手工注册时应使用解析后的绝对路径，不能假设 myodbc-installer.exe 位于 ZIP 根目录或已经加入 PATH：

$Root = (Resolve-Path '.').Path
$Installer = Join-Path $Root 'bin\myodbc-installer.exe'
$Lib = Join-Path $Root 'lib'
& $Installer -d -a -n 'MatrixOne ODBC 9.7 ANSI Driver' -t "DRIVER=$Lib\myodbc9a.dll;SETUP=$Lib\myodbc9S.dll"
& $Installer -d -a -n 'MatrixOne ODBC 9.7 Unicode Driver' -t "DRIVER=$Lib\myodbc9w.dll;SETUP=$Lib\myodbc9S.dll"

macOS ARM64¶

构建并注册 v9.7.0-mo.3。以下命令与该版本 CI 保持一致，并通过 Homebrew 查询路径，不假设 Homebrew 一定位于 /opt/homebrew：

git clone --branch v9.7.0-mo.3 --depth 1 https://github.com/matrixorigin/matrixone-odbc.git
cd matrixone-odbc
brew install cmake mysql-client ninja unixodbc

MYSQL_PREFIX="$(brew --prefix mysql-client)"
ODBC_PREFIX="$(brew --prefix unixodbc)"
OPENSSL_PREFIX="$(brew --prefix openssl@3)"
ZSTD_PREFIX="$(brew --prefix zstd)"
INSTALL_PREFIX="$HOME/.local/matrixone-odbc-9.7.0-mo.3"

cmake -S . -B build-macos -G Ninja \
  -DCMAKE_BUILD_TYPE=RelWithDebInfo \
  -DDISABLE_GUI=1 \
  -DWITH_UNIXODBC=1 \
  -DMYSQL_DIR="$MYSQL_PREFIX" \
  -DODBC_INCLUDES="$ODBC_PREFIX/include" \
  -DODBC_LIB_DIR="$ODBC_PREFIX/lib" \
  -DODBCINST_LIB_DIR="$ODBC_PREFIX/lib" \
  -DMYSQLCLIENT_STATIC_LINKING=0 \
  -DMYSQL_LINK_FLAGS="-L$ZSTD_PREFIX/lib -L$OPENSSL_PREFIX/lib" \
  -DWITH_PBI=1
cmake --build build-macos
cmake --install build-macos --prefix "$INSTALL_PREFIX"

使用 unixODBC 注册两个驱动。odbcinst -j 会显示当前使用的配置文件；仅当其中的 odbcinst.ini 对当前账户不可写时，才对注册命令使用 sudo。

DRIVER_TEMPLATE="$(mktemp)"
cat > "$DRIVER_TEMPLATE" <<EOF
[MatrixOne ODBC 9.7 Unicode Driver]
Description=MatrixOne ODBC 9.7 Unicode Driver
Driver=$INSTALL_PREFIX/lib/libmyodbc9w.so

[MatrixOne ODBC 9.7 ANSI Driver]
Description=MatrixOne ODBC 9.7 ANSI Driver
Driver=$INSTALL_PREFIX/lib/libmyodbc9a.so
EOF
odbcinst -i -d -f "$DRIVER_TEMPLATE"
odbcinst -q -d

确认输出中存在 MatrixOne ODBC 9.7 Unicode Driver，然后测试首次连接：

下面的短时 smoke 命令会把密码展开到进程参数列表，其他本地用户或进程监控可能看到它。只在受控主机使用，随后立即清理变量；生产测试应改用受保护的 DSN/凭据机制。

export MO_PASSWORD='your-password'
iusql -v "DRIVER={MatrixOne ODBC 9.7 Unicode Driver};SERVER=127.0.0.1;PORT=6001;DATABASE=test;UID=root;PWD=${MO_PASSWORD};SSLMODE=DISABLED"
unset MO_PASSWORD

诊断¶

连接失败时，记录 ODBC SQLSTATE 和原生错误码。驱动针对 MatrixOne 做了如下映射：

场景	SQLSTATE
原生认证错误 1044 或 1045	`28000`
无法建立连接（未知主机、socket 或主机错误）	`08001`
表不存在	`42S02`

仅在短时间复现问题时，从 ODBC 数据源（64 位）> 跟踪 开启 Windows ODBC 跟踪，因为跟踪会记录连接活动，可能包含敏感值。不要未经脱敏就提交密码或原始跟踪内容。

已知限制¶

本节记录 MatrixOne ODBC v9.7.0-mo.3 标签测试套件和 Windows 安装报告中的限制（驱动 commit 5cc5e1297f93809b1ea7352a1881b67c22b3a3ff）。这些继承的报告不能证明每个用例都已在 MatrixOne v4.2.0 精确 commit 01ae8eca88110dc29d2f51e421570bb3d850d328 上重新执行。某个 GitHub issue 在更新分支上关闭，并不表示该修复已经包含在测试所用的发布基线中。

限制	受影响版本	修复状态
不存在的用户名可能返回 `HY000`/20101 而非 `28000`；不存在数据库的映射也不完整。	ODBC `v9.7.0-mo.3`	在 `mo.3` 资产发布后的 matrixone-odbc#22 中修复，未包含在 `v9.7.0-mo.3` 中。
utf8mb4 `VARCHAR` 上报缩小的 ODBC `ColumnSize`。	`mo.3` 标签兼容性报告；#26967	标签报告中为 XFAIL；issue 后续已关闭。
不带 `LIMIT` 的 `OFFSET` 被拒绝，限制 Power Query 分页折叠。	`mo.3` 标签兼容性报告；#26769	标签报告中为 XFAIL；issue 后续已关闭。
`sql_select_limit` 被忽略，`SQL_ATTR_MAX_ROWS` 无法限制行数。	`mo.3` 标签兼容性报告；#27035	标签报告中为 XFAIL；issue 后续已关闭。
缺少列时返回 `HY000`/20301 而非 `42S22`。	`mo.3` 标签兼容性报告；#27024	标签报告中为 XFAIL；issue 后续已关闭。
`max_execution_time` 不生效，查询超时无法可靠终止查询。	`mo.3` 标签兼容性报告；#26678	标签报告中为 XFAIL；issue 后续已关闭。
不接受未加引号的 Unicode 标识符。	`mo.3` 标签兼容性报告；#26715	标签报告中为 XFAIL；issue 后续已关闭。
参数数组 `SELECT` 的结果映射可能把返回行关联到错误的参数集。即使 Power BI 连接器关闭参数绑定，通用 ODBC 应用仍会受影响。	`mo.3` 标签深度测试和 Windows 安装报告；#27034	标签报告中为 KnownIssue/XFAIL；issue 后续已关闭。启用参数绑定前应验证服务端修复或 backport。
`PAD_CHAR_TO_FULL_LENGTH` 被接受，但通过 ODBC 返回的 `CHAR` 值仍不补齐。	`mo.3` 标签兼容性报告；#27036	标签报告中为 XFAIL；issue 仍开放。

后续 main 的 issue 状态与精确发布结果分开记录；没有验证 backport 前，issue 关闭不会把 mo.3 的 XFAIL 变成通过。mo.3 随附的 Power BI 连接器关闭了参数绑定，但 mo.3 ODBC 驱动本身没有关闭该能力；matrixone#27640 使用更新的 MatrixOne main 和 ODBC PR #24 复现，因此本文不声称 mo.3 精确组合可复现。

on-premises 数据网关刷新、签名连接器策略、TLS 证书校验模式以及干净 Windows 虚拟机上的交互式 MSI 安装/修复/卸载，在此版本中尚未完成验证。