Merge remote branch 'remotes/origin/tma0/iptrtpproxy-v2'
[sip-router] / modules / db_mysql / README
1 mysql Module
2
3 Daniel-Constantin Mierla
4
5    <miconda@gmail.com>
6
7 Edited by
8
9 Daniel-Constantin Mierla
10
11    <miconda@gmail.com>
12
13    Copyright © 2006 Voice Sistem SRL
14      __________________________________________________________________
15
16    Table of Contents
17
18    1. Admin Guide
19
20         1. Overview
21         2. Dependencies
22
23               2.1. Kamailio Modules
24               2.2. External Libraries or Applications
25
26         3. Exported Parameters
27
28               3.1. ping_interval (integer)
29               3.2. timeout_interval (integer)
30               3.3. auto_reconnect (integer)
31
32         4. Exported Functions
33         5. Installation
34         6. Reading configuration from my.cnf
35
36    List of Examples
37
38    1.1. Set ping_interval parameter
39    1.2. Set timeout_interval parameter
40    1.3. Set auto_reconnect parameter
41    1.4. Set a my.cnf group in db_url parameter
42    1.5. Adding a kamailio group to my.cnf
43    1.6. Using [client] and specific group
44
45 Chapter 1. Admin Guide
46
47    Table of Contents
48
49    1. Overview
50    2. Dependencies
51
52         2.1. Kamailio Modules
53         2.2. External Libraries or Applications
54
55    3. Exported Parameters
56
57         3.1. ping_interval (integer)
58         3.2. timeout_interval (integer)
59         3.3. auto_reconnect (integer)
60
61    4. Exported Functions
62    5. Installation
63    6. Reading configuration from my.cnf
64
65 1. Overview
66
67    This is a module which provides MySQL connectivity for Kamailio. It
68    implements the DB API defined in Kamailio.
69
70 2. Dependencies
71
72    2.1. Kamailio Modules
73    2.2. External Libraries or Applications
74
75 2.1. Kamailio Modules
76
77    The following modules must be loaded before this module:
78      * No dependencies on other Kamailio modules.
79
80 2.2. External Libraries or Applications
81
82    The following libraries or applications must be installed before
83    running Kamailio with this module loaded:
84      * mysql - the development libraries forthe Mysql database. In some
85        Linux distributions named "libmysqlclient-dev".
86
87 3. Exported Parameters
88
89    3.1. ping_interval (integer)
90    3.2. timeout_interval (integer)
91    3.3. auto_reconnect (integer)
92
93 3.1. ping_interval (integer)
94
95    Time interval in seconds to send ping messages to MySQL server in order
96    to keep the connection open.
97
98    Default value is 300 (5 min).
99
100    Example 1.1. Set ping_interval parameter
101 ...
102 modparam("db_mysql", "ping_interval", 600)
103 ...
104
105 3.2. timeout_interval (integer)
106
107    Time interval (in seconds) after that an connection attempt, read or
108    write request is aborted. The value counts three times, as several
109    retries are done from the driver before it gives up.
110
111    The read timeout parameter is ignored on MySQL driver versions prior to
112    “5.1.12”, “5.0.25” and “4.1.22”. The write timeout parameter is ignored
113    on versions prior to “5.1.12” and “5.0.25”, the “4.1” release don't
114    support it at all.
115
116    Default value is 2 (6 sec).
117
118    Example 1.2. Set timeout_interval parameter
119 ...
120 modparam("db_mysql", "timeout_interval", 2)
121 ...
122
123 3.3. auto_reconnect (integer)
124
125    Configure whether the module should automatically reconnect to MySQL
126    server if the connection was lost.
127
128    Default value is 1 (1 - on / 0 - off).
129
130    Example 1.3. Set auto_reconnect parameter
131 ...
132 modparam("db_mysql", "auto_reconnect", 0)
133 ...
134
135 4. Exported Functions
136
137    No function exported to be used from configuration file.
138
139 5. Installation
140
141    Because it dependes on an external library, the mysql module is not
142    compiled and installed by default. You can use one of these options.
143      * - edit the "Makefile" and remove "db_mysql" from "excluded_modules"
144        list. Then follow the standard procedure to install Kamailio: "make
145        all; make install".
146      * - from command line use: 'make all include_modules="db_mysql"; make
147        install include_modules="db_mysql"'.
148
149 6. Reading configuration from my.cnf
150
151    In order to take into account specific mysql client options, a my.cnf
152    config group can be passed using the db_url module parameter. This is
153    done by setting [group] in front of or instead of the host part. The
154    following examples are valid db_url definitions, which include a my.cnf
155    group:
156      * mysql://user:pass@[group]host:port/db
157      * mysql://user:pass@[group]:port/db
158      * mysql://user:pass@[group]/db
159      * mysql://[group]/db
160
161    Example 1.4. Set a my.cnf group in db_url parameter
162 ...
163 modparam("usrloc", "db_url", "mysql://[kamailio]/kamailio)
164 ...
165
166    Example 1.5. Adding a kamailio group to my.cnf
167 ...
168 [kamailio]
169 socket = /path/to/mysql.sock
170 user = kamailiouser
171 password = kamailiopass
172 default-character-set = utf8
173 ...
174
175    In addition to the given group, also the [client] section is read, in
176    the order given in my.cnf. So if you for example specify a socket in
177    both your specific group and the client group, then the value is taken
178    from the last one.
179
180    Example 1.6. Using [client] and specific group
181 ...
182 [client]
183 socket = /var/run/mysql/mysqld.sock
184
185 [kamailio]
186 socket = /path/to/mysqld.sock
187 user = kamailiouser
188 password = kamailiopass
189 default-character-set = utf8
190 ...
191
192    In the example given above, the socket /path/to/mysqld.sock is used by
193    Kamailio because both [kamailio] and [client] define this option, and
194    the latter overwrites the first.