Merge kamailio modules into sip-router master branch
[sip-router] / doc / seruser / db_fifo.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
3    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4
5 <section id="db_fifo" xmlns:xi="http://www.w3.org/2001/XInclude">
6     <sectioninfo>
7         <revhistory>
8             <revision>
9                 <revnumber>$Revision$</revnumber>
10                 <date>$Date$</date>
11             </revision>
12         </revhistory>
13     </sectioninfo>
14
15     <title>Database FIFO interface</title>
16
17     <section id="db_fifo_intro">
18         <title>Introduction</title>
19         <para>
20         <application>SER</application> offers to its module developers a common 
21         DataBase(DB) interface, disregarding the database implementation (mysql, 
22         dbtext or postgres) that lays beneath it.
23         </para>
24         <para>
25         This feature is now extended and offered also to the 
26         <application>SER</application> users/administrators by DataBase
27         <acronym>FIFO</acronym> Interface (or DB FIFO interface). So,
28         DB FIFO interface is an extension of the internal DB interface through the
29         FIFO server. Everybody from outside <application>SER</application> can 
30         operate SER's database (for adding/removing users, for manipulating 
31         aliases, access control wrights, etc) using the same FIFO commands 
32         without caring about the database type that's used by SER.
33         </para>
34     </section>
35
36     <section id="advantages">
37         <title>Advantages</title>
38         <para>
39         All external applications that need to work with SER's database (like 
40         <application>serctl</application> or <application>serweb</application>) 
41         can do so via DB FIFO interface without depending of a specific database 
42         driver. No modifications will be required when a new type of database 
43         will be added to <application>SER</application>.
44         </para>
45         <para>
46         Also, this approach, prevents any kind of confusion between the database
47         type used by <application>SER</application> and the one used by these 
48         external applications. They will use automatically the same database as 
49         <application>SER</application> is configure to use.
50         </para>
51     </section>
52     
53
54     <section id="limitations">
55         <title>Limitations</title>
56         <para>
57         DB FIFO interface is restricted to the limitation of the internal DB
58         interface.
59         </para>
60         <para>
61         Also the size (can fit on only one line) and the content (\n or \r
62         characters must be escaped) of a BLOB value is restricted.
63         </para>
64     </section>
65
66     <section id="db_fifo_config">
67         <title>Configuration</title>
68         <para>
69         FIFO server presents is required, so configure in your config file the FIFO
70         file to be used by the <application>SER</application> FIFO server:
71         <programlisting>
72 fifo="/tmp/ser_fifo"
73         </programlisting>
74         To enable the DB FIFO interface, it's required to load at least one 
75         database module (available for the moment are mysql, dbtext and postgres).
76         </para>
77         <para>
78         The database module that you want to use and the database configuration are
79         configured via parameter <varname>fifo_db_url</varname>:
80         <programlisting>
81 fifo_db_url="mysql:mysql_url"
82 fifo_db_url="dbtext:dbtext_url"
83         </programlisting>
84         The format of the database URL depends of the used database implementation
85         (see the documentation for each DB type).
86         </para>
87         <para><emphasis>
88         NOTE: be sure to load the module the is specified into fifo_db_url!
89         </emphasis></para>
90         <para>
91         If no fifo_db_url is specified or no appropriate DB module found, the 
92         DB FIFO interface will be disabled.
93         </para>
94     </section>
95
96
97     <section id="db_fifo_commands">
98         <title>DB FIFO commands</title>
99         <para>
100         From FIFO point of view, all DB FIFO commands are mapped with the 
101         same name: <emphasis>DB</emphasis>. The first line of the command must 
102         contain the name of the DB command. Available are:
103         <itemizedlist>
104                 <listitem>
105                         <para>SELECT</para>
106                 </listitem>
107                 <listitem>
108                         <para>UPDATE</para>
109                 </listitem>
110                 <listitem>
111                         <para>INSERT</para>
112                 </listitem>
113                 <listitem>
114                         <para>DELETE</para>
115                 </listitem>
116                 <listitem>
117                         <para>RAW_QUERY</para>
118                 </listitem>
119                 <listitem>
120                         <para>EAW_QUERY_RES</para>
121                 </listitem>
122         </itemizedlist>
123             The grammar used in the commands definition can be found in next
124             section "DB FIFO grammar". The presence of the
125             <varname>reply_fifo_file</varname> in the FIFO command is
126             <emphasis>required</emphasis> for all commands.
127         </para>
128
129         <section>
130                 <title><function>SELECT</function> command</title>
131                 <para>
132                 This function implements SELECT DB directive. Its syntax is:
133                 <programlisting>
134 :DB:reply_fifo_file
135 select
136 [COLUMN]*
137 .
138 TABLE_NAME
139 [CVP]
140 .
141                 </programlisting>
142                 If no CVP line is present, the whole table.will be returned. If no 
143                 COLUMN line is given, all table columns will be found in the result.
144                 </para>
145                 <para>
146                 The result of the query will be return via reply_fifo_file  in one 
147                 raw per line format (only requested columns), the first line being 
148                 the head of the table. The <emphasis>NULL</emphasis> values will be
149                 printed as "NULL".
150                 </para>
151         </section>
152
153         <section id="insert">
154                 <title><function>INSERT</function> command</title>
155                 <para>
156                 This function implements INSERT DB directive - inserts one row in 
157                 a table. Its syntax is:
158                 <programlisting>
159 :DB:reply_fifo_file
160 insert
161 TABLE_NAME
162 [EQUAL_CVP]+
163 .
164                 </programlisting>
165                 </para>
166                 <para>
167                 Command returns nothing if success or, other way, an error message.
168                 </para>
169         </section>
170
171
172         <section id="update">
173                 <title><function>UPDATE</function> command</title>
174                 <para>
175                 The function implements UPDATE DB directive - it is possible to 
176                 modify one or more rows in a table. Its syntax is:
177                 <programlisting>
178 :DB:reply_fifo_file
179 update
180 [EQUAL_CVP]+
181 .
182 TABLE_NAME
183 [CVP]*
184 .
185                 </programlisting>
186                 </para>
187                 <para>
188                 Command returns nothing if success or, other way, an error message.
189                 </para>
190         </section>
191
192
193         <section id="delete">
194                 <title><function>DELETE</function> command</title>
195                 <para>
196                 This function implements DELETE DB directive - it is possible to 
197                 delete one or more rows from a table. Its syntax is:
198                 <programlisting>
199 :DB:reply_fifo_file
200 delete
201 TABLE_NAME
202 [CVP]*
203 .
204                 </programlisting>
205                 If CVP list contain <emphasis>no lines, all rows will be
206                 deleted</emphasis> (table will be empty).
207                 </para>
208                 <para>
209                 Command returns nothing if success or, other way, an error message.
210                 </para>
211         </section>
212
213
214         <section id="raw_query">
215                 <title><function>RAW_QUERY</function> command</title>
216                 <para>
217                 This function sends a raw query directly to the database driver 
218                 without trying to understand the command. This command <emphasis>MUST
219                 NOT</emphasis> generate any response.Otherwise, the database driver 
220                 can block or desynchronize (depending of the driver).
221                 Its syntax is:
222                 <programlisting>
223 :DB:reply_fifo_file
224 raw_query
225 (ASCII)+
226                 </programlisting>
227             </para>
228             <para>
229                 Command returns nothing if success or, other way, an error message.
230             </para>
231         </section>
232
233
234         <section id="raw_query_res">
235             <title>
236                 <function>RAW_QUERY_RES</function> command
237             </title>
238             <para>
239                 This function sends a raw query directly to the database driver without
240                 trying to understand the command. This command <emphasis>MUST
241                 </emphasis> generate an response (even if an empty one). Otherwise, 
242                 the database driver can block or desynchronize (depending of the 
243                 driver). Its syntax is:
244                 <programlisting>
245 :DB:reply_fifo_file
246 raw_query_res
247 (ASCII)+
248                 </programlisting>
249             </para>
250             <para>
251                 Command's output format is identical with the one from 
252                 <function>SELECT</function> command.
253             </para>
254         </section>
255     </section>
256
257
258     <section id="db_fifo_grammar">
259         <title>DB FIFO grammar</title>
260         <programlisting>
261 <![CDATA[
262 COLUMN=(alfa-numeric|'_')+
263
264 GAP=' '|'\t'
265
266 DEF_OP='='|'<'|'>'|'>='|'<='
267 UNDEF_OP=(ASCII)+
268 CAST_OP="int"|"double"|"string"|"date"|"blob"|"bitmap"
269
270 INT_VAL=integer number
271 DOUBLE_VAL=float number
272 STRING_VAL='"' ASCII* '"'
273 DATE_VAL='<' YEAR '-' MONTH '-' DAY ' ' HOUR ':' MINS ':' SECS '>'
274 BLOB_VAL=STRING_VAL
275 BITMAP_VAL=INT_VAL
276 NULL_VAL="null"
277
278 VALUE=('['CAST_OP']')?(INT_VAL|DOUBLE_VAL|STRING_VAL|DATE_VAL|
279                 BLOB_VAL|BITMAP_VAL|NULL_VAL)
280
281 CVP(column-value-pair)=
282                 (COLUMN GAP* DEF_OP GAP* VALUE) | (COLUMN GAP+ UNDEF_OP GAP+ VALUE)
283 EQUAL-CVP(column-equal-value-pair)=
284                 (COLUMN GAP* '=' GAP* VALUE)
285 ]]>
286         </programlisting>
287     </section>
288 </section>