Table of Contents
db_url (string)usr_table (string)db_scheme (string)use_domain (integer)ps_id_max_buf_len (integer)uuid_column (string)username_column (string)domain_column (string)attribute_column (string)value_column (string)type_column (string)db_query(query, [res_col_avps], [db_id])
db_query_one(query, [res_col_vars], [db_id])
db_select([columns],table,[filter],[order],[res_col_avps], [db_id])
db_select_one([columns],table,[filter],[order],[res_col_vars], [db_id])
db_update(columns,table,[filter],[db_id])
db_insert(table,columns,[db_id])
db_delete(table,[filter],[db_id])
db_replace(table,columns,[db_id])
db_avp_load(source, name, [db_id], [prefix]])
db_avp_store(source, name, [db_id])
db_avp_delete(source, name, [db_id])
List of Tables
List of Examples
db_url parameterusr_table parameterdb_scheme parameter
use_domain parameter
ps_id_max_buf_len parameter
uuid_column parameterusername_column parameterdomain_column parameterattribute_column parameter
value_column parameter
type_column parameter
db_query usagedb_query_one usagedb_select usagedb_select_one usagedb_update usagedb_insert usagedb_delete usagedb_avp_load usagedb_avp_store usagedb_avp_delete usageasync db_query usageasync db_query_one usageDBops (DB-operations) modules implements a set of script functions for generic SQL standard queries (raw or structure queries). It also provides a dedicated set of functions for DB manipulation (loading/storing/removing) of user AVPs (preferences).
DB URL for database connection. As the module allows the usage of multiple DBs (DB URLs), the actual DB URL may be preceded by an reference number. This reference number is to be passed to AVPOPS function that what to explicitly use this DB connection. If no reference number is given, 0 is assumed - this is the default DB URL.
This parameter is optional, it's default value being NULL.
Example 1.1. Set db_url parameter
...
# default URL
modparam("dbops","db_url","mysql://user:passwd@host/database")
# an additional DB URL
modparam("dbops","db_url","1 postgres://user:passwd@host2/opensips")
...
DB table to be used for user preferences (AVPs)
This parameter is optional, it's default value being “usr_preferences”.
Definition of a DB scheme to be used for accessing a non-standard User Preference -like table.
Definition of a DB scheme. Scheme syntax is:
db_scheme = name':'element[';'element]*
element =
'uuid_col='string
'username_col='string
'domain_col='string
'value_col='string
'value_type='('integer'|'string')
'table='string
Default value is “NULL”.
Example 1.3. Set db_scheme parameter
...
modparam("dbops","db_scheme",
"scheme1:table=subscriber;uuid_col=uuid;value_col=first_name")
...
If the domain part of the a SIP URI should be used for identifying an AVP in DB operations.
Default value is 0 (no).
The maximum size of the buffer used to build the query IDs which are used for managing the Prepare Statements when comes to the "db_select|update|insert|replace|delete()" functions
If the size is exceeded (when trying to build the PS query ID), the PS support will be dropped for the query. If set to 0, the PS support will be completly disabled.
Default value is 1024.
Name of column containing the uuid (unique user id).
Default value is “uuid”.
Name of column containing the username.
Default value is “username”.
Name of column containing the domain name.
Default value is “domain”.
Name of column containing the attribute name (AVP name).
Default value is “attribute”.
Example 1.9. Set attribute_column parameter
...
modparam("dbops","attribute_column","attribute")
...
Name of column containing the AVP value.
Default value is “value”.
Make a database query and store the result in AVPs.
The meaning and usage of the parameters:
query (string) - must be a valid SQL query. The parameter can contain pseudo-variables.
You must escape any pseudo-variables manually to prevent SQL injection attacks. You can use the existing transformations escape.common and unescape.common to escape and unescape the content of any pseudo-variable. Failing to escape the variables used in the query makes you vulnerable to SQL injection, e.g. make it possible for an outside attacker to alter your database content. The function returns true if the query was successful, -2 in case the query returned an empty result set, and -1 for all other types of errors.
res_col_avps (string, optional, no expand) - a list with AVP names where to store the result. The format is “$avp(name1);$avp(name2);...”. If this parameter is omitted, the result is stored in “$avp(1);$avp(2);...”. If the result consists of multiple rows, then multiple AVPs with corresponding names will be added. The value type of the AVP (string or integer) will be derived from the type of the columns. If the value in the database is NULL, the returned avp will be a string with the <null> value.
db_id (int, optional) - reference to a defined DB URL (a numerical id) - see the “db_url” module parameter. It can be either a constant, or a string/int variable.
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE, LOCAL_ROUTE and ONREPLY_ROUTE.
Example 1.12. db_query usage
...
db_query("SELECT password, ha1 FROM subscriber WHERE username='$tu'",
"$avp(pass);$avp(hash)");
db_query("DELETE FROM subscriber");
db_query("DELETE FROM subscriber", , 2);
$avp(id) = 2;
db_query("DELETE FROM subscriber", , $avp(id));
...
Similar to db_query(), it makes a generic raw database query and returns the results, but with the following differences:
returns only one row - even if the query results in a multi row result, only the first row will be returned to script.
return variables are not limited to AVPs - the variables for returning the query result may any kind of variable, of course, as time as it is writeable. NOTE that the number of return vairable MUST match (as number) the number of returned columns. If less variables are provided, the query will fail.
NULL is returned - any a DB NULL value resulting from the query will be pushed as NULL indicator (and NOT as <null> string) to the script variables.
This function can be used from any type of route.
Example 1.13. db_query_one usage
...
db_query_one("SELECT password, ha1 FROM subscriber WHERE username='$tU'",
"$var(pass);$var(hash)");
# $var(pass) or $var(hash) may be NULL if the corresponding columns
# are not populated
...
db_query_one("SELECT value, type FROM usr_preferences WHERE username='$fU' and attribute='cfna'",
"$var(cf_uri);$var(type)");
# the above query will return only one row, even if there are multiple `cfna`
# attributes for the user
...
Function to perform a structured (not raw) SQL SELECT operation. The query is performed via OpenSIPS internal SQL interface, taking advantages of the prepared-statements support (if the db backend provides something like that). The selected columns are returned into a set of AVPs (one to one matching the selected columns).
If using varibales in constructing the query, you must manually escape their values in order to prevent SQL injection attacks. You can use the existing transformations escape.common and unescape.common to escape and unescape the content of any pseudo-variable. Failing to escape the variables used in the query makes you vulnerable to SQL injection, e.g. make it possible for an outside attacker to alter your database content.
The function returns true if the query was successful, -2 in case the query returned an empty result set, and -1 for all other types of errors.
The meaning and usage of the parameters:
columns (string,optional) - JSON formated string holding an array of columns to be returned by the select. Ex: “["col1","col2"]”. If missing, a “*” (all columns) select will be performed.
table (string, mandatory) - the name of the table to be queried.
filter (string, optional) - JSON formated string holding the "where" filter of the query. This must be an array of (column, operator,value) pairs. The exact JSON syntax of such a pair is “{"column":{"operator":"value"}}”.; operators may be `>`, `<`, `=`, `!=` or custom string; The values may be string, integer or `null`. To simplify the usage with the `=` operator, you can use “{"column":"value"}” If missing, all rows will be selected.
order (string, optional) - the name of the column to oder by (only ascending).
res_col_avps (string, optional, no expand) - a list with AVP names where to store the result. The format is “$avp(name1);$avp(name2);...”. If this parameter is omitted, the result is stored in “$avp(1);$avp(2);...”. If the result consists of multiple rows, then multiple AVPs with corresponding names will be added. The value type of the AVP (string or integer) will be derived from the type of the columns. If the value in the database is NULL, the returned avp will be a string with the <null> value.
db_id (int, optional) - reference to a defined DB URL (a numerical id) - see the db_url module parameter. It can be either a constant, or a string/int variable.
This function can be used from any type of route.
Example 1.14. db_select usage
...
db_select('["password","ha1"]', 'subscriber',
'[ {"username", "$tu"}, {"domain",{"!=",null}}]', ,
'$avp(pass);$avp(hash)');
...
Similar to db_select(), it makes a SELECT SQL query and returns the results, but with the following differences:
returns only one row - even if the query results in a multi row result, only the first row will be returned to script.
return variables are not limited to AVPs - the variables for returning the query result may any kind of variable, of course, as time as it is writeable. NOTE that the number of return vairable MUST match (as number) the number of returned columns. If less variables are provided, the query will fail.
NULL is returned - any a DB NULL value resulting from the query will be pushed as NULL indicator (and NOT as <null> string) to the script variables.
This function can be used from any type of route.
Example 1.15. db_select_one usage
...
db_select_one('["value","type"]', 'usr_preferences',
'[ {"username", "$tu"}, {"attribute","cfna"}]', ,
'$var(cf_uri);$var(type)');
# the above query will return only one row, even if there are multiple `cfna`
# attributes for the user
...
Function to perform a structured (not raw) SQL UPDATE operation. IMPORTANT: please see all the general notes from the db_select() function.
The function returns true if the query was successful.
The meaning and usage of the parameters:
columns (string,mandatory) - JSON formated string holding an array of (column,value) pairs to be updated by the query. Ex: “[{"col1":"val1"},{"col2":"val1"}]”.
table (string, mandatory) - the name of the table to be queried.
filter (string, optional) - JSON formated string holding the "where" filter of the query. This must be an array of (column, operator,value) pairs. The exact JSON syntax of such a pair is “{"column":{"operator":"value"}}”.; operators may be `>`, `<`, `=`, `!=` or custom string; The values may be string, integer or `null`. To simplify the usage with the `=` operator, you can use “{"column":"value"}” If missing, all rows will be updated.
db_id (int, optional) - reference to a defined DB URL (a numerical id) - see the db_url module parameter. It can be either a constant, or a string/int variable.
This function can be used from any type of route.
Example 1.16. db_update usage
...
db_update( '[{"password":"my_secret"}]', 'subscriber',
'[{"username", "$tu"}]');
...
Function to perform a structured (not raw) SQL INSERT operation. IMPORTANT: please see all the general notes from the db_select() function.
The function returns true if the query was successful.
The meaning and usage of the parameters:
table (string, mandatory) - the name of the table to be queried.
columns (string,mandatory) - JSON formated string holding an array of (column,value) pairs to be inserted. Ex: “[{"col1":"val1"},{"col2":"val1"}]”.
db_id (int, optional) - reference to a defined DB URL (a numerical id) - see the db_url module parameter. It can be either a constant, or a string/int variable.
This function can be used from any type of route.
Example 1.17. db_insert usage
...
db_insert( 'cc_agents', '[{"agentid":"agentX"},{"skills":"info"},{"location":null},{"msrp_location":"sip:agentX@opensips.com"},{"msrp_max_sessions":2}]' );
...
Function to perform a structured (not raw) SQL DELETE operation. IMPORTANT: please see all the general notes from the db_select() function.
The function returns true if the query was successful.
The meaning and usage of the parameters:
table (string, mandatory) - the name of the table to delete from.
filter (string, optional) - JSON formated string holding the "where" filter of the query. This must be an array of (column, operator,value) pairs. The exact JSON syntax of such a pair is “{"column":{"operator":"value"}}”.; operators may be `>`, `<`, `=`, `!=` or custom string; The values may be string, integer or `null`. To simplify the usage with the `=` operator, you can use “{"column":"value"}” If missing, all rows will be updated.
db_id (int, optional) - reference to a defined DB URL (a numerical id) - see the db_url module parameter. It can be either a constant, or a string/int variable.
This function can be used from any type of route.
Function very similar to db_insert() function, but performing an SQL REPLACE operation instead. Note that not all SQL backend in OpenSIPS may support a REPLACE operation.
The function returns true if the query was successful.
Loads from DB into memory the AVPs corresponding to the given source. If given, it sets the script flags for loaded AVPs. It returns true if it loaded some values in AVPs, false otherwise (db error, no avp loaded ...).
AVPs may be preceded by an optional prefix, in order to avoid some conflicts.
Meaning of the parameters is as follows:
source (string, no expand) - what info is used for identifying the AVPs. Parameter syntax:
source = (pvar|str_value) ['/'('username'|'domain'|'uri'|'uuid')])
pvar = any pseudo variable defined in OpenSIPS. If the pvar is $ru (request uri), $fu (from uri), $tu (to uri) or $ou (original uri), then the implicit flag is 'uri'. Otherwise, the implicit flag is 'uuid'.
name (string, no expand) - which AVPs will be loaded from DB into memory. Parameter syntax is:
name = avp_spec['/'(table_name|'$'db_scheme)]
db_id (int, optional) - reference to a defined DB URL (a numerical id) - see the “db_url” module parameter.
prefix (string, optional) - static string which will precede the names of the AVPs populated by this function.
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE, LOCAL_ROUTE and ONREPLY_ROUTE.
Example 1.19. db_avp_load usage
...
db_avp_load("$fu", "$avp(678)");
db_avp_load("$ru/domain", "i/domain_preferences");
db_avp_load("$avp(uuid)", "$avp(404fwd)/fwd_table");
db_avp_load("$ru", "$avp(123)/$some_scheme");
# use DB URL id 3
db_avp_load("$ru", "$avp(1)", 3);
# precede all loaded AVPs by the "caller_" prefix
db_avp_load("$ru", "$avp(100)", , "caller_");
xlog("Loaded: $avp(caller_100)\n");
...
Stores to DB the AVPs corresponding to the given source.
The meaning and usage of the parameters are identical as for db_avp_load(source, name) function. Please refer to its description.
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE, LOCAL_ROUTE and ONREPLY_ROUTE.
Example 1.20. db_avp_store usage
...
db_avp_store("$tu", "$avp(678)");
db_avp_store("$ru/username", "$avp(email)");
# use DB URL id 3
db_avp_store("$ru", "$avp(1)", 3);
...
Deletes from DB the AVPs corresponding to the given source.
The meaning and usage of the parameters are identical as for db_avp_load(source, name) function. Please refer to its description.
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE, LOCAL_ROUTE and ONREPLY_ROUTE.
Example 1.21. db_avp_delete usage
...
db_avp_delete("$tu", "$avp(678)");
db_avp_delete("$ru/username", "$avp(email)");
db_avp_delete("$avp(uuid)", "$avp(404fwd)/fwd_table");
# use DB URL id 3
db_avp_delete("$ru", "$avp(1)", 3);
...
This function takes the same parameters and behaves identically to db_query(), but asynchronously (after launching the query, the current SIP worker pauses the execution of the current SIP message until the result is available and attempts to process more SIP traffic).
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE, LOCAL_ROUTE and ONREPLY_ROUTE.
Example 1.22. async db_query usage
...
{
...
/* Example of a slow MySQL query - it should take around 5 seconds */
async(
db_query(
"SELECT table_name, table_version, SLEEP(0.1) from version",
"$avp(tb_name); $avp(tb_ver); $avp(retcode)"),
my_resume_route);
/* script execution is halted right after the async() call */
}
/* We will be called when data is ready - meanwhile, the worker is free */
route [my_resume_route]
{
xlog("Results: \n$(avp(tb_name)[*])\n
-------------------\n$(avp(tb_ver)[*])\n
-------------------\n$(avp(retcode)[*])\n");
}
...
This function takes the same parameters and behaves identically to db_query_one(), but asynchronously (after launching the query, the current SIP worker pauses the execution of the current SIP message until the result is available and attempts to process more SIP traffic).
This function can be used from any route.
Example 1.23. async db_query_one usage
...
{
...
/* Example of a slow MySQL query - it should take around 5 seconds */
async(
db_query_one(
"SELECT table_name, table_version, SLEEP(0.1) from version",
"$var(tb_name); $var(tb_ver); $var(retcode)"),
my_resume_route);
/* script execution is halted right after the async() call */
}
/* We will be called when data is ready - meanwhile, the worker is free */
route [my_resume_route]
{
xlog("Result: $var(tb_name) | $var(tb_ver) | $(var(retcode)\n");
}
...
Table 2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
| Name | DevScore | Commits | Lines ++ | Lines -- | |
|---|---|---|---|---|---|
| 1. | Bogdan-Andrei Iancu (@bogdan-iancu) | 33 | 3 | 3495 | 18 |
(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)
(2) including any documentation-related commits, excluding merge commits. Regarding imported patches/code, we do our best to count the work on behalf of the proper owner, as per the "fix_authors" and "mod_renames" arrays in opensips/doc/build-contrib.sh. If you identify any patches/commits which do not get properly attributed to you, please submit a pull request which extends "fix_authors" and/or "mod_renames".
(3) ignoring whitespace edits, renamed files and auto-generated files
Table 2.2. Most recently active contributors(1) to this module
| Name | Commit Activity | |
|---|---|---|
| 1. | Bogdan-Andrei Iancu (@bogdan-iancu) | Feb 2024 - Mar 2024 |
(1) including any documentation-related commits, excluding merge commits
Last edited by: Bogdan-Andrei Iancu (@bogdan-iancu).
Documentation Copyrights:
Copyright © 2009-2024 www.opensips-solutions.com
Copyright © 2004-2008 Voice Sistem SRL