Navigation :

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:

DB Messages (DB-REQUEST inbound).