1. BDB Module

   Sippy Software, Inc.

   Copyright © 2006 Sippy Software, Inc.
     __________________________________________________________________

   1.1. Overview

        1.1.1. Design of DBD Engine

   1.2. Dependencies

        1.2.1. External libraries or applications

   1.3. Exported parameters

        1.3.1. describe_table (string)

   1.4. Constrains and limitations
   1.5. Installation and running

        1.5.1. Using BDB With Basic SER Configuration

1.1. Overview

   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.

1.1.1. Design of DBD Engine

   The dbtext database system architecture:
     * A database is represented by a directory in the local file system
       where BDB environment is located.

Note
       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.

Note
       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).

1.2. Dependencies

1.2.1. External libraries or applications

   The next libraries or applications must be installed before running SER
   with this module:
     * Berkeley DB 4.X

1.3. Exported parameters

1.3.1. describe_table (string)

   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

1.4. Constrains and limitations

   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.

1.5. Installation and running

   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)")
...

1.5.1. Using BDB With Basic SER Configuration

   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 3. Population of version table
$ db_load -h /var/db/ser -f version.dump version

   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(st
r) i_env(int) expires(datetime) q(double) callid(str) cseq(int) method(str) flag
s(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]