DB Messages
Introduction
Any application may use DB-… messages to the DBApp application to request that an operation be performed against an external DBI or MongoDB database.
The following applications from the core n2svcd
module make such requests to the
DBApp.
TesterApp
(initates outbound Database requests)FoxApp
(initates outbound Database requests to fetch configuration)
The following LuaApp agents from the core n2svcd
module use SigtranApp.
DBLuaAgent
(initates outbound Database requests)
The DB-… messages are:
DB-REQUEST
DB-RESPONSE
Note that this page uses the term “on-the-wire” to refer to the sending or receiving of REST content by the DBApp. This term is also inclusive of the case where the message is sent by local loopback and does not physically transit a Network Interface Controller (NIC).
DB-REQUEST
The DB-REQUEST
message is sent to DBApp by any application that wishes
to perform an outbound database request.
Refer to the DBApp Configuration documentation for more information on setting default parameters.
The attributes of the DB-REQUEST
message are:
Field
Type
Description
dbi
Object
Container for request parameters directed to DBI-style drivers.
.method
String
Method which defines the type of operation being performed.
The other attributes depend on the method.
.sql
String
Applies for
method
== selectall_arrayref
/do
.
This is the SQL which is executed by the DBI driver.
.args
Mixed Array
Applies for
method
== selectall_arrayref
/do
.
This is the DBI bind arguments to be used in the SQL execution.
.returning
Boolean
Applies for
method
== do
/do
.
Whether the operation is expected to return a value.
mongo
Object
Container for request parameters directed to Mongo-style drivers.
.method
String
Method which defines the type of operation being performed.
The other attributes depend on the method.
.collection
String
This is the collection the operation will be performed on.
.object
Mixed Array
Applies for
method
== insert_one
/insert_many
/aggregate
/update_one
/ update_many
/delete_one
/ delete_many
/count
.
This is the Mongo Object definition arguments used in the Mongo execution.
.filter
Mixed Array
Applies for
method
== find
/find_one
/update_one
/update_many
.
This is the Mongo Filter definition arguments used in the Mongo execution.
.options
Mixed Array
Applies for
method
== find
/find_one
.
This is the Mongo Options definition arguments used in the Mongo execution.
.projection
Mixed Array
Applies for
method
== find
/find_one
.
This is the Mongo Projection definition arguments used in the Mongo execution.
Note that it is not possible to set or override connection parameters in the DB-REQUEST
message. The database connection parameters can only be set in the DBApp configuration.
DB-RESPONSE
The DB-RESPONSE
message is sent by DBApp to the requesting application
when the database interaction described in the origina DB-REQUEST
is completed,
or if a failure occurs which indicates that no database response will be received.
The attributes of the DB-RESPONSE
message are:
Field
Type
Description
success
0
/1
[Required] Indicates if the request was successful or not.
error
String
Indicates the reason why the request failed.
Present and applicable only if success
== 0
.
dbi
Object
Container for response parameters returned by DBI-style drivers.
.rows
Array of Object
Applies for
method
== selectall_arrayref
.
Array of returned Objects fetched from the database.
.nrows
Integer
Applies for
method
== do
.
Number of rows affected by the executed statement.
.returned
Array of Object
Applies for
method
== do
.
Array of returned Objects given by the RETURNING clause if present.
mongo
Object
Container for response parameters returned by Mongo-style drivers.
.inserted
Object
Applies for
method
== insert_one
/insert_many
.
Object containing insertion data for records stored in the database.
.data
Object
Applies for
method
== find
/find_one
/aggregate
.
Object of returned records fetched from the database.
.count
Object
Applies for
method
== count
.
Object containing count of records matching the provided Object definition.
.updated
Object
Applies for
method
== update
/update_one
.
Object containing update data for records updated in the database.
.deleted
Object
Applies for
method
== delete_one
/delete_many
.
Object containing deletion data for records deleted from the database.
timing
Object
Container for DB internal queue timing.
.ms_pending
Int
Amount of time in milliseconds the DB request was in the pending queue.
.ms_working
Int
Amount of time in milliseconds the DB request was in the working queue.