When Broker mode is enabled, the SQL engine operates in an external Java process that is monitored by the driver's Broker. To efficiently provision memory and resources, the Broker automatically starts and stops the service as needed. This setting also eliminates the need for the application or users to explicitly start and stop the service.

Note that, unlike server mode, you do not need to launch the SQL engine server before establishing a connection. The Broker will launch the SQL engine server automatically when attempting to connect.

To configure the driver to use Broker mode:

  • Configure the minimum options required for a connection:
    • Set the Host Name (HostName) option to specify the name or the IP address of the MongoDB server to which you want to connect. For example, myserver.
    • Set the Schema Map (SchemaMap) option to specify the fully qualified path of the configuration file where the relational map of native data is written.
    • Set the Port Number (PortNumber) option to specifies the port number of the server listener. The default value is 27017.
    • Set options required for authentication to your server. See "Authentication" for a description of authentication methods and their requirements.
    • Set the Database Name (DatabaseName) option to specify the name of the database to which you are connecting.
  • Set the SQL Engine Mode (SQLEngineMode) option to 3 (Broker).
  • Optionally, set the Broker Port Number (BrokerPortNumber) option to specify a valid port on which the Broker listens for client connection requests. The default value is 1183.
  • Optionally, set the Max Connections Per Server (MaxConnectionsPerServer) option to specify the number of connections that can be granted to a server before another server is created. The default value is 1024.
  • Optionally, set the Server Launch Timeout (ServerLaunchTimeout) option to specify the number of seconds the Broker waits for a server process to initialize before determining that is not available. The default value is 30 seconds.
  • Optionally, set the Server Idle Timeout (ServerIdleTimeout) option to specify the number of seconds the SQL engine server can be without active connections before the Broker issues a SHUTDOWN command to stop the server. The default value is 300 seconds.
  • Optionally, set the Broker Idle Timeout (BrokerIdleTimeout) option to specify the number of seconds the Broker continues to run after all the SQL engine servers have been stopped (shutdown). This option allows you to shut down an idle Broker automatically to allow for additional connection requests from client processes. The default value is 600 seconds.
  • Optionally, set the Broker Ping Interval (BrokerPingInterval) option to specify the number of seconds between status heartbeats from a SQL engine server process to the Broker. The default value is 30 seconds.
  • Optionally, set the JVM Path (JVMPath) option to specify the fully qualified path to the Java SE 8 or higher JVM executable that you want to use to run the SQL engine server. The path must not contain double quotation marks.
  • Optionally, set the JVM Arguments (JVMArgs) option to specify a string that contains the arguments that are passed to the JVM that the driver is starting. The location of the JVM must be specified on your PATH. See "JVM Arguments" for details. The following are the default values:
    • For the 32-bit driver in direct or Broker mode: -Xmx256m
    • For all other configurations: -Xmx1024m
  • Optionally, set the JVM Classpath (JVMClasspath) option to specify the CLASSPATH for the JVM used by the driver. See "JVM Classpath" for details.

The following examples demonstrate the minimum configuration required to enable Broker mode using user ID and password authentication. The Broker mode is enabled, but the connection uses the default settings for the rest of the Broker-related options.

Connection string

DRIVER=DataDirect 8.1 MongoDB;AuthenticationDatabase=admin;DatabaseName=mydb;
      HostName=myserver;PortNumber=27017;SQLEngineMode=3;User=jsmith;
      Password=secret;

odbc.ini

[MongoDB]
Driver=ODBCHOME/lib/ivmongodb81.so
...
Description=DataDirect 8.1 MongoDB
...
AuthenticationDatabase=admin
...
DatabaseName=mydb
...
HostName=myserver
...
PortNumber=27017
...
SQLEngineMode=3
...
Password=secret
...
User=jsmith
...