建立连接

host 和 port 用于指定服务端地址与端口，是建立连接所必需的参数。host 可填写域名、IP 地址或主机名；port 为服务端监听端口。二者可通过位置参数、关键字参数、ConnectionConfig 或配置字典传入。

userid 和 password 为可选登录凭据。若未指定，API 仅建立连接而不执行登录；后续如需认证，可调用 login() 完成登录。在 ConnectionConfig 中，userId 可作为 userid 的兼容别名。

import dolphindb as ddb

conn = ddb.DBConnection()
conn.connect(
    host="localhost",
    port=8848,
    userid="admin",
    password="your_password",
)

• startup：可选，连接建立后立即执行的 DolphinDB 脚本（如加载插件、定义函数或初始化表等），默认为 ""（不执行）。

注意：在初次连接成功、自动重连（reconnect=True）或高可用节点切换时，启动脚本均会被触发执行。因此，启动脚本应保持幂等性（如函数定义、变量覆盖赋值），避免包含数据追加、累加计数等可能导致重复执行副作用的操作。

import dolphindb as ddb

conn = ddb.DBConnection()
conn.connect("localhost", 8848, startup="x = 1..10")
print(conn.run("sum(x)"))
# 输出：55

不需要启动脚本时，请省略 startup 参数或传入空字符串；不建议显式传入

startup=None。

• enable_high_availability：可选。是否启用 API 高可用机制，默认值为 False。

• high_availability_sites：可选。高可用节点地址列表，列表项格式为 "host:port"；默认值为空列表。

启用高可用时会自动开启断线重连。建立连接时，API 会先连接 connect() 指定的目标节点（若配置了 high_availability_sites，则为其与目标节点的并集）获取集群状态；随后自动将集群内的可用节点加入候选池，并优先与负载较低的节点建立连接。

注意：高并发创建连接时，受负载信息同步延迟影响，新建连接不一定能完全均匀分布。

import dolphindb as ddb

sites = ["x.x.x.x:x", "x.x.x.x:x"]
conn = ddb.DBConnection()
conn.connect(
    host="x.x.x.x:x",
    port=xxx,
    userid="admin",
    password="your_password",
    enable_high_availability=True,
    high_availability_sites=sites,
)

在高可用模式下，当服务端返回可解析的 <NotLeader> 响应时，API 会切换到指定的 leader 节点；若当前节点不可用，则尝试其他可用节点。若启用 use_public_name 且集群提供相应的 publicName，API 将使用该对外地址。

• reconnect：可选，布尔值，默认为 False，指定在未开启高可用时，连接异常后是否自动重连原节点。

• try_reconnect_nums：可选，整型，默认为 None。指定自动重连的尝试轮数。未指定、指定为 0 或负数时表示无限重连；指定为正整数时，在 HA 和非 HA 模式下均会限制重连尝试次数。在 HA 模式下，每次尝试都会遍历每个节点一次，最多尝试 try_reconnect_nums 次。

自动重连会创建新的服务端会话，原会话中的临时变量不会自动恢复。需要在重连后重新执行的初始化逻辑，建议放入 startup 脚本中。

conn = ddb.DBConnection()
conn.connect(
    "localhost",
    8848,
    reconnect=True,
    try_reconnect_nums=5,
)

• timeout：可选，指定等待服务端返回响应的接收超时时间。类型为非负的 datetime.timedelta 或 None，默认值为 None。

• net_timeout：可选，指定底层网络操作的超时时间，包括 TCP 建连、数据写入和保活检测。类型为非负的 datetime.timedelta 或 None，默认值为 None。

注意：

• 上述超时均不代表单次 API 调用的总耗时上限（若触发自动重连或多次网络读写，实际总耗时可能更长）。

• 发生接收超时（timeout）时，不会自动取消服务端已经提交执行的作业。

from datetime import timedelta
import dolphindb as ddb

conn = ddb.DBConnection()
conn.connect(
    host="localhost",
    port=8848,
    timeout=timedelta(seconds=30),
    net_timeout=timedelta(seconds=10),
)

与其他连接设置一样，每次显式调用 connect() 时，都会根据本次传入的参数重新计算 timeout 和 net_timeout，不会沿用上一次连接的超时设置。

省略 timeout 或 net_timeout，或传入 None，表示该项未指定。同一次调用中已传入的 read_timeout、write_timeout 仍然生效，不会被 None 清除。

timedelta(0) 是显式的零值，与 None 不同。它会清除同一次调用中对应的 read_timeout 或 write_timeout。timeout=timedelta(0) 表示不限制等待服务端响应的时间。若 net_timeout=timedelta(0) 且 keep_alive_time <= 0，本次连接仍使用下面说明的全局默认网络超时。

未指定 net_timeout 且 keep_alive_time <= 0 时，连接使用全局默认网络超时，当前默认值为 3 秒。可通过以下接口修改：

import dolphindb.global_config as cfg

cfg.tcp.set_timeout(30)  # 单位为秒

cfg.tcp.set_timeout(0) 表示使用系统默认网络超时；传入负数会抛出 ValueError。DBConnection 每次显式调用 connect() 且需要使用全局默认值时，都会读取该配置；DBConnectionPool 则在构造时读取。修改该配置不会立即影响已建立的连接：自动重连仍会复用该连接上一次 connect() 确定的值，已有的 DBConnectionPool 也会保留构造时读取的值。

说明：SimpleDBConnectionPool 可在池配置中单独设置 timeout 和 net_timeout；其中 acquire(timeout=...) 表示等待空闲连接的时间（单位为毫秒），与本节的网络超时不是同一参数。连接池的详细超时行为请参见构造连接池。

• keep_alive_time：可选，整型，单位为秒，默认值为 -1。指定连接的保活检测周期。

• read_timeout：可选，数值型，单位为秒，默认值为 -1。指定读取服务端响应的超时时间。

• write_timeout：可选，数值型，单位为秒，默认值为 -1。指定底层数据写入的网络超时时间。

参数换算与优先级规则：

• read_timeout 与 timeout：未指定 timeout（或为 None）时，非负的 read_timeout 会按秒换算为接收超时时间；若同时指定了正数 timeout，以 timeout 为准；若指定了 timeout=timedelta(0)（不限等待时间），则会忽略同一次调用中的 read_timeout。

• write_timeout 与 net_timeout：若同时指定了正数 net_timeout，系统会采用二者中较短的时间作为写操作超时。

• keep_alive_time 与 net_timeout：keep_alive_time 会按操作系统换算为网络超时：Linux 和 macOS 上为 keep_alive_time × 3 秒，Windows 上为 keep_alive_time × 10 秒；若同时指定了正数 net_timeout，系统会采用换算值与 net_timeout 中的较小值。

conn = ddb.DBConnection()
conn.connect(
    "localhost",
    8848,
    read_timeout=30,
    write_timeout=10,
)

• use_public_name：可选参数，用于指定高可用连接是否优先使用节点的 publicName 作为连接地址，默认值为 False。

仅在启用高可用（enable_high_availability=True）时，use_public_name 才会生效；未开启高可用时，连接地址仍按原有逻辑解析，不受该参数影响。

启用该参数前，请先在服务端为相关节点正确配置 publicName，并确保客户端能够解析并访问该地址，同时仍可访问初始入口 host:port。当前实现仅支持非空的单个对外地址；如果 publicName 配置为以分号分隔的多个地址，则不会建立对外地址映射，连接仍使用节点内部地址。

conn = ddb.DBConnection()
conn.connect(
    "cluster.example.com",
    8848,
    enable_high_availability=True,
    use_public_name=True,
)

连接参数可统一保存在 ConnectionConfig 对象或字典中。使用 ConnectionConfig 对象时，直接传入的参数会覆盖对象中对应字段的值；使用字典时，若同时直接传入字典中已包含的同名参数，将抛出 TypeError。当直接传入的 host、port、userid 或 password 为 None 时，不会覆盖配置中的对应值。

import dolphindb as ddb

config = ddb.ConnectionConfig(
    host="localhost",
    port=8848,
    userid="admin",
    password="your_password",
    reconnect=True,
)
conn = ddb.DBConnection()
conn.connect(config=config)

connect() 用于建立会话，成功时返回 True；连接未建立时通常返回 False。调用方应按返回值判断是否继续执行业务操作，并仅在需要定位配置或运行时问题时关注异常。

另外，连接阶段的认证失败按 connect() 的连接结果处理；如果在连接后显式调用 login()，认证失败会抛出 RuntimeError。