Browse code

modules: readme files regenerated - db_redis ... [skip ci]

Kamailio Dev authored on 08/09/2019 08:31:59
Showing 1 changed files
... ...
@@ -235,6 +235,7 @@ loadmodule "db_redis.so"
235 235
 #!define DBURL_ACC    "redis://127.0.0.1:6379/6"
236 236
 #!define DBURL_AUTH   "redis://127.0.0.1:6379/7"
237 237
 #!define DBURL_PERM   "redis://127.0.0.1:6379/8"
238
+#!define DBURL_DLG    "redis://127.0.0.1:6379/9"
238 239
 ...
239 240
 modparam("db_redis", "schema_path", "/usr/share/kamailio/db_redis/kamailio")
240 241
 modparam("db_redis", "keys", "version=entry:table_name")
... ...
@@ -242,6 +243,9 @@ modparam("db_redis", "keys", "location=entry:ruid&usrdom:username,domain&timer:p
242 243
 artition,keepalive")
243 244
 modparam("db_redis", "keys", "acc=entry:callid,time_hires&cid:callid")
244 245
 modparam("db_redis", "keys", "subscriber=entry:username,domain")
246
+modparam("db_redis", "keys", "dialog=entry:hash_entry,hash_id&cid:callid")
247
+modparam("db_redis", "keys", "dialog_vars=entry:hash_entry,hash_id,dialog_key&di
248
+alog:hash_entry,hash_id")
245 249
 ...
246 250
 modparam("usrloc", "db_url", DBURL_USRLOC)
247 251
 ...
... ...
@@ -250,6 +254,8 @@ modparam("acc_db", "db_url", DBURL_ACC)
250 254
 modparam("auth_db", "db_url", DBURL_AUTH)
251 255
 ...
252 256
 modparam("permissions", "db_url", DBURL_PERM)
257
+...
258
+modparam("dialog", "db_url", DBURL_DLG)
253 259
 ...
254 260
 
255 261
    Samples adding records for address table using 'redis-cli':
Browse code

modules: readme files regenerated - db_redis ... [skip ci]

Kamailio Dev authored on 31/07/2019 09:17:27
Showing 1 changed files
... ...
@@ -10,8 +10,6 @@ Andreas Granig
10 10
 
11 11
    <agranig@sipwise.com>
12 12
 
13
-Edited by
14
-
15 13
 Alex Balashov
16 14
 
17 15
    <abalashov@evaristesys.com>
... ...
@@ -138,7 +136,9 @@ nce/string,server_id/int,connection_id/int,keepalive/int,partition/int
138 136
    parameter, but it does not need to be related to the table loaded from
139 137
    Redis server -- for example, if used only for permissions module with
140 138
    'address' table, then the 'keys' parameter can be specified for
141
-   'version' table.
139
+   'version' table. However, if it used for a module that inserts or
140
+   updates the records in database table, the key for entry must be
141
+   defined for that table.
142 142
 
143 143
    The mappings can be freely defined in the "keys" module parameter,
144 144
    which is composed of a semi-colon separated list of definitions in the
Browse code

modules: readme files regenerated - db_redis ... [skip ci]

Kamailio Dev authored on 02/11/2018 08:16:27
Showing 1 changed files
... ...
@@ -134,6 +134,12 @@ nce/string,server_id/int,connection_id/int,keepalive/int,partition/int
134 134
    'address:entry::1', address:entry::2', address:entry::3', ... No 'keys'
135 135
    modparam of 'db_redis' for 'address' table needs to be defined.
136 136
 
137
+   Important Note: at this moment the module requires at least one 'keys'
138
+   parameter, but it does not need to be related to the table loaded from
139
+   Redis server -- for example, if used only for permissions module with
140
+   'address' table, then the 'keys' parameter can be specified for
141
+   'version' table.
142
+
137 143
    The mappings can be freely defined in the "keys" module parameter,
138 144
    which is composed of a semi-colon separated list of definitions in the
139 145
    format
... ...
@@ -231,6 +237,7 @@ loadmodule "db_redis.so"
231 237
 #!define DBURL_PERM   "redis://127.0.0.1:6379/8"
232 238
 ...
233 239
 modparam("db_redis", "schema_path", "/usr/share/kamailio/db_redis/kamailio")
240
+modparam("db_redis", "keys", "version=entry:table_name")
234 241
 modparam("db_redis", "keys", "location=entry:ruid&usrdom:username,domain&timer:p
235 242
 artition,keepalive")
236 243
 modparam("db_redis", "keys", "acc=entry:callid,time_hires&cid:callid")
Browse code

modules: readme files regenerated - db_redis ... [skip ci]

Kamailio Dev authored on 26/09/2018 18:16:30
Showing 1 changed files
... ...
@@ -28,24 +28,26 @@ Alex Balashov
28 28
         3. Dependencies
29 29
 
30 30
               3.1. Kamailio Modules
31
+              3.2. External Libraries or Applications
31 32
 
32 33
         4. Parameters
33 34
 
34 35
               4.1. schema_path (string)
35 36
               4.2. keys (string)
37
+              4.3. verbosity (int)
36 38
 
37
-        5. External Libraries or Applications
38
-        6. Usage
39
-        7. Module specific considerations
39
+        5. Usage
40
+        6. Module Specific Considerations
40 41
 
41
-              7.1. usrloc
42
+              6.1. usrloc
42 43
 
43 44
    List of Examples
44 45
 
45 46
    1.1. Setting schema_path module parameter
46 47
    1.2. Setting keys module parameter
47
-   1.3. Usage
48
+   1.3. Setting verbosity module parameter
48 49
    1.4. Usage
50
+   1.5. Usage
49 51
 
50 52
 Chapter 1. Admin Guide
51 53
 
... ...
@@ -56,17 +58,18 @@ Chapter 1. Admin Guide
56 58
    3. Dependencies
57 59
 
58 60
         3.1. Kamailio Modules
61
+        3.2. External Libraries or Applications
59 62
 
60 63
    4. Parameters
61 64
 
62 65
         4.1. schema_path (string)
63 66
         4.2. keys (string)
67
+        4.3. verbosity (int)
64 68
 
65
-   5. External Libraries or Applications
66
-   6. Usage
67
-   7. Module specific considerations
69
+   5. Usage
70
+   6. Module Specific Considerations
68 71
 
69
-        7.1. usrloc
72
+        6.1. usrloc
70 73
 
71 74
 1. Overview
72 75
 
... ...
@@ -156,46 +159,69 @@ allid,time_hires&cid:callid
156 159
 3. Dependencies
157 160
 
158 161
    3.1. Kamailio Modules
162
+   3.2. External Libraries or Applications
159 163
 
160 164
 3.1. Kamailio Modules
161 165
 
162 166
    The following modules must be loaded before this module:
163 167
      * none.
164 168
 
169
+3.2. External Libraries or Applications
170
+
171
+   The following libraries or applications must be installed before
172
+   running Kamailio with this module loaded:
173
+     * hiredis - available at https://github.com/redis/hiredis
174
+
165 175
 4. Parameters
166 176
 
167 177
    4.1. schema_path (string)
168 178
    4.2. keys (string)
179
+   4.3. verbosity (int)
169 180
 
170 181
 4.1. schema_path (string)
171 182
 
172
-   The path to the table schemas (default /usr/share/kamailio/db_redis).
183
+   The path to the table schemas.
184
+
185
+   Default value: "/usr/share/kamailio/db_redis".
173 186
 
174 187
    Example 1.1. Setting schema_path module parameter
188
+...
175 189
 modparam("db_redis", "schema_path", "/usr/local/share/kamailio/db_redis/kamailio
176 190
 ")
191
+...
177 192
 
178 193
 4.2. keys (string)
179 194
 
180 195
    The entry and mapping keys of tables.
181 196
 
197
+   Default value: "" (empty).
198
+
182 199
    Example 1.2. Setting keys module parameter
200
+...
183 201
 modparam("db_redis", "keys", "version=entry:table_name;location=entry:ruid&usrdo
184 202
 m:username,domain&timer:partition,keepalive")
203
+...
185 204
 
186
-5. External Libraries or Applications
205
+4.3. verbosity (int)
187 206
 
188
-   The following libraries or applications must be installed before
189
-   running Kamailio with this module loaded:
190
-     * hiredis - available at https://github.com/redis/hiredis
207
+   Control the verbosity of debug messages printed by the module. If set
208
+   to 1, the module prints schema details for all tables on each connect
209
+   operation to Redis server.
210
+
211
+   Default value: 1.
191 212
 
192
-6. Usage
213
+   Example 1.3. Setting verbosity module parameter
214
+...
215
+modparam("db_redis", "verbosity", 0)
216
+...
217
+
218
+5. Usage
193 219
 
194 220
    Load the module and set the "db_url" modparam for specific modules to:
195 221
    'redis://[username]@host:port/database'. Username is optional. The
196 222
    database portion must be a valid Redis database number.
197 223
 
198
-   Example 1.3. Usage
224
+   Example 1.4. Usage
199 225
 ...
200 226
 loadmodule "db_redis.so"
201 227
 ...
... ...
@@ -221,7 +247,7 @@ modparam("permissions", "db_url", DBURL_PERM)
221 247
 
222 248
    Samples adding records for address table using 'redis-cli':
223 249
 
224
-   Example 1.4. Usage
250
+   Example 1.5. Usage
225 251
 ...
226 252
 SELECT 8
227 253
 HMSET address:entry::1 id 1 grp 1 ip_addr "127.0.0.1" mask 32 port 0
... ...
@@ -236,11 +262,11 @@ HMSET address:entry::4 id 4 grp 2 ip_addr "127.0.0.4" mask 32 port 0 tag "test"
236 262
    database schema. When definition allows 'NULL', that field can be
237 263
    unset.
238 264
 
239
-7. Module specific considerations
265
+6. Module Specific Considerations
240 266
 
241
-   7.1. usrloc
267
+   6.1. usrloc
242 268
 
243
-7.1. usrloc
269
+6.1. usrloc
244 270
 
245 271
    If you set "expires_type" to "1" in order to use BIGINT instead of
246 272
    DATETIME, make sure to update your location schema file and change the
Browse code

modules: readme files regenerated - db_redis ... [skip ci]

Kamailio Dev authored on 24/09/2018 14:01:32
Showing 1 changed files
... ...
@@ -231,9 +231,9 @@ HMSET address:entry::4 id 4 grp 2 ip_addr "127.0.0.4" mask 32 port 0 tag "test"
231 231
 ...
232 232
 
233 233
    Note that is some cases, the optional values in database tables can be
234
-   ommitted. For 'address' table, the 'tag' value may be ommitted. To
235
-   avoid any issues, set unused fields to their default values as defined
236
-   by database schema. When definition allows 'NULL', that field can be
234
+   omitted. For 'address' table, the 'tag' value may be omitted. To avoid
235
+   any issues, set unused fields to their default values as defined by
236
+   database schema. When definition allows 'NULL', that field can be
237 237
    unset.
238 238
 
239 239
 7. Module specific considerations
Browse code

modules: readme files regenerated - db_redis ... [skip ci]

Kamailio Dev authored on 24/09/2018 13:46:28
Showing 1 changed files
... ...
@@ -45,6 +45,7 @@ Alex Balashov
45 45
    1.1. Setting schema_path module parameter
46 46
    1.2. Setting keys module parameter
47 47
    1.3. Usage
48
+   1.4. Usage
48 49
 
49 50
 Chapter 1. Admin Guide
50 51
 
... ...
@@ -121,6 +122,15 @@ nce/string,server_id/int,connection_id/int,keepalive/int,partition/int
121 122
    module also write mappings besides the actual records for billing
122 123
    systems to correlate start and stop records faster).
123 124
 
125
+   The key is always prefixed with 'tablename:entry::'. For example the
126
+   record in 'subscriber' table for user 'alice@sip.com' has the key:
127
+   'subscriber:entry::alice:sip.com'. If all the records are just loaded
128
+   at startup (or all reloaded at runtime), the key can just be made
129
+   unique using whatever values added after 'tablename:entry::' prefix.
130
+   For example, keys for 'address' table records can be:
131
+   'address:entry::1', address:entry::2', address:entry::3', ... No 'keys'
132
+   modparam of 'db_redis' for 'address' table needs to be defined.
133
+
124 134
    The mappings can be freely defined in the "keys" module parameter,
125 135
    which is composed of a semi-colon separated list of definitions in the
126 136
    format
... ...
@@ -182,7 +192,7 @@ m:username,domain&timer:partition,keepalive")
182 192
 6. Usage
183 193
 
184 194
    Load the module and set the "db_url" modparam for specific modules to:
185
-   redis://[username]@host:port/database. Username is optional. The
195
+   'redis://[username]@host:port/database'. Username is optional. The
186 196
    database portion must be a valid Redis database number.
187 197
 
188 198
    Example 1.3. Usage
... ...
@@ -192,16 +202,39 @@ loadmodule "db_redis.so"
192 202
 #!define DBURL_USRLOC "redis://127.0.0.1:6379/5"
193 203
 #!define DBURL_ACC    "redis://127.0.0.1:6379/6"
194 204
 #!define DBURL_AUTH   "redis://127.0.0.1:6379/7"
205
+#!define DBURL_PERM   "redis://127.0.0.1:6379/8"
195 206
 ...
196 207
 modparam("db_redis", "schema_path", "/usr/share/kamailio/db_redis/kamailio")
197 208
 modparam("db_redis", "keys", "location=entry:ruid&usrdom:username,domain&timer:p
198 209
 artition,keepalive")
199 210
 modparam("db_redis", "keys", "acc=entry:callid,time_hires&cid:callid")
200 211
 modparam("db_redis", "keys", "subscriber=entry:username,domain")
212
+...
201 213
 modparam("usrloc", "db_url", DBURL_USRLOC)
214
+...
202 215
 modparam("acc_db", "db_url", DBURL_ACC)
216
+...
203 217
 modparam("auth_db", "db_url", DBURL_AUTH)
204 218
 ...
219
+modparam("permissions", "db_url", DBURL_PERM)
220
+...
221
+
222
+   Samples adding records for address table using 'redis-cli':
223
+
224
+   Example 1.4. Usage
225
+...
226
+SELECT 8
227
+HMSET address:entry::1 id 1 grp 1 ip_addr "127.0.0.1" mask 32 port 0
228
+HMSET address:entry::2 id 2 grp 1 ip_addr "127.0.0.2" mask 32 port 0
229
+HMSET address:entry::3 id 3 grp 2 ip_addr "127.0.0.3" mask 32 port 0
230
+HMSET address:entry::4 id 4 grp 2 ip_addr "127.0.0.4" mask 32 port 0 tag "test"
231
+...
232
+
233
+   Note that is some cases, the optional values in database tables can be
234
+   ommitted. For 'address' table, the 'tag' value may be ommitted. To
235
+   avoid any issues, set unused fields to their default values as defined
236
+   by database schema. When definition allows 'NULL', that field can be
237
+   unset.
205 238
 
206 239
 7. Module specific considerations
207 240
 
Browse code

modules: readme files regenerated - db_redis ... [skip ci]

Kamailio Dev authored on 08/03/2018 15:01:24
Showing 1 changed files
... ...
@@ -36,6 +36,9 @@ Alex Balashov
36 36
 
37 37
         5. External Libraries or Applications
38 38
         6. Usage
39
+        7. Module specific considerations
40
+
41
+              7.1. usrloc
39 42
 
40 43
    List of Examples
41 44
 
... ...
@@ -60,6 +63,9 @@ Chapter 1. Admin Guide
60 63
 
61 64
    5. External Libraries or Applications
62 65
    6. Usage
66
+   7. Module specific considerations
67
+
68
+        7.1. usrloc
63 69
 
64 70
 1. Overview
65 71
 
... ...
@@ -196,3 +202,13 @@ modparam("usrloc", "db_url", DBURL_USRLOC)
196 202
 modparam("acc_db", "db_url", DBURL_ACC)
197 203
 modparam("auth_db", "db_url", DBURL_AUTH)
198 204
 ...
205
+
206
+7. Module specific considerations
207
+
208
+   7.1. usrloc
209
+
210
+7.1. usrloc
211
+
212
+   If you set "expires_type" to "1" in order to use BIGINT instead of
213
+   DATETIME, make sure to update your location schema file and change the
214
+   type of "expires" and "last_modified" from "time" to "int".
Browse code

modules: readme files regenerated - db_redis ... [skip ci]

Kamailio Dev authored on 22/02/2018 08:51:45
Showing 1 changed files
... ...
@@ -10,6 +10,12 @@ Andreas Granig
10 10
 
11 11
    <agranig@sipwise.com>
12 12
 
13
+Edited by
14
+
15
+Alex Balashov
16
+
17
+   <abalashov@evaristesys.com>
18
+
13 19
    Copyright © 2018 sipwise.com
14 20
      __________________________________________________________________
15 21
 
... ...
@@ -57,56 +63,61 @@ Chapter 1. Admin Guide
57 63
 
58 64
 1. Overview
59 65
 
60
-   This module provides a DB APIv1 connector for Redis server.
66
+   This module provides a DB APIv1 connector for the Redis server
67
+   (https://www.redis.io).
61 68
 
62 69
    It can be used as a replacement for other database modules such as
63 70
    db_mysql and db_postgres. Not all the specs of DB APIv1 are
64 71
    implemented, thus the usage of this module might be restricted to
65
-   specific modules. Also, for proper performance, the module needs
66
-   particular configuration tailored to the using modules.
72
+   specific modules. Also, for proper performance, this module needs
73
+   particular configuration tailored to the modules that make use of it.
67 74
 
68 75
    Since Redis does not provide a schema by itself, db_redis ships with
69
-   schema files, which path has to be defined as module parameter
70
-   "schema_path". The schema definition is defined in one file per table
71
-   with the file name being the table name, and each file is composed of a
72
-   comma-separated list of column definitions in format
73
-   <column-name>/<type>[,<column-name>/<type> ...] in one line, followed
74
-   by a line holding the table version.
75
-
76
-   Example for location definition:
76
+   schema files. The path to these has to be defined using the module
77
+   parameter "schema_path". The schema definition is defined in one file
78
+   per table, such that the file name corresponds to the table name, and
79
+   each file is composed of a comma-separated list of column definitions
80
+   in the format <column-name>/<type>[,<column-name>/<type> ...] in one
81
+   line, followed by a line holding the table version.
82
+
83
+   Example definition for the "location" table (from the usrloc module):
77 84
 username/string,domain/string,contact/string,received/string,path/string,expires
78 85
 /timestamp,q/double,callid/string,cseq/int,last_modified/timestamp,flags/int,cfl
79 86
 ags/int,user_agent/string,socket/string,methods/int,ruid/string,reg_id/int,insta
80 87
 nce/string,server_id/int,connection_id/int,keepalive/int,partition/int
81 88
 8
82 89
 
83
-   Also since Redis is a key-value store with keys having to be unique,
84
-   tables and rows e.g. from MySQL can not be ported 1:1 to Redis. For
85
-   instance, usrloc relies on a key "username@domain", but it must not be
86
-   unique for being able to store multiple contacts per AoR. Thus,
87
-   db_redis supports mapping sets in a way for example for usrloc to have
88
-   a set with a key "username@domain", with its entries being unique keys
89
-   per contact being the ruid of a contact. Thus, one contact in usrloc
90
-   consists of a unique key "location:entry::example-ruid-1" being a hash
91
-   with the columns like username, domain, contact, path etc. In addition,
92
-   this unique key is stored in a set
90
+   Because Redis is a key-value store, it requires unique keys. This means
91
+   that tables and rows from a relational SQL database, e.g. from MySQL,
92
+   can not be ported one a 1:1 basis to Redis.
93
+
94
+   For instance, usrloc relies on a key of "username@domain", but in order
95
+   to store multiple contacts per AoR, it cannot be constrained to
96
+   uniqueness. To work around this, db_redis supports mapping sets in such
97
+   a way as to, in the case of the usrloc module, have a set with a key of
98
+   "username@domain" and its entries being unique keys per contact based
99
+   on the ruid of a contact. Thus, one contact in usrloc consists of a
100
+   unique key "location:entry::example-ruid-1" being a hash with the
101
+   columns like username, domain, contact, path etc. In addition, this
102
+   unique key is stored in a set
93 103
    "location:usrdom::exampleuser:exampledomain.org". When usrloc does a
94 104
    lookup based on "username@domain", db_redis figures out via the
95
-   keys/values the query is constructed by usrloc to look for the final
96
-   entry key in the mapping set first, then querying the actual entries
97
-   from there, avoiding full table scans. For usrloc, the same holds true
98
-   for expired contacts, requiring a different kind of mapping. There is a
105
+   keys/values the query constructed by usrloc to look for the final entry
106
+   key in the mapping set first. It then query the actual entries from
107
+   there, avoiding full table scans. For usrloc, the same holds true for
108
+   expired contacts, requiring a different kind of mapping. There is a
99 109
    certain balance of read performance vs. write performance to consider,
100
-   because inserts and deletes also have to maintain the mappings, in
101
-   favor of much faster selects. The mappings can be freely defined, so
110
+   because inserts and deletes also have to maintain the mappings, though
111
+   this yields much faster selects. The mappings can be freely defined, so
102 112
    even though other kamailio modules don't require a specific mapping to
103 113
    be in place for proper performance, mappings could be defined for
104 114
    external applications to read faster (for instance letting the acc
105 115
    module also write mappings besides the actual records for billing
106 116
    systems to correlate start and stop records faster).
107 117
 
108
-   The mappings can be freely defined in the "keys" module parameter. It
109
-   is composed of a semi-colon separated list of definitions in format
118
+   The mappings can be freely defined in the "keys" module parameter,
119
+   which is composed of a semi-colon separated list of definitions in the
120
+   format
110 121
    <table-name>=<entry>:<column-name>[&<map-name>:<column-name>,<column-na
111 122
    me>...]. Each table must at least have an "entry" key for db_redis to
112 123
    be able to store data.
... ...
@@ -115,17 +126,16 @@ nce/string,server_id/int,connection_id/int,keepalive/int,partition/int
115 126
 location=entry:ruid&usrdom:username,domain&timer:partition,keepalive;acc=entry:c
116 127
 allid,time_hires&cid:callid
117 128
 
118
-   For readability purposes, keys per table can be defined line by line by
119
-   providing multiple "keys" mod-params.
120
-
121
-   You can read more about Redis at: https://www.redis.io.
129
+   For readability purposes, definitions of keys per table can span
130
+   multiple Kamailio config lines by providing multiple "keys" modparams.
122 131
 
123 132
 2. Limitations
124 133
 
125
-     * This module has implemented the equivalent operations for INSERT,
126
-       UPDATE, DELETE and SELECT. The ORDER BY for SELECT is not
127
-       implemented. Raw query is not implemented inside this module, use
128
-       ndb_redis for sending any kind of command to a Redis server.
134
+     * This module has implemented equivalent underlying Redis operations
135
+       for INSERT, UPDATE, DELETE and SELECT. The ORDER BY clause for
136
+       SELECT is not implemented. Raw querying is not implemented inside
137
+       this module; for sending literal commands to the Redis server, use
138
+       ndb_redis.
129 139
 
130 140
 3. Dependencies
131 141
 
... ...
@@ -143,8 +153,7 @@ allid,time_hires&cid:callid
143 153
 
144 154
 4.1. schema_path (string)
145 155
 
146
-   The path to the schema of your tables (default
147
-   /usr/share/kamailio/db_redis).
156
+   The path to the table schemas (default /usr/share/kamailio/db_redis).
148 157
 
149 158
    Example 1.1. Setting schema_path module parameter
150 159
 modparam("db_redis", "schema_path", "/usr/local/share/kamailio/db_redis/kamailio
... ...
@@ -152,7 +161,7 @@ modparam("db_redis", "schema_path", "/usr/local/share/kamailio/db_redis/kamailio
152 161
 
153 162
 4.2. keys (string)
154 163
 
155
-   The entry and mapping keys of your tables.
164
+   The entry and mapping keys of tables.
156 165
 
157 166
    Example 1.2. Setting keys module parameter
158 167
 modparam("db_redis", "keys", "version=entry:table_name;location=entry:ruid&usrdo
... ...
@@ -166,9 +175,9 @@ m:username,domain&timer:partition,keepalive")
166 175
 
167 176
 6. Usage
168 177
 
169
-   Load the module and set the the DB URL for specific modules to:
170
-   redis://[username]@host:port/database. Username is optional. Database
171
-   must be a valid redis database number.
178
+   Load the module and set the "db_url" modparam for specific modules to:
179
+   redis://[username]@host:port/database. Username is optional. The
180
+   database portion must be a valid Redis database number.
172 181
 
173 182
    Example 1.3. Usage
174 183
 ...
Browse code

db_redis: Use schema files and improve keys def

* Auto-generate schema files for redis from xml specs and use
them in module instead of having to define them as mod params.
* Allow key definition line by line with multiple "keys" mod params.
* Fetch table versions from schema to avoid having to populate them
in Redis.
* Fix reconnection issues on connection drops when Redis takes longer
to start.
* Fix documentation formatting issues.

Andreas Granig authored on 13/02/2018 13:55:35
Showing 1 changed files
... ...
@@ -18,24 +18,22 @@ Andreas Granig
18 18
    1. Admin Guide
19 19
 
20 20
         1. Overview
21
+        2. Limitations
22
+        3. Dependencies
21 23
 
22
-              1.1. Limitations
24
+              3.1. Kamailio Modules
23 25
 
24
-        2. Dependencies
26
+        4. Parameters
25 27
 
26
-              2.1. Kamailio Modules
27
-              2.2. Parameters
28
+              4.1. schema_path (string)
29
+              4.2. keys (string)
28 30
 
29
-                    2.2.1. schema (string)
30
-                    2.2.2. keys (string)
31
-
32
-              2.3. External Libraries or Applications
33
-
34
-        3. Usage
31
+        5. External Libraries or Applications
32
+        6. Usage
35 33
 
36 34
    List of Examples
37 35
 
38
-   1.1. Setting schema module parameter
36
+   1.1. Setting schema_path module parameter
39 37
    1.2. Setting keys module parameter
40 38
    1.3. Usage
41 39
 
... ...
@@ -44,25 +42,21 @@ Chapter 1. Admin Guide
44 42
    Table of Contents
45 43
 
46 44
    1. Overview
45
+   2. Limitations
46
+   3. Dependencies
47 47
 
48
-        1.1. Limitations
49
-
50
-   2. Dependencies
48
+        3.1. Kamailio Modules
51 49
 
52
-        2.1. Kamailio Modules
53
-        2.2. Parameters
50
+   4. Parameters
54 51
 
55
-              2.2.1. schema (string)
56
-              2.2.2. keys (string)
52
+        4.1. schema_path (string)
53
+        4.2. keys (string)
57 54
 
58
-        2.3. External Libraries or Applications
59
-
60
-   3. Usage
55
+   5. External Libraries or Applications
56
+   6. Usage
61 57
 
62 58
 1. Overview
63 59
 
64
-   1.1. Limitations
65
-
66 60
    This module provides a DB APIv1 connector for Redis server.
67 61
 
68 62
    It can be used as a replacement for other database modules such as
... ...
@@ -71,17 +65,20 @@ Chapter 1. Admin Guide
71 65
    specific modules. Also, for proper performance, the module needs
72 66
    particular configuration tailored to the using modules.
73 67
 
74
-   Since Redis does not provide a schema, a schema has to be defined as
75
-   module parameter "schema". The schema definition is composed of a
76
-   semi-column separated list of table definitions in format
77
-   <table-name>=<column-name>/<type>[<column-name>/<type> ...].
78
-
79
-   Example:
80
-        version=table_name/string,table_version/int;location=username/string,dom
81
-ain/string,contact/string,received/string,path/string,expires/timestamp,q/double
82
-,callid/string,cseq/int,last_modified/timestamp,flags/int,cflags/int,user_agent/
83
-string,socket/string,methods/int,ruid/string,reg_id/int,instance/string,server_i
84
-d/int,connection_id/int,keepalive/int,partition/int
68
+   Since Redis does not provide a schema by itself, db_redis ships with
69
+   schema files, which path has to be defined as module parameter
70
+   "schema_path". The schema definition is defined in one file per table
71
+   with the file name being the table name, and each file is composed of a
72
+   comma-separated list of column definitions in format
73
+   <column-name>/<type>[,<column-name>/<type> ...] in one line, followed
74
+   by a line holding the table version.
75
+
76
+   Example for location definition:
77
+username/string,domain/string,contact/string,received/string,path/string,expires
78
+/timestamp,q/double,callid/string,cseq/int,last_modified/timestamp,flags/int,cfl
79
+ags/int,user_agent/string,socket/string,methods/int,ruid/string,reg_id/int,insta
80
+nce/string,server_id/int,connection_id/int,keepalive/int,partition/int
81
+8
85 82
 
86 83
    Also since Redis is a key-value store with keys having to be unique,
87 84
    tables and rows e.g. from MySQL can not be ported 1:1 to Redis. For
... ...
@@ -98,85 +95,76 @@ d/int,connection_id/int,keepalive/int,partition/int
98 95
    keys/values the query is constructed by usrloc to look for the final
99 96
    entry key in the mapping set first, then querying the actual entries
100 97
    from there, avoiding full table scans. For usrloc, the same holds true
101
-   for exipired contacts, requiring a different kind of mapping. There is
102
-   a certain balance of read performance vs. write performance to
103
-   consider, because inserts and deletes also have to maintain the
104
-   mappings, in favor of much faster selects. The mappings can be freely
105
-   defined, so even though other kamailio modules don't require a specific
106
-   mapping to be in place for proper performance, mappings could be
107
-   defined for external applications to read faster (for instance letting
108
-   the acc module also write mappings besides the actual records for
109
-   billing systems to correlate start and stop records faster).
98
+   for expired contacts, requiring a different kind of mapping. There is a
99
+   certain balance of read performance vs. write performance to consider,
100
+   because inserts and deletes also have to maintain the mappings, in
101
+   favor of much faster selects. The mappings can be freely defined, so
102
+   even though other kamailio modules don't require a specific mapping to
103
+   be in place for proper performance, mappings could be defined for
104
+   external applications to read faster (for instance letting the acc
105
+   module also write mappings besides the actual records for billing
106
+   systems to correlate start and stop records faster).
110 107
 
111 108
    The mappings can be freely defined in the "keys" module parameter. It
112 109
    is composed of a semi-colon separated list of definitions in format
113 110
    <table-name>=<entry>:<column-name>[&<map-name>:<column-name>,<column-na
114
-   me>...]
111
+   me>...]. Each table must at least have an "entry" key for db_redis to
112
+   be able to store data.
115 113
 
116 114
    Example:
117
-        version=entry:table_name;location=entry:ruid&usrdom:username,domain&time
118
-r:partition,keepalive;acc=entry:callid,time_hires&cid:callid
115
+location=entry:ruid&usrdom:username,domain&timer:partition,keepalive;acc=entry:c
116
+allid,time_hires&cid:callid
119 117
 
120
-   Note that as of now, you have to have version information in your Redis
121
-   db, similar to your MySQL schema. To insert table versions (e.g. for
122
-   usrloc and acc), execute the following:
123
-        # redis-cli -h $host -n $dbnumber HMSET version:entry::location table_ve
124
-rsion 8
125
-        # redis-cli -h $host -n $dbnumber HMSET version:entry::acc table_version
126
- 5
118
+   For readability purposes, keys per table can be defined line by line by
119
+   providing multiple "keys" mod-params.
127 120
 
128 121
    You can read more about Redis at: https://www.redis.io.
129 122
 
130
-1.1. Limitations
123
+2. Limitations
131 124
 
132 125
      * This module has implemented the equivalent operations for INSERT,
133 126
        UPDATE, DELETE and SELECT. The ORDER BY for SELECT is not
134 127
        implemented. Raw query is not implemented inside this module, use
135
-       db_redis for sending any kind of command to a Redis server.
136
-
137
-2. Dependencies
138
-
139
-   2.1. Kamailio Modules
140
-   2.2. Parameters
128
+       ndb_redis for sending any kind of command to a Redis server.
141 129
 
142
-        2.2.1. schema (string)
143
-        2.2.2. keys (string)
130
+3. Dependencies
144 131
 
145
-   2.3. External Libraries or Applications
132
+   3.1. Kamailio Modules
146 133
 
147
-2.1. Kamailio Modules
134
+3.1. Kamailio Modules
148 135
 
149 136
    The following modules must be loaded before this module:
150 137
      * none.
151 138
 
152
-2.2. Parameters
139
+4. Parameters
153 140
 
154
-2.2.1. schema (string)
141
+   4.1. schema_path (string)
142
+   4.2. keys (string)
155 143
 
156
-   The schema of your tables.
144
+4.1. schema_path (string)
157 145
 
158
-   Example 1.1. Setting schema module parameter
159
-modparam("db_redis", "schema", "version=table_name/string,table_version/int;loca
160
-tion=username/string,domain/string,contact/string,received/string,path/string,ex
161
-pires/timestamp,q/double,callid/string,cseq/int,last_modified/timestamp,flags/in
162
-t,cflags/int,user_agent/string,socket/string,methods/int,ruid/string,reg_id/int,
163
-instance/string,server_id/int,connection_id/int,keepalive/int,partition/int")
146
+   The path to the schema of your tables (default
147
+   /usr/share/kamailio/db_redis).
164 148
 
165
-2.2.2. keys (string)
149
+   Example 1.1. Setting schema_path module parameter
150
+modparam("db_redis", "schema_path", "/usr/local/share/kamailio/db_redis/kamailio
151
+")
166 152
 
167
-   The lookup and mapping keys of your tables.
153
+4.2. keys (string)
154
+
155
+   The entry and mapping keys of your tables.
168 156
 
169 157
    Example 1.2. Setting keys module parameter
170 158
 modparam("db_redis", "keys", "version=entry:table_name;location=entry:ruid&usrdo
171 159
 m:username,domain&timer:partition,keepalive")
172 160
 
173
-2.3. External Libraries or Applications
161
+5. External Libraries or Applications
174 162
 
175 163
    The following libraries or applications must be installed before
176 164
    running Kamailio with this module loaded:
177 165
      * hiredis - available at https://github.com/redis/hiredis
178 166
 
179
-3. Usage
167
+6. Usage
180 168
 
181 169
    Load the module and set the the DB URL for specific modules to:
182 170
    redis://[username]@host:port/database. Username is optional. Database
... ...
@@ -186,14 +174,16 @@ m:username,domain&timer:partition,keepalive")
186 174
 ...
187 175
 loadmodule "db_redis.so"
188 176
 ...
189
-#!define DBURL "redis://127.0.0.1:6379/5"
177
+#!define DBURL_USRLOC "redis://127.0.0.1:6379/5"
178
+#!define DBURL_ACC    "redis://127.0.0.1:6379/6"
179
+#!define DBURL_AUTH   "redis://127.0.0.1:6379/7"
190 180
 ...
191
-modparam("db_redis", "schema", "version=table_name/string,table_version/int;loca
192
-tion=username/string,domain/string,contact/string,received/string,path/string,ex
193
-pires/timestamp,q/double,callid/string,cseq/int,last_modified/timestamp,flags/in
194
-t,cflags/int,user_agent/string,socket/string,methods/int,ruid/string,reg_id/int,
195
-instance/string,server_id/int,connection_id/int,keepalive/int,partition/int")
196
-modparam("db_redis", "keys", "version=entry:table_name;location=entry:ruid&usrdo
197
-m:username,domain&timer:partition,keepalive")
198
-modparam("usrloc", "db_url", DBURL)
181
+modparam("db_redis", "schema_path", "/usr/share/kamailio/db_redis/kamailio")
182
+modparam("db_redis", "keys", "location=entry:ruid&usrdom:username,domain&timer:p
183
+artition,keepalive")
184
+modparam("db_redis", "keys", "acc=entry:callid,time_hires&cid:callid")
185
+modparam("db_redis", "keys", "subscriber=entry:username,domain")
186
+modparam("usrloc", "db_url", DBURL_USRLOC)
187
+modparam("acc_db", "db_url", DBURL_ACC)
188
+modparam("auth_db", "db_url", DBURL_AUTH)
199 189
 ...
Browse code

db_redis: Implement db_redis generic db driver

This module implements a generic db driver for kamailio. It
requires a "schema" and "key" definition of "tables" and corresponding
keys for redis in the kamailio config file, otherwise it's supposed to
work with every module.

Implemented methods are query (w/o order-by), insert, update, delete.

Tested with usrloc and acc.

Andreas Granig authored on 07/02/2018 12:52:56
Showing 1 changed files
1 1
new file mode 100644
... ...
@@ -0,0 +1,199 @@
1
+DB_REDIS Module
2
+
3
+Andreas Granig
4
+
5
+   <agranig@sipwise.com>
6
+
7
+Edited by
8
+
9
+Andreas Granig
10
+
11
+   <agranig@sipwise.com>
12
+
13
+   Copyright © 2018 sipwise.com
14
+     __________________________________________________________________
15
+
16
+   Table of Contents
17
+
18
+   1. Admin Guide
19
+
20
+        1. Overview
21
+
22
+              1.1. Limitations
23
+
24
+        2. Dependencies
25
+
26
+              2.1. Kamailio Modules
27
+              2.2. Parameters
28
+
29
+                    2.2.1. schema (string)
30
+                    2.2.2. keys (string)
31
+
32
+              2.3. External Libraries or Applications
33
+
34
+        3. Usage
35
+
36
+   List of Examples
37
+
38
+   1.1. Setting schema module parameter
39
+   1.2. Setting keys module parameter
40
+   1.3. Usage
41
+
42
+Chapter 1. Admin Guide
43
+
44
+   Table of Contents
45
+
46
+   1. Overview
47
+
48
+        1.1. Limitations
49
+
50
+   2. Dependencies
51
+
52
+        2.1. Kamailio Modules
53
+        2.2. Parameters
54
+
55
+              2.2.1. schema (string)
56
+              2.2.2. keys (string)
57
+
58
+        2.3. External Libraries or Applications
59
+
60
+   3. Usage
61
+
62
+1. Overview
63
+
64
+   1.1. Limitations
65
+
66
+   This module provides a DB APIv1 connector for Redis server.
67
+
68
+   It can be used as a replacement for other database modules such as
69
+   db_mysql and db_postgres. Not all the specs of DB APIv1 are
70
+   implemented, thus the usage of this module might be restricted to
71
+   specific modules. Also, for proper performance, the module needs
72
+   particular configuration tailored to the using modules.
73
+
74
+   Since Redis does not provide a schema, a schema has to be defined as
75
+   module parameter "schema". The schema definition is composed of a
76
+   semi-column separated list of table definitions in format
77
+   <table-name>=<column-name>/<type>[<column-name>/<type> ...].
78
+
79
+   Example:
80
+        version=table_name/string,table_version/int;location=username/string,dom
81
+ain/string,contact/string,received/string,path/string,expires/timestamp,q/double
82
+,callid/string,cseq/int,last_modified/timestamp,flags/int,cflags/int,user_agent/
83
+string,socket/string,methods/int,ruid/string,reg_id/int,instance/string,server_i
84
+d/int,connection_id/int,keepalive/int,partition/int
85
+
86
+   Also since Redis is a key-value store with keys having to be unique,
87
+   tables and rows e.g. from MySQL can not be ported 1:1 to Redis. For
88
+   instance, usrloc relies on a key "username@domain", but it must not be
89
+   unique for being able to store multiple contacts per AoR. Thus,
90
+   db_redis supports mapping sets in a way for example for usrloc to have
91
+   a set with a key "username@domain", with its entries being unique keys
92
+   per contact being the ruid of a contact. Thus, one contact in usrloc
93
+   consists of a unique key "location:entry::example-ruid-1" being a hash
94
+   with the columns like username, domain, contact, path etc. In addition,
95
+   this unique key is stored in a set
96
+   "location:usrdom::exampleuser:exampledomain.org". When usrloc does a
97
+   lookup based on "username@domain", db_redis figures out via the
98
+   keys/values the query is constructed by usrloc to look for the final
99
+   entry key in the mapping set first, then querying the actual entries
100
+   from there, avoiding full table scans. For usrloc, the same holds true
101
+   for exipired contacts, requiring a different kind of mapping. There is
102
+   a certain balance of read performance vs. write performance to
103
+   consider, because inserts and deletes also have to maintain the
104
+   mappings, in favor of much faster selects. The mappings can be freely
105
+   defined, so even though other kamailio modules don't require a specific
106
+   mapping to be in place for proper performance, mappings could be
107
+   defined for external applications to read faster (for instance letting
108
+   the acc module also write mappings besides the actual records for
109
+   billing systems to correlate start and stop records faster).
110
+
111
+   The mappings can be freely defined in the "keys" module parameter. It
112
+   is composed of a semi-colon separated list of definitions in format
113
+   <table-name>=<entry>:<column-name>[&<map-name>:<column-name>,<column-na
114
+   me>...]
115
+
116
+   Example:
117
+        version=entry:table_name;location=entry:ruid&usrdom:username,domain&time
118
+r:partition,keepalive;acc=entry:callid,time_hires&cid:callid
119
+
120
+   Note that as of now, you have to have version information in your Redis
121
+   db, similar to your MySQL schema. To insert table versions (e.g. for
122
+   usrloc and acc), execute the following:
123
+        # redis-cli -h $host -n $dbnumber HMSET version:entry::location table_ve
124
+rsion 8
125
+        # redis-cli -h $host -n $dbnumber HMSET version:entry::acc table_version
126
+ 5
127
+
128
+   You can read more about Redis at: https://www.redis.io.
129
+
130
+1.1. Limitations
131
+
132
+     * This module has implemented the equivalent operations for INSERT,
133
+       UPDATE, DELETE and SELECT. The ORDER BY for SELECT is not
134
+       implemented. Raw query is not implemented inside this module, use
135
+       db_redis for sending any kind of command to a Redis server.
136
+
137
+2. Dependencies
138
+
139
+   2.1. Kamailio Modules
140
+   2.2. Parameters
141
+
142
+        2.2.1. schema (string)
143
+        2.2.2. keys (string)
144
+
145
+   2.3. External Libraries or Application