Debian Codegraph @

src/modules/db_cluster/README

raw
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 ...