The SER (SIP Express Router) supports several different persistent storage backends (flatfile, dbtext and several SQL servers). However, in certain cases those existing backends don't satisfy conditions. Particularly, SQL server-based backends typically provide good performance and scalability, but at the same time require considerable efforts to configure and manage and also have significant memory and on-disk footprint, while simpler storage backends (flatfile, dbtext) are lighter and simpler to setup and manage, but scale poorly and don't provide sufficient performance. For certain types of applications (i.e. embedded SIP applications, SIP load balancing farms etc), different solution that would combine some of the non-overlapping properties of those two existing classes of backends is necessary.
Berkeley DB is widely regarded as industry-leading open source, embeddable database engine that provides developers with fast, reliable, local persistence with almost zero administration.
The dbtext database system architecture:
A database is represented by a directory in the local file system where BDB environment is located.
When using BDB driver in SER, the database URL for modules must be the path to the directory where the BDB environment is located, prefixed by "bdb://", e.g., "bdb:///var/db/ser". If there is no "/" after "bdb://" then "CFG_DIR/" (the OS-specific path defined at SER's compile time) is inserted at the beginning of the database path automatically. So that, either an absolute path to database directory, or one relative to "CFG_DIR" directory should be provided in the URL.
The individual tables internaly are represented by binary files inside environment directory.
The BDB driver uses BTree access method.
On-disk storage format has been developed to be as simple as possible, while meeting performance requirements set forth above. It is not compatible with on-disk format of any other BDB-based DB engine (e.g. MySQL's BDB table handler).
The next libraries or applications must be installed before running SER with this module:
Define the table and its structure. Each table that will be used by other modules has to be defined. The format of the parameter is: table_name:column_name_1(column_type_1)[column_name_2(column_type_2)[... column_name_N(column_type_N)]]
The names of table and columns must not include white spaces.
The first column in definition is used as index.
Between name of table and name of first column must be ":".
Between two columns definitions must be exactly one white space.
Type of column has to be enclosed into parentheses.
Supported column types are:
int
float
double
string
str
datetime
blob
bitmap
Use of indexes:
Effective SELECT, UPDATE and DELETE operations on a structured storage that contains any more or less decent number of records are impossible without using some kind of indexing scheme. Since Berkley DB is relatively simple storage engine it provides only basic support for indexing, nearly not as rich as usually expected by an average SQL user. Therefore, it has been decided to limit number of indexes supported to one per table. This is sufficient for most of the uses in the SER (for example: usrloc, auth_db etc).
SELECT/UPDATE/DELETE records matching criteria. Due to its simplicity, Berkley DB only supports exact match on indexed field. In order to support <, >, <= and >= operations mandated by the SIP DB API it is necessary to fall back to sequental scan of the index values, which obviously has significant negative impact on performance. Fortunately those advanced records matching criterias are not required neither by the usrloc module nor by auth_db module.
BDB driver uses index only if key column appears in search clause at least once and records matching operator associated with it is '='.
It is not allowed to set index value to NULL or an empty string.
It is not allowed to update index value. The DELETE followed by INSERT should be used instead.
BDB driver does not support db_raw_query() method.
BDB driver does not support ORDER BY clause of db_query() method.
Compile the module and load it instead of mysql or other DB modules.
Example 1. Load the bdb module
...
loadmodule "/path/to/ser/modules/dbb.so"
...
modparam("module_name", "db_url", "bdb:///path/to/bdb/database")
...
Example 2. definition of the standard version table
...
modparam("bdb", "describe_table", "version:table_name(str) table_version(int)")
...
Here are the definitions for tables used by usrloc module as well as a part of basic configuration file to use BDB driver with SER. The table structures may change in future releases, so that some adjustment to example below may be necessary. That example corresponds to SER v0.9.4
According to the configuration file below, the table files will be placed in the //var/db/ser/ directory.
The table version should be populated manually before the SER is started. To do this version.dump file located in the directotry of BDB driver sources and db_load utility from Berkeley BD distribution should be used as follows:
Example 4. Configuration file
# ---------- global configuration parameters ------------------------
# [skip]
# ---------- module loading -----------------------------------------
loadmodule "/usr/local/lib/ser/modules/usrloc.so"
loadmodule "/usr/local/lib/ser/modules/bdb.so"
# ---------- module-specific configuration parameteres --------------
modparam("usrloc", "db_mode", 2)
modparam("usrloc", "timer_interval", 3)
modparam("usrloc", "db_url", "bdb:///var/db/ser")
modparam("bdb", "describe_table", "version:table_name(str) table_version(int)")
modparam("bdb", "describe_table", "location:username(str) domain(str) contact(str) i_env(int) expires(datetime) q(double) callid(str) cseq(int) method(str) flags(int) user_agent(str) received(str)")
modparam("bdb", "describe_table", "aliases:username(str) domain(str) contact(str) i_env(int) expires(datetime) q(double) callid(str) cseq(int) method(str) flags(int) user_agent(str) received(str)")
# ---------- request routing logic ----------------------------------
# [skip]