| 1 |
DB_CLUSTER Module |
| 2 |
|
| 3 |
Daniel-Constantin Mierla |
| 4 |
|
| 5 |
<[email protected]> |
| 6 |
|
| 7 |
Edited by |
| 8 |
|
| 9 |
Daniel-Constantin Mierla |
| 10 |
|
| 11 |
<[email protected]> |
| 12 |
|
| 13 |
Frits Wiersma |
| 14 |
|
| 15 |
<[email protected]> |
| 16 |
|
| 17 |
Copyright © 2012 asipto.com |
| 18 |
__________________________________________________________________ |
| 19 |
|
| 20 |
Table of Contents |
| 21 |
|
| 22 |
1. Admin Guide |
| 23 |
|
| 24 |
1. Overview |
| 25 |
2. Dependencies |
| 26 |
|
| 27 |
2.1. Kamailio Modules |
| 28 |
2.2. External Libraries or Applications |
| 29 |
|
| 30 |
3. Parameters |
| 31 |
|
| 32 |
3.1. connection (str) |
| 33 |
3.2. cluster (str) |
| 34 |
3.3. inactive_interval (int) |
| 35 |
3.4. max_query_length (int) |
| 36 |
|
| 37 |
4. Usage |
| 38 |
5. RPC Commands |
| 39 |
|
| 40 |
5.1. dbcl.list_clusters |
| 41 |
5.2. dbcl.list_connections |
| 42 |
5.3. dbcl.disable_connection |
| 43 |
5.4. dbcl.enable_connection |
| 44 |
|
| 45 |
List of Examples |
| 46 |
|
| 47 |
1.1. Set connection parameter |
| 48 |
1.2. Set cluster parameter |
| 49 |
1.3. Set inactive_interval parameter |
| 50 |
1.4. Set max_query_length parameter |
| 51 |
1.5. Sample of usage |
| 52 |
|
| 53 |
Chapter 1. Admin Guide |
| 54 |
|
| 55 |
Table of Contents |
| 56 |
|
| 57 |
1. Overview |
| 58 |
2. Dependencies |
| 59 |
|
| 60 |
2.1. Kamailio Modules |
| 61 |
2.2. External Libraries or Applications |
| 62 |
|
| 63 |
3. Parameters |
| 64 |
|
| 65 |
3.1. connection (str) |
| 66 |
3.2. cluster (str) |
| 67 |
3.3. inactive_interval (int) |
| 68 |
3.4. max_query_length (int) |
| 69 |
|
| 70 |
4. Usage |
| 71 |
5. RPC Commands |
| 72 |
|
| 73 |
5.1. dbcl.list_clusters |
| 74 |
5.2. dbcl.list_connections |
| 75 |
5.3. dbcl.disable_connection |
| 76 |
5.4. dbcl.enable_connection |
| 77 |
|
| 78 |
1. Overview |
| 79 |
|
| 80 |
This module provides a generic database clustering system. It can be |
| 81 |
used as a middle layer between modules and database connectors. |
| 82 |
|
| 83 |
Via clustering, database operations can be executed across multiple |
| 84 |
servers, based on policies such as parallel write, serial or round |
| 85 |
robin write and read. |
| 86 |
|
| 87 |
The following database commands are considered to be write operations: |
| 88 |
INSERT, DELETE, UPDATE, REPLACE, INSERT-DELAYED, INSERT-UPDATE, |
| 89 |
INSERT-ASYNC. The read operations are done for database commands: QUERY |
| 90 |
and RAW-QUERY. |
| 91 |
|
| 92 |
Note: if INSERT-ASYNC is not implemented by DB connector module, then |
| 93 |
standard INSERT operation is done. |
| 94 |
|
| 95 |
2. Dependencies |
| 96 |
|
| 97 |
2.1. Kamailio Modules |
| 98 |
2.2. External Libraries or Applications |
| 99 |
|
| 100 |
2.1. Kamailio Modules |
| 101 |
|
| 102 |
The following modules must be loaded before this module: |
| 103 |
* db connector - database connectors. |
| 104 |
|
| 105 |
2.2. External Libraries or Applications |
| 106 |
|
| 107 |
The following libraries or applications must be installed before |
| 108 |
running Kamailio with this module loaded: |
| 109 |
* None |
| 110 |
|
| 111 |
3. Parameters |
| 112 |
|
| 113 |
3.1. connection (str) |
| 114 |
3.2. cluster (str) |
| 115 |
3.3. inactive_interval (int) |
| 116 |
3.4. max_query_length (int) |
| 117 |
|
| 118 |
3.1. connection (str) |
| 119 |
|
| 120 |
Specify the connection to a real database system. The format is |
| 121 |
'conid=>DBURL' - providing a connection id and the database URL used by |
| 122 |
the database driver used. |
| 123 |
|
| 124 |
Default value is NULL. |
| 125 |
|
| 126 |
Example 1.1. Set connection parameter |
| 127 |
... |
| 128 |
modparam("db_cluster", "connection", |
| 129 |
"con1=>mysql://kamailio:kamailiorw@localhost/kamailio1") |
| 130 |
modparam("db_cluster", "connection", |
| 131 |
"con2=>mysql://kamailio:kamailiorw@localhost/kamailio2") |
| 132 |
... |
| 133 |
|
| 134 |
3.2. cluster (str) |
| 135 |
|
| 136 |
Specify the cluster definition. The format is |
| 137 |
'clsid=>conid1=def1;conid2=def2' - providing a cluster id and the list |
| 138 |
of database connections to be used. For each connection you have to |
| 139 |
provide a usage definition. The usage definition is a 4-char long |
| 140 |
string, specifying priority and command mode for read and write |
| 141 |
operations to be performed on that connection. |
| 142 |
|
| 143 |
The priority is a digit between 0 and 9, where a higher value means |
| 144 |
higher priority. Priority 0 means that the connection is not going to |
| 145 |
be used in that cluster. |
| 146 |
|
| 147 |
Command mode is a character among s, r and p. s is for doing serial |
| 148 |
operations (try first and if fails, try next); r is for doing round |
| 149 |
robin operations; p - is for doing parallel operations (this is valid |
| 150 |
only for write operations). |
| 151 |
|
| 152 |
The first two characters is priority and mode for read, followed by two |
| 153 |
characters for priority and mode for write operations. "p" is only used |
| 154 |
for write operations. |
| 155 |
|
| 156 |
Default value is NULL. |
| 157 |
|
| 158 |
Example 1.2. Set cluster parameter |
| 159 |
... |
| 160 |
modparam("db_cluster", "cluster", "cls1=>con1=9s8p;con2=9s8p") |
| 161 |
... |
| 162 |
|
| 163 |
3.3. inactive_interval (int) |
| 164 |
|
| 165 |
How long (seconds) a connection is considered inactive after a DB |
| 166 |
operations failed on it. |
| 167 |
|
| 168 |
Default value is 300 (5 min). |
| 169 |
|
| 170 |
Example 1.3. Set inactive_interval parameter |
| 171 |
... |
| 172 |
modparam("db_cluster", "inactive_interval", 180) |
| 173 |
... |
| 174 |
|
| 175 |
3.4. max_query_length (int) |
| 176 |
|
| 177 |
How long (seconds) a failed db operation needs to last before |
| 178 |
deactivating the connection for inactive_interval seconds. This |
| 179 |
prevents disabling of connections that reply fast with error codes, |
| 180 |
thus being active (e.g., due to primary key insert errors). In such |
| 181 |
cases, the database server is active. |
| 182 |
|
| 183 |
Default value is 0. |
| 184 |
|
| 185 |
Example 1.4. Set max_query_length parameter |
| 186 |
... |
| 187 |
modparam("db_cluster", "max_query_length", 5) |
| 188 |
... |
| 189 |
|
| 190 |
4. Usage |
| 191 |
|
| 192 |
Practically, all the modules that want to use a cluster, have to set |
| 193 |
their db_url parameter to "cluster://clusterid". |
| 194 |
|
| 195 |
Following rules apply when doing DB commands: the connections with |
| 196 |
highest priority are chosen first and the operations are performed |
| 197 |
according to the command mode. Note that for same priority, only one |
| 198 |
command mode is used (the one from the first connection with that |
| 199 |
priority found in the definition of the cluster). If the DB command is |
| 200 |
not successful, next set of connections based on priority is selected |
| 201 |
and the command is tried again. When the command is successful, no |
| 202 |
other try is made. |
| 203 |
|
| 204 |
For parallel operations, a command is considered successful if it |
| 205 |
succeeded on one connection from a group with same priority. |
| 206 |
|
| 207 |
Next example shows how to set a cluster with two connections to MySQL |
| 208 |
to be used for parallel writing from acc and round-robin reading by |
| 209 |
sqlops. |
| 210 |
|
| 211 |
Example 1.5. Sample of usage |
| 212 |
... |
| 213 |
modparam("db_cluster", "connection", |
| 214 |
"c1=>mysql://kamailio:kamailiorw@localhost/kamailio1") |
| 215 |
modparam("db_cluster", "connection", |
| 216 |
"c2=>mysql://kamailio:kamailiorw@remotehost/kamailio2") |
| 217 |
|
| 218 |
modparam("db_cluster", "cluster", "k1=>c1=9r9p;c2=9r9p") |
| 219 |
|
| 220 |
modparam("acc", "db_url", "cluster://k1") |
| 221 |
|
| 222 |
modparam("sqlops", "sqlcon", "ca=>cluster://k1") |
| 223 |
... |
| 224 |
|
| 225 |
5. RPC Commands |
| 226 |
|
| 227 |
5.1. dbcl.list_clusters |
| 228 |
5.2. dbcl.list_connections |
| 229 |
5.3. dbcl.disable_connection |
| 230 |
5.4. dbcl.enable_connection |
| 231 |
|
| 232 |
5.1. dbcl.list_clusters |
| 233 |
|
| 234 |
Lists all database clusters. |
| 235 |
|
| 236 |
Name: dbcl.list_clusters |
| 237 |
|
| 238 |
RPC Command Format: |
| 239 |
... |
| 240 |
kamctl rpc dbcl.list_clusters |
| 241 |
... |
| 242 |
|
| 243 |
5.2. dbcl.list_connections |
| 244 |
|
| 245 |
Lists all database connections of a specific cluster. |
| 246 |
|
| 247 |
Name: dbcl.list_connections |
| 248 |
|
| 249 |
RPC Command Format: |
| 250 |
... |
| 251 |
kamctl rpc dbcl.list_connections clustername |
| 252 |
... |
| 253 |
|
| 254 |
5.3. dbcl.disable_connection |
| 255 |
|
| 256 |
Disable a database connection of a specific cluster for a period. The |
| 257 |
database connection remains open but will not be used for the specified |
| 258 |
period (seconds). The command does not allow to close all database |
| 259 |
connections of the specific cluster. If the database connection is |
| 260 |
already disabled than the new period will overwrite the old period. |
| 261 |
|
| 262 |
Name: dbcl.disable_connection |
| 263 |
|
| 264 |
RPC Command Format: |
| 265 |
... |
| 266 |
kamctl rpc dbcl.disable_connection clustername connectionname period |
| 267 |
... |
| 268 |
|
| 269 |
5.4. dbcl.enable_connection |
| 270 |
|
| 271 |
Enable a database connection of a specific cluster. |
| 272 |
|
| 273 |
Name: dbcl.enable_connection |
| 274 |
|
| 275 |
RPC Command Format: |
| 276 |
... |
| 277 |
kamctl rpc dbcl.enable_connection clustername connectionname |
| 278 |
... |