Navigation :

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:

DB Messages (DB-REQUEST inbound).