kamailio/misc/obsolete/bdb

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]