[SR-Dev] git:master: generate README for bdb module
Henning Westerholt
henning.westerholt at 1und1.de
Mon May 4 15:10:42 CEST 2009
Module: sip-router
Branch: master
Commit: c90d02e608c048a3bbcf263daadb024c829bded2
URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=c90d02e608c048a3bbcf263daadb024c829bded2
Author: Henning Westerholt <henning.westerholt at 1und1.de>
Committer: Henning Westerholt <henning.westerholt at 1und1.de>
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]
More information about the sr-dev
mailing list