DBApp

DB Application Configuration

The N2SVCD DB Application is a helper gateway application which performs synchronous 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 following configuration is used to create a DB Application instance to perform synchronous DB requests to a database server. A single DB Application will maintain a connection 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). DB applications may be repeated X number of times using the repeat attribute on the <application> definition to increase performance by loading several connections at once.

<?xml version="1.0" encoding="utf-8"?>
<n2svcd>
  ...
  <applications>
    ...
    <application name="DB-SMF" module="DBApp" repeat="5">
      <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="post_login_sql" value="BEGIN SMF_SECURITY.RESPONSE(SMF.SMF_SECURITY_RESPONSE(SMF_SECURITY.CHALLENGE('N2 DB App'))); END;"/>
        <parameter name="ping_supported" value="1"/>
        <parameter name="ping_interval" value="60"/>
      </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" repeat="5">
      <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="ping_supported" value="1"/>
        <parameter name="ping_interval" value="60"/>
      </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

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
See: Common Application configuration
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.
"reconnect_interval" Positive Integer Attribute Time in seconds between attempts to re-connect a failed database connection.
(Default = 5)
"ping_supported" Boolean Attribute Whether or not to periodically ping the remote database server.
(Default = 1)
"db_request_expiry_seconds" Positive Integer Attribute Time in seconds that a DB request may sit in the pending queue before being timed out.
(Default = 5)
"db_request_expiry_ms" Positive Integer Attribute Alternative fine-grained parameter for configuring the pending queue timeout for a DB request.
"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)
"connect_timeout_ms" Positive Integer Attribute Time in milliseconds allowed for each database connection attempt before it is aborted with an error.
A connect_timeout of zero will disable the connect timeout checks.
(Default = 2000)
"action_timeout_ms" Positive Integer Attribute Time in milliseconds for each database action to complete before it is aborted with an error.
A action_timeout of zero will disable the action timeout checks.
(Default = 1000)
"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: