Constructing a DBConnectionPool

• host: required. The server address to connect to.
• port: required. The port number of the server.
• threadNum: int, optional, default 10. The number of connections to create.
• userid: optional. The username for server login.
• password: optional. The password for server login.

Connect DBConnectionPool to a DolphinDB server by specifying the domain/IP address and the port number. You can also log in to the server by specifying the user credentials.

Example

import dolphindb as ddb

# Create 10 connections to the local DolphinDB server
pool = ddb.DBConnectionPool("localhost", 8848)

# Create 8 connections to the local DolphinDB server and log in as the user "admin"
pool = ddb.DBConnectionPool("localhost", 8848, 8, "admin", "123456")

Note

• If the connectivity parameters are incorrect, the DBConnectionPool object will not be created and the connection will fail.

bool, default False. Whether to enable load balancing when connecting to the DolphinDB server. To enable load balancing, specify this parameter as True.

Example

import dolphindb as ddb

# create DBConnectionPool with load balancing enabled
pool = ddb.DBConnectionPool("localhost", 8848, 8, loadBalance=True)

Note that in load balancing mode:

• if API high availability (HA) mode is enabled, all data nodes and compute nodes in the cluster are available for connection. In this case, loadBalance does not take effect.
• if API HA mode is disabled, DBConnectionPool will evenly distribute connections to all available nodes. For example, there are 3 nodes in the cluster and each has [5, 12, 13] connections, respectively. A DBConnectionPool needs to establish 6 connections. As a result, connections for each node is increased by 2, and the final connections on each node would be [7, 14, 15], respectively.

bool, default False. Whether to enable high availability on all cluster nodes.

Note: In API HA mode, if load balancing is disabled, DBConnectionPool will connect to the cluster node with the minimum load. As all the connections are created at the same time, they will all be added to the same node with the lowest load at the time, causing load imbalance.

Example

import dolphindb as ddb

# create DBConnectionPool with HA mode enabled. all data/compute nodes are available for connection.
pool = ddb.DBConnectionPool("localhost", 8848, 8, "admin", "123456", highAvailability=True)

bool, default False. Whether to enable compressed communication on the connections.

Compressed communication can be a useful option when writing or querying large amounts of data. When compress is set to True, the data will be compressed before being transferred, which can reduce bandwidth usage. Note that it increases the computational complexity on the server and API client, which may impact performance.

Note

• The compress parameter is supported on DolphinDB server since version 1.30.6.
• Compress communication is supported only when protocol = PROTOCOL_DDB. (In API versions 1.30.19.4 and below, compress is always supported because these versions use PROTOCOL_DDB by default. )

Example

import dolphindb as ddb
import dolphindb.settings as keys

# when API version >= 1.30.21.1, specify PROTOCOL_DDB to enable compression 
pool = ddb.DBConnectionPool("localhost", 8848, 8, compress=True, protocol=keys.PROTOCOL_DDB)

# when API version <= 1.30.19.4, PROTOCOL_DDB is used by default, i.e., enablePickle False
pool = ddb.DBConnectionPool("localhost", 8848, 8, compress=True)

• reconnect: bool, default False. Whether to reconnect if the API detects a connection exception when HA mode is disabled.

  When HA mode is enabled, the system automatically reconnects when connection exception is detected, and it is not required to specify reconnect. Otherwise, set reconnect to True for auto reconnection.

• tryReconnectNums: int, default None. Number of reconnection attempts for each connection. If not specified, reconnection attempts are not limited. If specified, limited attempts are applied in HA and non-HA modes. In HA mode, cycles through each node once per attempt, up to tryReconnectNums cycles.

import dolphindb as ddb

# create DBConnectionPool with auto reconnection
pool = ddb.DBConnectionPool("localhost", 8848, 8, reConnect=True, tryReconnectNums=5)

protocol name, default PROTOCOL_DEFAULT (equivalent to PROTOCOL_DDB). The protocol for object serialization in communication between the API client and the DolphinDB server. Note that for 3.0.1.1 and earlier Python API versions, the default protocol is PROTOCOL_PICKLE.

Currently, the protocols PROTOCOL_DDB, PROTOCOL_PICKLE, and PROTOCOL_ARROW are supported. Protocols determine the format of data returned after running DolphinDB scripts through Python API. For more information about the protocols, see Data Type Conversion.

import dolphindb.settings as keys

# use PROTOCOL_DDB
pool = ddb.DBConnectionPool("localhost", 8848, 10, protocol=keys.PROTOCOL_DDB)

# use PROTOCOL_PICKLE
pool = ddb.DBConnectionPool("localhost", 8848, 10, protocol=keys.PROTOCOL_PICKLE)

# use PROTOCOL_ARROW
pool = ddb.DBConnectionPool("localhost", 8848, 10, protocol=keys.PROTOCOL_ARROW)

Note: Starting from 1.30.21.1, the protocol parameter is provided for specifying the object serialization protocol. Prior to 1.30.19.4, PROTOCOL_DDB is used by default, i.e., enablePickle = False.

bool, default True. Determines whether to print content passed to the print() function in the terminal after executing the script.

Examples

# With show_output = True, print() content is shown
pool = ddb.DBConnectionPool("localhost", 8848, 8, show_output=True)
taskid = 12
pool.addTask("print(1);2", taskId=taskid)
while True:
    if pool.isFinished(taskId=taskid):
        break
    time.sleep(0.01)

res = pool.getData(taskId=taskid)
print(res)

# output:
1
2


# With show_output = False, print() content is suppressed
pool = ddb.DBConnectionPool("localhost", 8848, 8, show_output=False)
taskid = 12
pool.addTask("print(1);2", taskId=taskid)
while True:
    if pool.isFinished(taskId=taskid):
        break
    time.sleep(0.01)

res = pool.getData(taskId=taskid)
print(res)

# output:
2

optional, default DolphinDB. The SQL dialect used when running scripts. Possible values are DolphinDB, Oracle, and MySQL.

Note: Oracle and MySQL dialects are supported in DolphinDB server versions 1.30.22/2.00.10 and higher.

To use this parameter, import the SqlStd enumeration class from dolphindb.settings before specifying it.

import dolphindb as ddb
from dolphindb.settings import SqlStd

s = ddb.Session(sqlStd=SqlStd.Oracle)

bool, default False. Whether to enable the Python Parser feature when running scripts with DBConnectionPool.run.

Example

import dolphindb as ddb

# enable python parser 
pool = ddb.DBConnectionPool("localhost", 8848, 10, python=True)

Note: This parameter will be supported in the upcoming version 3.00 of the DolphinDB server.