# &adminguide;

## 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.

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- a DB SQL module (mysql, postgres, ...).

### External Libraries or Applications

The following libraries or applications must be installed before running &kamailio; with this module loaded:

- None.

## Parameters

### `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.

#### Set `sqlcon` parameter

    ...
    modparam("sqlops","sqlcon","cb=>&defaultdb;")
    modparam("sqlops","sqlcon","ca=>&exampledb;")
    ...

### `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 declare 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.

#### Set `sqlres` parameter

    ...
    modparam("sqlops", "sqlres", "ra")
    ...

### `tr_buf_size` (int)

The size of the transformations for SQL operations.

Default value is 2048.

#### Set `tr_buf_size` parameter

    ...
    modparam("sqlops", "tr_buf_size", 4096)
    ...

### `log_buf_size` (int)

The size of the buffer (characters) when logging raw SQL operations.

Note: When the buffer is smaller than the SQL operation, the operation is logged truncated up to log_buf_size.

Default value is 128.

#### Set `log_buf_size` parameter

    ...
    modparam("sqlops", "log_buf_size", 4096)
    ...

### `connect_mode` (int)

Control how the module will connect to database. Values:

- 0 connect at start up or fail

- 1 connect at start up but continue even if connecting to database server fails

- 2 do not connect until needed (this will limit the amount of idle connections)

Default value is 0.

#### Set `connect_mode` parameter

    ...
    modparam("sqlops", "connect_mode", 1)
    ...

### `results_maxsize` (int)

Set the upper limit of how many result containers are going to be defined.

Note that a result container can be used for different SQL queries, it is not required to have result container per SQL query. Use different containers when the result records are needed at the same time (e.g., compare a field from one result with a field from another result).

Default value is 32.

#### Set `results_maxsize` parameter

    ...
    modparam("sqlops", "results_maxsize", 64)
    ...

## Functions

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

  3 - query successful, at least one row returned, but result parameter was not given

### `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.

#### `sql_query()` usage

    ...
    modparam("sqlops","sqlcon","ca=>&exampledb;")
    ...
    sql_query("ca", "select * from domain", "ra");
    xlog("number of rows in table domain: $dbr(ra=>rows)\n");
    sql_result_free("ra");
    ...

### `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.

#### `sql_xquery()` usage

    ...
    modparam("sqlops","sqlcon","ca=>&exampledb;")
    ...
    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");
    }
    ..

### `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)

#### `sql_pvquery()` usage

    ...
    modparam("sqlops","sqlcon","ca=>&exampledb;")
    ...
    sql_pvquery("ca", "select 'col1', 2, NULL, 'sip:test@example.com'",
    	"$var(a), $avp(col2), $xavp(item[0]=>s), $ru");
    ...

### `sql_result_free(result)`

Free data in SQL 'result'.

This function can be used from ANY_ROUTE.

#### `sql_result_free()` usage

    ...
    modparam("sqlops","sqlcon","ca=>&exampledb;")
    ...
    sql_query("ca", "select * from domain", "ra");
    xlog("number of rows in table domain: $dbr(ra=>rows)\n");
    ...
    sql_result_free("ra");
    ...

### `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 asynchronous 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.

#### `sql_query_async()` usage

    ...
    modparam("sqlops","sqlcon","ca=>&exampledb;")
    ...
    sql_query_async("ca", "delete from domain");
    ...

## Exported pseudo-variables

### `$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.

#### `$dbr(result=>key)` usage

    ...
    modparam("sqlops","sqlcon","ca=>&exampledb;")
    ...
    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)");
        }
    }
    ...

### `$sqlrows(con)`

Number of affected rows of the previous query on the specified connection. Its 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.

#### `$sqlrows(con)` usage

    ...
    modparam("sqlops","sqlcon","ca=>&exampledb;")
    ...
    sql_query("ca", "update domain set domain='mydomain' where id=5");
    xlog("Affected rows: $sqlrows(ca)\n");
    ...