Connecting to Server

The most important class provided by DolphinDB C++ API is DBConnection. It facilitates communication between the client and the DolphinDB server. Through DBConnection, you can execute scripts and functions on the DolphinDB server and transfer data in both directions. This section introduces how to create DBConnection objects and connect to server with detailed examples.

Creating a DBConnection Object

The constructor declaration for DBConnection is as follows:

DBConnection(bool enableSSL = false, bool asyncTask = false, int keepAliveTime = 7200, bool compress = false, bool python = false, bool isReverseStreaming = false);

Arguments

For Encryption

  • enableSSL: Whether to use the SSL protocol for communication. Defaults to false.

Note:

  • The -DUSE_OPENSSL option MUST be specified during compilation.

  • enableSSL is supported on DolphinDB server since version 1.10.17/1.20.6 or later.

  • To enable the SSL protocol, the configuration parameter enableHTTPS must be set to true on the server side. For details, see the DolphinDB Manual - Secure Communication.

For Asynchrony

  • asyncTask: Whether to enable asynchronous execution. Defaults to false.

With asynchronous mode enabled, you can proceed to the next task without waiting for a response of the current task.

Note: Asynchronous execution is supported on DolphinDB server since version 1.10.17/1.20.6.

For Keepalive Time

  • keepAliveTime:The duration (in unit of seconds) between two keepalive transmissions to detect the TCP connection status. Defaults to 7200.

Note:

  • keepAliveTime is supported on Linux, Windows, and MacOS.
  • This parameter can also be set when connecting to the server with DBConnection::connect.

For Compression

  • compress: Whether to enable compression. Defaults to false.

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.

Others

  • python: Reserved for potential future use, but as of now serves no functional purpose. Leaving it to default.
  • isReverseStreaming: Reserved for potential future use, but as of now serves no functional purpose. Leaving it to default.

Example

Construct a DBConnection object with enableSSL=true, asyncTask=false, keepAliveTime=30, and compress=true.

DBConnection conn(true, false, 30, true);

Connecting to Server

The DolphinDB C++ API provides member function DBConnection::connect to establish a connection to a DolphinDB server. The function declaration is as follows:

bool connect(const string& hostName, int port, const string& userId = "", const string& password = "", const string& initialScript = "",
		     bool highAvailability = false, const vector<string>& highAvailabilitySites = vector<string>(), int keepAliveTime=7200, bool reconnect = false);

Arguments

For Connection

  • host: The server address to connect to.
  • port: The port number of the server.
  • userId: The username for server login. Defaults to None.
  • password: The password for server login. Defaults to None.

You can connect and log in to a DolphinDB server by specifying the server domain name/IP address, port number and user credentials.

For Defining Init Script

  • initialScript: The init script to execute the tasks when the connection is established.

This parameter allows executing various preloading tasks at launch time. Various plugins, datasets, and objects can all be staged at startup prior to processing traffic.

For High Availability Mode

  • highAvailability: Whether to enable the high availability mode for the API. Defaults to false.
  • highAvailabilitySites: The IP address and port number of all available nodes, in the format of <ip>:<port>.

highAvailability and highAvailabilitySites configure the high availability (HA) of the DolphinDB C++ API. In HA mode, when connecting to cluster nodes, the API will connect to the node with the lowest load. When you create multiple sessions using a single-threaded approach, the connections are established to ensure load balancing on all available nodes. However, if the sessions are created simultaneously using a multi-threaded approach, all sessions will connect to the same node at the same time, overloading that node.

Note:

  • Rapid, continuous session creation from a single thread could lead to load imbalance, as the load status of each node may not have enough time to fully propagate across the cluster. Adding slight delays between session creation can help avoid this scenario and ensure better load distribution.
  • If highAvailability is enabled and highAvailabilitySites is unspecified, the system enables high availability on all cluster nodes by default.
  • Enabling high availability means that auto reconnection is enabled. Once disconnected, the C++ API will try to reconnect in two scenarios: If it receives the <NotLeader> error message, it will keep attempting to reconnect to the last node it successfully connected to. Otherwise, it will try connecting to the next available node specified in highAvailabilitySites following the last successfully connected node.

For Keepalive Time

  • keepAliveTime:The duration (in unit of seconds) between two keepalive transmissions to detect the TCP connection status. Defaults to 7200.

Note:

  • keepAliveTime is supported on Linux, Windows, and MacOS.
  • This parameter serves the same purpose as the keepAliveTime parameter defined in the DBConnection constructor.

For Reconnection

  • reconnect: Whether to reconnect if the API detects a connection exception when high availability is disabled. Defaults to false.

When high availability is enabled, the system automatically reconnects when connection exception is detected, in which case it is not required to specify reconnect. When high availability is disabled, set reconnect to True for auto reconnection.

Example

//Connect to DolphinDB with IP address 127.0.0.1 and port 8848 and log in with username "admin" and password "123456".
conn.connect("127.0.0.1", 8848, "admin", "123456");
//Connect to the server and execute the init script "clearAllCache();"
conn.connect("127.0.0.1", 8848, "admin", "123456", "clearAllCache();");
//Enable HA and connect to a cluster of three nodes.
std::vector<std::string> sites{"192.168.1.2:24120", "192.168.1.3:24120", "192.168.1.4:24120"};
conn.connect("192.168.1.2", 24120, "admin", "123456", "", true, sites);
//Connect to a single-node server, set the keepalive time to 30 seconds, and enable automatic reconnection.
conn.connect("127.0.0.1", 8848, "admin", "123456", "", false, std::vector<std::string>{}, 30, true);