Table of Contents
List of Examples
Table of Contents
This module provides a generic database clustering system. It can be used as a middle layer between modules and database connectors.
Via clustering, database operations can be executed across multiple servers, based on policies such as parallel write, serial or round robin write and read.
The following database commands are considered to be write operations: INSERT, DELETE, UPDATE, REPLACE, INSERT-DELAYED, INSERT-UPDATE, INSERT-ASYNC. The read operations are done for database commands: QUERY and RAW-QUERY.
Note: if INSERT-ASYNC is not implemented by DB connector module, then standard INSERT operation is done.
The following modules must be loaded before this module:
db connector - database connectors.
Specify the connection to a real database system. The format is 'conid=>DBURL' - providing a connection id and the database URL used by the database driver used.
Default value is NULL.
Example 1.1. Set connection parameter
...
modparam("db_cluster", "connection",
"con1=>mysql://kamailio:kamailiorw@localhost/kamailio1")
modparam("db_cluster", "connection",
"con2=>mysql://kamailio:kamailiorw@localhost/kamailio2")
...
Specify the cluster definition. The format is 'clsid=>conid1=def1;conid2=def2' - providing a cluster id and the list of database connections to be used. For each connection you have to provide a usage definition. The usage definition is a 4-char long string, specifying priority and command mode for read and write operations to be performed on that connection.
The priority is a digit between 0 and 9, where a higher value means higher priority. Priority 0 means that the connection is not going to be used in that cluster.
Command mode is a character among s, r and p. s is for doing serial operations (try first and if fails, try next); r is for doing round robin operations; p - is for doing parallel operations (this is valid only for write operations).
The first two characters is priority and mode for read, followed by two characters for priority and mode for write operations. "p" is only used for write operations.
Default value is NULL.
Example 1.2. Set cluster parameter
...
modparam("db_cluster", "cluster", "cls1=>con1=9s8p;con2=9s8p")
...
How long (seconds) a connection is considered inactive after a DB operations failed on it.
Default value is 300 (5 min).
Example 1.3. Set inactive_interval parameter
...
modparam("db_cluster", "inactive_interval", 180)
...
How long (seconds) a failed db operation needs to last before deactivating the connection for inactive_interval seconds. This prevents disabling of connections that reply fast with error codes, thus being active (e.g., due to primary key insert errors). In such cases, the database server is active.
Default value is 0.
Practically, all the modules that want to use a cluster, have to set their db_url parameter to "cluster://clusterid".
Following rules apply when doing DB commands: the connections with highest priority are chosen first and the operations are performed according to the command mode. Note that for same priority, only one command mode is used (the one from the first connection with that priority found in the definition of the cluster). If the DB command is not successful, next set of connections based on priority is selected and the command is tried again. When the command is successful, no other try is made.
For parallel operations, a command is considered successful if it succeeded on one connection from a group with same priority.
Next example shows how to set a cluster with two connections to MySQL to be used for parallel writing from acc and round-robin reading by sqlops.
Example 1.5. Sample of usage
...
modparam("db_cluster", "connection",
"c1=>mysql://kamailio:kamailiorw@localhost/kamailio1")
modparam("db_cluster", "connection",
"c2=>mysql://kamailio:kamailiorw@remotehost/kamailio2")
modparam("db_cluster", "cluster", "k1=>c1=9r9p;c2=9r9p")
modparam("acc", "db_url", "cluster://k1")
modparam("sqlops", "sqlcon", "ca=>cluster://k1")
...
Lists all database clusters.
Name: dbcl.list_clusters
RPC Command Format:
... kamcmd dbcl.list_clusters ...
Lists all database connections of a specific cluster.
Name: dbcl.list_connections
RPC Command Format:
... kamcmd dbcl.list_connections clustername ...
Disable a database connection of a specific cluster for a period. The database connection remains open but will not be used for the specified period (seconds). The command does not allow to close all database connections of the specific cluster. If the database connection is already disabled than the new period will overwrite the old period.
Name: dbcl.disable_connection
RPC Command Format:
... kamcmd dbcl.disable_connection clustername connectionname period ...