Migrating from Session (Not Recommended) to DBConnection

Session inherits from DBConnection and retains backward-compatible constructor and method parameters. The main difference is that Session can receive host, port, userid, and password in the constructor and connect immediately, whereas DBConnection requires you to create an instance first and then call connect() to establish the connection.

Session.connect(), Session.run(), and Session.login() convert old parameter names to new parameter names used by DBConnection before execution. Session.upload() reuses the parent class implementation. The two interfaces share timeout, reconnection, and high availability mechanisms. Session additionally provides wrappers for database object operations, stream subscriptions, and so on.

When migrating, follow these steps:

  1. Move connection parameters in the Session constructor to connect().

  2. Replace run() with exec(), and change parameter names to the snake_case names used by DBConnection.

  3. If your code depends on session-specific methods such as table, loadTable, database, or subscribe, continue using Session. These APIs cannot be migrated to DBConnection simply by renaming parameters.

Note: The compatible interfaces of Session still use the old parameter names. Passing old parameter names such as clearMemory or pickleTableToList to DBConnection causes an error.

Migration Item SessionParameter DBConnectionParameter
SSL enableSSL enable_ssl
Asynchronous mode enableASYNC enable_async
Serialization protocol enablePickle=True / False protocol="pickle" / "ddb"
Python parser python=True parser="python"
SQL standard compatibility sqlStd sql_std
High availability highAvailability enable_high_availability
High availability sites highAvailabilitySites high_availability_sites
Heartbeat interval keepAliveTime keep_alive_time
Number of reconnection attempts tryReconnectNums try_reconnect_nums
Public name usePublicName use_public_name
Read/write timeout readTimeout / writeTimeout timeout / net_timeout (datetime.timedelta); compatible parameters read_timeout / write_timeout use seconds
Network timeout netTimeout net_timeout
Connection timeout timeout timeout (datetime.timedelta)
Login encryption parameter enableEncryption (login()) enable_encryption
Clear memory after execution clearMemory clear_memory
Convert table to list pickleTableToList table_to_list
Fetch size fetchSize fetch_size
Disable Decimal disableDecimal disable_decimal 
import dolphindb as ddb

# Session: old style, using camelCase parameters
s = ddb.Session()
try:
    if not s.connect("localhost", 8848, "admin", "your_password"):
        raise RuntimeError("Failed to connect to DolphinDB")
    s.run("table(1..3 as a)", clearMemory=True, pickleTableToList=True)
finally:
    s.close()

# DBConnection: migrated style, using exec() and snake_case parameters
conn = ddb.DBConnection()
try:
    if not conn.connect("localhost", 8848, "admin", "your_password"):
        raise RuntimeError("Failed to connect to DolphinDB")
    conn.exec("table(1..3 as a)", clear_memory=True, table_to_list=True)
finally:
    conn.close()

Note:

  • The default protocol is DDB. Specify protocol="pickle" only when migrating code that explicitly sets enablePickle=True.

  • PICKLE has been deprecated. In Python 3.13 and later, the API automatically switches to DDB.

  • enableChunkGranularityConfig is used only for Session.database() and should remain on Session. DBConnection has no corresponding parameter.

  • enableEncryption and enable_encryption currently do not implement credential encryption. Renaming the parameter does not change this behavior.