Constructor

• config: optional. A connection settings object (ConnectionSetting) or a configuration dictionary used to pass connection parameters in batches. The default value is None.

  • If a ConnectionSetting object is specified, additional keyword arguments can override fields with the same names in the object.

  • If a dictionary is specified, its keys cannot duplicate any additional keyword arguments; otherwise, a TypeError is thrown.

ConnectionSetting is a connection settings class for centrally defining connection parameters such as SSL and data compression settings:

• Temporary or simple connections: specify keyword arguments directly in connect() when needed. There is no need to create a settings object.

• Complex or batch connections: if multiple connections share the same settings, or if parameters need to be centrally managed, create a ConnectionSetting object and pass it to config.

from dolphindb import DBConnection, ConnectionSetting

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

You can also pass a dictionary:

from dolphindb import DBConnection

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

• enable_ssl: optional, bool, default False. Whether the connection uses the SSL protocol for encrypted communication. To enable the SSL protocol, the configuration parameter enableHTTPS must be set to true on the server side.

import dolphindb as ddb

conn = ddb.DBConnection(enable_ssl=True)

For server configuration, see Secure Communication.

• enable_async: optional, bool, default False. Whether to enable asynchronous communication for the connection.

When enable_async=True is specified, exec(), call(), and run() do not wait for the server to return the execution result after sending a request. They return None directly. Therefore, the client cannot determine from the return value whether an error occurred on the server. However, a network error may still be thrown while the request is being sent. This mode is suitable for asynchronous writes that do not depend on return results, but not for regular queries or block reads.

This parameter controls only the network communication mode. It does not turn these methods into Python coroutines, and await is not required.

import dolphindb as ddb

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

Note: Do not specify parameters that depend on server return results, such as fetch_size, in asynchronous mode.

• compress: optional, bool, default False. Whether to enable data compression for the connection.

When compress=True is specified, the client compresses transmitted data. This mode is suitable for queries or writes involving a large amount of data. It can reduce network traffic, but increases computational overhead on both the client and server.

Response compression for regular queries takes effect only with the DDB protocol. PICKLE responses are not compressed in this way. Tables in uploaded data or function arguments can still be compressed and serialized according to compress=True.

The Arrow protocol cannot be enabled together with compress=True. Otherwise, constructing the connection object throws pydantic.ValidationError.

import dolphindb as ddb

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

• protocol: optional, str, default "default". Specifies the data transmission protocol used for interaction between the client and the DolphinDB server.

You can specify "default", "ddb", "pickle", or "arrow", or use the corresponding PROTOCOL_* constants in dolphindb.settings. "default" currently is equivalent to the DDB protocol.

Different protocols affect the Python types of query results. The Arrow protocol depends on pyarrow and cannot be used together with compress=True. The PICKLE protocol is deprecated, and the API automatically switches to the DDB protocol in Python 3.13 and later.

import dolphindb as ddb
from dolphindb.settings import PROTOCOL_ARROW

conn = ddb.DBConnection(protocol=PROTOCOL_ARROW)

For protocols and return types, see Data Type Conversion.

• sql_std: optional, default "ddb". Specifies the SQL dialect used to execute SQL scripts.

You can specify "ddb", "oracle", or "mysql", or specify this parameter through the SqlStd enum, for example, sql_std=SqlStd.DolphinDB.

DolphinDB server supports Oracle and MySQL dialects starting from versions 2.00.10 and 1.30.22. When using a non-default dialect, verify that both the server version and the script to be executed support the dialect.

import dolphindb as ddb

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

• show_output: optional, bool, default True. Specifies whether to display output generated by print() statements in the DolphinDB script.

When show_output=False is specified, the client does not output print messages from scripts. This parameter controls only script messages and does not affect the return values of run(), exec(), or call().

import dolphindb as ddb

conn = ddb.DBConnection(show_output=False)
conn.connect("localhost", 8848)
result = conn.run("print(1); 2")
print(result)
# output: 2

• parser: optional, str, default "dolphindb". Specifies the parser used by the server to parse scripts.

You can specify "dolphindb", "python", or "kdb", or use the corresponding ParserType enum value.

It is supported only on DolphinDB server version 3.00.0 or later. Before using Python Parser or KDB Parser, verify that the server provides the corresponding feature.

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

• pydantic.ValidationError:

  • An unknown parameter or invalid parameter value is specified. For example, if protocol, parser, or sql_std is set to an unsupported value, the system does not fall back to the default value.

  • The Arrow protocol and data compression are enabled at the same time. They are mutually exclusive.

• ImportError: The Arrow protocol is specified, but the pyarrow library is not installed in the current environment.