generate README for bdb module

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]