DBApp

DB Application Configuration

The N2SVCD DB Application is a helper gateway application which performs asynchronous database requests. The default for Oracle SQL*Net DB requests is that the client will block and wait for the database lookup to complete. The N2SVCD DB Application spawns child processes which allow for long-running queries to be performed in the background, while allowing other tests and call processing to continue without interruption.

The following configuration is used to create a DB Application instance to perform asynchronous DB requests to a database server. A single DB Application instance will maintain a pool of connections to a single database server. If you need to connect to more than one remote database server, you must configure multiple DB Application instances (each with unique names).

In some cases, you may even wish to configure multiple DB Application instances to the same server. For example, you may wish to use one pool of DB connections for long-running queries, while creating a second pool for faster and more important queries.

<?xml version="1.0" encoding="utf-8"?>
<n2svcd>
  ...
  <applications>
    ...
    <application name="DB-SMF" module="DBApp">
      <include><lib>../apps/db/lib</lib></include>
      <parameters>
        <parameter name="dbtype" value="dbi"/>
        <parameter name="connect" value="dbi:Oracle:host=10.42.2.154;sid=SMF;port=1521"/>
        <parameter name="username" value="smf"/>
        <parameter name="password" value="top-s3cr3t"/>
        <parameter name="pool" value="3"/>
        <parameter name="post_login_sql" value="BEGIN SMF_SECURITY.RESPONSE(SMF.SMF_SECURITY_RESPONSE(SMF_SECURITY.CHALLENGE('N2 DB App'))); END;"/>
      </parameters>
    </application>
    ...
  </application>
  ...
</n2svcd>

Using MongoDB, an example might be:

<?xml version="1.0" encoding="utf-8"?>
<n2svcd>
  ...
  <applications>
    ...
    <application name="DB-N2QD-MONGO" module="DBApp">
      <include>
        <lib>../apps/db/lib</lib>
      </include>
      <parameters>
        <parameter name="connect" value="mongodb://server1.telco.com:27017,server2.telco.com:27017/n2qd?replicaSet=n2qd&authSource=$external&readPreference=primary"/>
        <parameter name="username" value=""/>
        <parameter name="password" value=""/>
        <parameter name="dbtype" value="mongo"/>
        <parameter name="pool" value="2"/>
        <parameter name="replica_set_name" value="n2qd"/>
      </parameters>
      <config>
        <dbh_attributes>
          <attribute name="ssl.SSL_cert_file" value="/etc/ssl/n2svcd/n2User-pp.pem"/>
          <attribute name="ssl.SSL_key_file" value="/etc/ssl/n2svcd/n2User-pp.pem"/>
          <attribute name="ssl.SSL_ca_file" value="/etc/ssl/n2svcd/2dCA.cer"/>
          <attribute name="auth_mechanism" value="MONGODB-X509"/>
        </dbh_attributes>
      </config>
    </application>
    ...
  </application>
  ...
</n2svcd>

Configuration Details

In addition to the common Application configuration parameters, the application element attributes for a DB Application instance may include the below. For details of the various parameter types used, refer to Common Configuration.

Parameter Name Type XML Type Description
module String Attribute [Required] DBApp
include.lib String Element [Required] ../apps/osd/lib
parameters Array Element [Required] Array of name = value Parameters for this Application instance.
.edr_enabled - - This value is ignored; the DB Application does not support writing EDRs.
.connect String Attribute [Required] The DBI connection string for the target database.
When using DBD::Oracle with port 1521, it is strongly suggested that you explicitly specify the ;port=<port-num> component of the connection string to avoid a 60 second connection delay associated with a failed attempt to connect to port 1526.
.dbtype dbi/mongo Attribute The type of underlying database connection and supported methods.
(Default = dbi)
.username String Attribute Username to present to the database as credentials.
.password String Attribute Password to present to the database as credentials.
.pool Positive Integer Attribute Number of simultaneous child processes to maintain - one database connection per child.
(Default = 2)
.backlog_timeout Positive Integer Attribute Number of seconds to wait for a free connection before abandoning the request.
(Default = 10)
.server_timeout Positive Integer Attribute Number of seconds to wait on a submitted request before abandoning the request.
(Default = 5)
.reconnect_interval Positive Integer Attribute Time in seconds between attempts to re-connect a failed database connection.
(Default = 5)
.ping_interval Positive Integer Attribute Time in seconds between "ping" to check connection on an inactive database connection.
A ping_interval of zero will disable ping connection checks.
(Default = 60)
.long_raw_len String Attribute Maximum length in bytes for reading LONG RAW columns.
Applicable to dbi database connections to an Oracle DB only.
(Default = 65536)
.post_login_sql String Attribute An SQL command to perform via "do" after the DB connection is made.
Applicable to dbi database connections only.
(Default = null)
config Object Element Container for extended configuration for this Application instance.
.dbi_attributes Array Attribute Array of attribute elements defining Database Handle connection attributes.
.attribute Object Attribute Configures a Database Handle connection attribute.

Note: The DBI connection string format varies according to the type of target database.

For an Oracle DB the format is is dbi:Oracle:host=<host-name-or-ip>;sid=<oracle-sid>.

DBH Attributes

Extended connection attributes can be configured for MongoDB or DBI connections.

Each attribute Object in the config.dbh_attributes Array is configured as follows.

Parameter Name Type XML Type Description
name String Attribute [Required] The name of the DB handle connection attribute.
If this value contains . then it will be treated as a nested parameter.
value String Attribute [Required] The value of the DB handle connection attribute.

Message Handling

In addition to the common Application management messages, the DBApp uses the following messages: