mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
386 lines
12 KiB
386 lines
12 KiB
SQLOps Module
|
|
|
|
Daniel-Constantin Mierla
|
|
|
|
asipto.com
|
|
<miconda@gmail.com>
|
|
|
|
Edited by
|
|
|
|
Daniel-Constantin Mierla
|
|
|
|
<miconda@gmail.com>
|
|
|
|
Copyright © 2008 http://www.asipto.com
|
|
__________________________________________________________________
|
|
|
|
Table of Contents
|
|
|
|
1. Admin Guide
|
|
|
|
1. Overview
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
3. Parameters
|
|
|
|
3.1. sqlcon (str)
|
|
3.2. sqlres (str)
|
|
|
|
4. Functions
|
|
|
|
4.1. sql_query(connection, query[, result])
|
|
4.2. sql_xquery(connection, query, result)
|
|
4.3. sql_pvquery(connection, query, result)
|
|
4.4. sql_result_free(result)
|
|
4.5. sql_query_async(connection, query)
|
|
|
|
5. Exported pseudo-variables
|
|
|
|
5.1. $dbr(result=>key)
|
|
5.2. $sqlrows(con)
|
|
|
|
List of Examples
|
|
|
|
1.1. Set sqlcon parameter
|
|
1.2. Set sqlres parameter
|
|
1.3. sql_query() usage
|
|
1.4. sql_xquery() usage
|
|
1.5. sql_pvquery() usage
|
|
1.6. sql_result_free() usage
|
|
1.7. sql_query_async() usage
|
|
1.8. $dbr(result=>key) usage
|
|
1.9. $sqlrows(con) usage
|
|
|
|
Chapter 1. Admin Guide
|
|
|
|
Table of Contents
|
|
|
|
1. Overview
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
3. Parameters
|
|
|
|
3.1. sqlcon (str)
|
|
3.2. sqlres (str)
|
|
|
|
4. Functions
|
|
|
|
4.1. sql_query(connection, query[, result])
|
|
4.2. sql_xquery(connection, query, result)
|
|
4.3. sql_pvquery(connection, query, result)
|
|
4.4. sql_result_free(result)
|
|
4.5. sql_query_async(connection, query)
|
|
|
|
5. Exported pseudo-variables
|
|
|
|
5.1. $dbr(result=>key)
|
|
5.2. $sqlrows(con)
|
|
|
|
1. Overview
|
|
|
|
The SQLOPS module adds support for raw SQL queries in the configuration
|
|
file.
|
|
|
|
Among the features:
|
|
* Multiple database connections - the sqlops module can connect to
|
|
many databases on different servers using different DB driver
|
|
modules at the same time.
|
|
* Many query results - the module can store many results of different
|
|
SQL queries in separate structures at the same time. Thus it is
|
|
possible to work in parallel with several queries and results.
|
|
* Access via pseudo-variables - the content of the SQL query result
|
|
is accessible via pseudo-variables. Please note that only integer
|
|
and string variables are supported at the moment because of the
|
|
internal usage of “AVPs” to hold the values. So it is not possible
|
|
for example to return floating point or big integer values this
|
|
way.
|
|
* Array indexes - fast access to result values via array position:
|
|
[row,column].
|
|
* Persistence in process space - a result can be used many times in
|
|
the same worker process. Query once, use many times.
|
|
* Results can be stored in xavps - columns are accessed by their
|
|
names, rows by xavp index. Xavp's are available during the
|
|
transactions lifetime and don't need to be destroyed manually.
|
|
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
2.1. Kamailio Modules
|
|
|
|
The following modules must be loaded before this module:
|
|
* a DB SQL module (mysql, postgres, ...).
|
|
|
|
2.2. External Libraries or Applications
|
|
|
|
The following libraries or applications must be installed before
|
|
running Kamailio with this module loaded:
|
|
* None.
|
|
|
|
3. Parameters
|
|
|
|
3.1. sqlcon (str)
|
|
3.2. sqlres (str)
|
|
|
|
3.1. sqlcon (str)
|
|
|
|
The definition of a DB connection. The value of the parameter must have
|
|
the following format:
|
|
* "connection_name=>database_url"
|
|
|
|
This parameter may be set multiple times to get many DB connections in
|
|
the same configuration file.
|
|
* connection_name - string specifying the name of a database
|
|
connection. This string is used by the “sql_query()” function to
|
|
refer to the DB connection.
|
|
* database_url - Standardized Kamailio database URL used to connect
|
|
to database.
|
|
|
|
Default value is NULL.
|
|
|
|
Example 1.1. Set sqlcon parameter
|
|
...
|
|
modparam("sqlops","sqlcon","cb=>mysql://kamailio:abc@10.10.1.1/testdb")
|
|
modparam("sqlops","sqlcon","ca=>dbdriver://username:password@dbhost/dbname")
|
|
...
|
|
|
|
3.2. sqlres (str)
|
|
|
|
The definition of a database result ID. The value of the parameter can
|
|
be any string. Results IDs are also added at fixup time when
|
|
sql_query() parameters are parsed, so there is no need to decalare them
|
|
via module parameter unless you want to use them from within other
|
|
modules and be available in all application processes.
|
|
|
|
Default value is NULL.
|
|
|
|
Example 1.2. Set sqlres parameter
|
|
...
|
|
modparam("sqlops", "sqlres", "ra")
|
|
...
|
|
|
|
4. Functions
|
|
|
|
4.1. sql_query(connection, query[, result])
|
|
4.2. sql_xquery(connection, query, result)
|
|
4.3. sql_pvquery(connection, query, result)
|
|
4.4. sql_result_free(result)
|
|
4.5. sql_query_async(connection, query)
|
|
|
|
Note that sql_query(), sql_xquery() and sql_pvquery() functions have
|
|
the following return values:
|
|
* -1 - error in parameters or query execution
|
|
* 1 - query successful, at least one row in resultset (for SELECTs)
|
|
* 2 - query successful, no rows returned
|
|
|
|
4.1. sql_query(connection, query[, result])
|
|
|
|
Make an SQL query using 'connection' and store data in 'result'.
|
|
* connection - the name of the connection to be used for the query
|
|
(defined via the “sqlcon” parameter).
|
|
* query - SQL query string or pseudo-variables containing SQL query.
|
|
* result - string name to identify the result. Will be used by
|
|
$dbr(...) pseudo-variable to access result attributes. If omitted,
|
|
any resultset will be discarded. The result parameter should
|
|
normally only be omitted when no result is expected (INSERT,
|
|
UPDATE, DELETE).
|
|
|
|
This function can be used from ANY_ROUTE.
|
|
|
|
Example 1.3. sql_query() usage
|
|
...
|
|
modparam("sqlops","sqlcon","ca=>dbdriver://username:password@dbhost/dbname")
|
|
...
|
|
sql_query("ca", "select * from domain", "ra");
|
|
xlog("number of rows in table domain: $dbr(ra=>rows)\n");
|
|
sql_result_free("ra");
|
|
...
|
|
|
|
4.2. sql_xquery(connection, query, result)
|
|
|
|
Make an SQL query using 'connection' and store data in 'result' xavp.
|
|
* connection - the name of the connection to be used for the query
|
|
(defined via the “sqlcon” parameter).
|
|
* query - SQL query string or pseudo-variables containing SQL query.
|
|
* result - string name to identify the result xavp. Each row will be
|
|
added to this xavp, each column can be accessed by its name.
|
|
|
|
This function can be used from ANY_ROUTE.
|
|
|
|
Example 1.4. sql_xquery() usage
|
|
...
|
|
modparam("sqlops","sqlcon","ca=>dbdriver://username:password@dbhost/dbname")
|
|
...
|
|
sql_xquery("ca", "select * from domain", "ra");
|
|
xlog("first domain: $xavp(ra=>domain) with id: $xavp(ra=>domain_id)\n");
|
|
...
|
|
if (sql_xquery("ca", "select * from domain", "ra") == 1) {
|
|
xlog("domain: $xavp(ra=>domain) with id: $xavp(ra=>domain_id)\n");
|
|
}
|
|
..
|
|
|
|
4.3. sql_pvquery(connection, query, result)
|
|
|
|
Make an SQL query using 'connection' and store data in arbitrary pseudo
|
|
variables specified by 'result' parameter.
|
|
* connection - the name of the connection to be used for query
|
|
(defined via the “sqlcon” parameter).
|
|
* query - SQL query string or pseudo-variables containing SQL query.
|
|
* result - a list with PV names where to store the result. The format
|
|
is “$pv;$pv;...”. Every PV that is writable may be used (for
|
|
example $var, $avp, $xavp, $ru, $du, $sht, etc).
|
|
The PV are assigned values in the following order: last row to
|
|
first row, first field to last field. Assignment has the same
|
|
behavior as assigning in the script itself with one exception for
|
|
avp's, a NULL value will not delete an avp, but will be skipped
|
|
over.
|
|
Beware that if multiple rows are returned, non-(x)avp variables
|
|
will only hold the last added value, which corresponds to the first
|
|
returned row.
|
|
The value type of the PV (string or integer) will be derived from
|
|
the type of the columns. Please note that only these two datatypes
|
|
are supported, other datatypes will/may be converted to string.
|
|
|
|
This function can be used from ANY_ROUTE. Returns -1 on Error, 1 on
|
|
successful query, 2 if query provided no result set, 3 if result is
|
|
ignored (no result parameter given)
|
|
|
|
Example 1.5. sql_pvquery() usage
|
|
...
|
|
modparam("sqlops","sqlcon","ca=>dbdriver://username:password@dbhost/dbname")
|
|
...
|
|
sql_pvquery("ca", "select 'col1', 2, NULL, 'sip:test@example.com'",
|
|
"$var(a), $avp(col2), $xavp(item[0]=>s), $ru");
|
|
...
|
|
|
|
4.4. sql_result_free(result)
|
|
|
|
Free data in SQL 'result'.
|
|
|
|
This function can be used from ANY_ROUTE.
|
|
|
|
Example 1.6. sql_result_free() usage
|
|
...
|
|
modparam("sqlops","sqlcon","ca=>dbdriver://username:password@dbhost/dbname")
|
|
...
|
|
sql_query("ca", "select * from domain", "ra");
|
|
xlog("number of rows in table domain: $dbr(ra=>rows)\n");
|
|
...
|
|
sql_result_free("ra");
|
|
...
|
|
|
|
4.5. sql_query_async(connection, query)
|
|
|
|
Make an async SQL query using 'connection', if implemented by db driver
|
|
module (e.g., db_mysql). The query is executed in another process and
|
|
result is not available back to config, thus it should be used only for
|
|
sql statements that don't return values (e.g., insert, delete,
|
|
update...). Note that async_workers core parameter must be set in order
|
|
to enable the asyncronous framework needed by this function.
|
|
* connection - the name of the connection to be used for the query
|
|
(defined via “sqlcon” parameter).
|
|
* query - SQL query string or pseudo-variables containing SQL query.
|
|
|
|
This function can be used from ANY_ROUTE.
|
|
|
|
Example 1.7. sql_query_async() usage
|
|
...
|
|
modparam("sqlops","sqlcon","ca=>dbdriver://username:password@dbhost/dbname")
|
|
...
|
|
sql_query_async("ca", "delete from domain");
|
|
...
|
|
|
|
5. Exported pseudo-variables
|
|
|
|
5.1. $dbr(result=>key)
|
|
5.2. $sqlrows(con)
|
|
|
|
5.1. $dbr(result=>key)
|
|
|
|
Access hash table entries.
|
|
|
|
The “result” must be the name identifying a SQL result (third parameter
|
|
of sql_query(...)).
|
|
|
|
The “key” can be:
|
|
* rows - return the number of rows in query result
|
|
* cols - return the number of columns in the result.
|
|
* [row,col] - return the value at position (row,col) in the result
|
|
set. 'row' and 'col' must be integer or pseudo-variable holding an
|
|
integer.
|
|
* colname[N] - return the name of the N-th column in the result set.
|
|
|
|
Example 1.8. $dbr(result=>key) usage
|
|
...
|
|
modparam("sqlops","sqlcon","ca=>dbdriver://username:password@dbhost/dbname")
|
|
...
|
|
sql_query("ca", "select * from domain", "ra");
|
|
xlog("rows: $dbr(ra=>rows) cols: $dbr(ra=>cols)\n");
|
|
if($dbr(ra=>rows)>0)
|
|
{
|
|
$var(i) = 0;
|
|
while($var(i)<$dbr(ra=>cols))
|
|
{
|
|
xlog("--- SCRIPT: column[$var(i)] = $dbr(ra=>colname[$var(i)])\n");
|
|
$var(i) = $var(i) + 1;
|
|
}
|
|
$var(i) = 0;
|
|
while($var(i)<$dbr(ra=>rows))
|
|
{
|
|
$var(j) = 0;
|
|
while($var(j)<$dbr(ra=>cols))
|
|
{
|
|
xlog("[$var(i),$var(j)] = $dbr(ra=>[$var(i),$var(j)])\n");
|
|
$var(j) = $var(j) + 1;
|
|
}
|
|
$var(i) = $var(i) + 1;
|
|
}
|
|
}
|
|
sql_result_free("ra");
|
|
...
|
|
|
|
|
|
...
|
|
if (sql_xquery("ca", "select * from domain", "ra") == 1)
|
|
{
|
|
# non-destructive iteration
|
|
$var(i) = 0;
|
|
while($xavp(ra[$var(i)]) != $null)
|
|
{
|
|
xlog("[id, domain] = [$xavp(ra[$var(i)]=>id), $xavp(ra[$var(i)]=>domain)
|
|
]\n");
|
|
$var(i) = $var(i) + 1;
|
|
}
|
|
|
|
# destructive iteration
|
|
while($xavp(ra) != $null)
|
|
{
|
|
xlog("[id, domain] = [$xavp(ra=>id), $xavp(ra=>domain)]\n");
|
|
pv_unset("$xavp(ra)");
|
|
}
|
|
}
|
|
...
|
|
|
|
5.2. $sqlrows(con)
|
|
|
|
Number of affected rows of the previous query on the specified
|
|
connection. It's primary use is to get the number of rows affected by
|
|
UPDATE, INSERT and DELETE queries.
|
|
|
|
“con” must be the name identifying a DB connection.
|
|
|
|
Example 1.9. $sqlrows(con) usage
|
|
...
|
|
modparam("sqlops","sqlcon","ca=>dbdriver://username:password@dbhost/dbname")
|
|
...
|
|
sql_query("ca", "update domain set domain='mydomain' where id=5");
|
|
xlog("Affected rows: $sqlrows(ca)\n");
|
|
...
|