☰
Navigation :

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.

The following LuaApp agents from the core n2svcd module use SigtranApp.

The DB-… messages are:

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.