构造函数

• config：可选，连接高级配置对象（ConnectionSetting）或配置字典，用于批量传入连接参数。默认为 None。

  • 若传入 ConnectionSetting 对象，也可以通过额外的关键字参数覆盖该对象中的同名字段。

  • 若传入字典，其键名不能与额外传入的关键字参数重复，否则将抛出 TypeError。

  ConnectionSetting 是连接配置的管理类，用于集中定义 SSL、数据压缩等连接参数：

  • 临时或简单连接：推荐直接在 connect() 中通过关键字参数指定（如 DBConnection(enable_ssl=True)），无需创建配置对象。

  • 复杂或批量连接：如果多个连接共享相同配置，或需要统一管理参数，推荐创建 ConnectionSetting 对象并传入 config 参数复用。

    from dolphindb import DBConnection, ConnectionSetting
    
    setting = ConnectionSetting(protocol="ddb", compress=True)
    conn = DBConnection(config=setting, show_output=False)

  也可以传入字典：

  from dolphindb import DBConnection
  
  conn = DBConnection(config={"protocol": "ddb", "compress": True})

• enable_ssl：可选，指定是否对客户端与 DolphinDB 服务端之间的通信进行加密，默认值为 False。启用前，服务端必须同时配置 enableHTTPS=true，否则客户端无法建立 SSL 连接。

import dolphindb as ddb

conn = ddb.DBConnection(enable_ssl=True)

有关服务端配置，参见安全通信。

• enable_async：可选，是否支持异步通讯，默认值为 False。

指定 enable_async=True 时，exec()、call() 和 run() 在发送请求后不会等待服务端返回执行结果，而是直接返回 None。因此，客户端无法通过返回值判断服务端是否执行出错；但如果请求发送过程中发生网络错误，仍可能抛出异常。该模式适用于无需依赖执行结果的异步写入场景，不适用于普通查询或分段读取。

该参数仅控制网络通信方式，不会将上述方法转换为 Python 协程，因此也无需使用 await。

import dolphindb as ddb

conn = ddb.DBConnection(enable_async=True)
conn.connect("localhost", 8848, "admin", "your_password")
conn.run("x = 1")

注意：异步模式下，请勿指定 fetch_size 等依赖服务端返回结果的参数。

• compress：可选，是否压缩客户端与 DolphinDB 服务端之间传输的数据，默认值为 False。

指定 compress=True 时，客户端会对传输数据进行压缩。该模式适用于数据量较大的查询或写入场景，可以降低网络传输量，但会增加客户端和服务端的计算开销。

普通查询的响应压缩仅对 DDB 协议生效，PICKLE 响应不启用该压缩；上传数据或函数参数中的表仍可按 compress=True 进行压缩序列化。

Arrow 协议不能与 compress=True 同时启用，否则构造连接对象时会抛出 pydantic.ValidationError。

import dolphindb as ddb

conn = ddb.DBConnection(compress=True, protocol="ddb")

• protocol：可选，指定 API 与 DolphinDB 服务端交互时使用的数据传输协议，默认值为 "default"。

可以指定为 "default"、"ddb"、"pickle" 或 "arrow"，也可以使用 dolphindb.settings 中对应的 PROTOCOL_* 常量。"default" 当前等价于 DDB 协议。

不同协议会影响查询结果对应的 Python 类型。Arrow 协议依赖 pyarrow，且不能与 compress=True 同时使用；PICKLE 协议已弃用，在 Python 3.13 及以上版本中，API 会自动改用 DDB 协议。

import dolphindb as ddb
from dolphindb.settings import PROTOCOL_ARROW

conn = ddb.DBConnection(protocol=PROTOCOL_ARROW)

有关协议与返回类型，参见类型转换。

• sql_std：可选，指定执行 SQL 脚本时使用的方言，默认值为 "ddb"。

可以指定为 "ddb"、"oracle" 或 "mysql"，也可通过 SqlStd 枚举类型来指定该参数，例如 sql_Std=SqlStd.DolphinDB。

DolphinDB 服务端自 2.00.10、1.30.22 起支持 Oracle 和 MySQL 方言。使用非默认方言时，应确认服务端版本和待执行脚本均支持该方言。

import dolphindb as ddb

conn = ddb.DBConnection(sql_std="oracle")

• show_output：可选，指定是否输出 DolphinDB 脚本中 print 语句产生的消息，默认值为 True。

指定 show_output=False 时，客户端不会输出脚本中的 print 消息。该参数只控制脚本消息，不影响 run()、exec() 或 call() 的返回值。

import dolphindb as ddb

conn = ddb.DBConnection(show_output=False)
conn.connect("localhost", 8848)
result = conn.run("print(1); 2")
print(result)
# 仅输出：2

• parser：可选，指定服务端解析脚本时使用的解析器，默认值为 "dolphindb"。

可以指定为 "dolphindb"、"python" 或 "kdb"，也可以使用对应的 ParserType 枚举值。

解析器参数仅适用于 DolphinDB 3.00 版本。使用 Python Parser 或 KDB Parser 前，应确认服务端已提供相应功能。

import dolphindb as ddb

python_conn = ddb.DBConnection(parser="python")
kdb_conn = ddb.DBConnection(parser="kdb")

• pydantic.ValidationError：

  • 传入未知参数或参数取值非法（如 protocol、parser、sql_std 传入非预设选项，系统不会回退至默认值）。

  • 同时启用了 Arrow 协议与数据压缩（两者互斥）。

• ImportError：指定使用 Arrow 协议但当前运行环境中未安装 pyarrow 库。