[SR-Dev] git:master: generate README for bdb module

Module: sip-router Branch: master Commit: c90d02e608c048a3bbcf263daadb024c829bded2 URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=c90d02e… Author: Henning Westerholt &lt;henning.westerholt(a)1und1.de&gt; Committer: Henning Westerholt &lt;henning.westerholt(a)1und1.de&gt; Date: Thu Apr 30 18:54:26 2009 +0200 generate README for bdb module --- modules_s/bdb/README | 199 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 199 insertions(+), 0 deletions(-) diff --git a/modules_s/bdb/README b/modules_s/bdb/README new file mode 100644 index 0000000..4817972 --- /dev/null +++ b/modules_s/bdb/README @@ -0,0 +1,199 @@ +1. BDB Module + + Sippy Software, Inc. + + Copyright � 2006 Sippy Software, Inc. + Revision History + Revision $Revision$ $Date$ + __________________________________________________________________ + + 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]