mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
198 lines
7.3 KiB
198 lines
7.3 KiB
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]
|