kamailio/modules/sqlops/README

SQLOps Module

Daniel-Constantin Mierla

   asipto.com
   <[email protected]>

Edited by

Daniel-Constantin Mierla

   <[email protected]>

   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:[email protected]/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.

   Example 1.5. sql_pvquery() usage
...
modparam("sqlops","sqlcon","ca=>dbdriver://username:password@dbhost/dbname")
...
sql_pvquery("ca", "select 'col1', 2, NULL, 'sip:[email protected]'",
        "$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...).
     * 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");
...