SQL CACHER module
Admin Guide
Section titled “Admin Guide”Overview
Section titled “Overview”The sql_cacher module introduces the possibility to cache data from a SQL-based database (using different OpenSIPS modules which implement the DB API) into a cache system implemented in OpenSIPS through the CacheDB Interface. This is done by specifying the databases URLs, SQL table to be used, desired columns to be cached and other details in the OpenSIPS configuration script.
The cached data is available in the script through the read-only pseudovariable “$sql_cached_value” similar to a Key-Value system. A specified column from the SQL table has the role of “key” therefore the value of this column along with the name of a required column are provided as “parameters” to the pseudovariable returning the appropriate value of the column.
There are two types of caching available:
- full caching - the entire SQL table (all the rows) is loaded into the cache at OpenSIPS startup;
- on demand - the rows of the SQL table are loaded at runtime when appropriate keys are requested.
For on demand caching, the stored values have a configurable expire period after which they are permanently removed unless an MI reload function is called for a specific key. In the case of full caching the data is automatically reloaded at a configurable interval. Consequently if the data in the SQL database changes and a MI reload function is called, the old data remains in cache only until it expires.
Dependencies
Section titled “Dependencies”The following modules must be loaded before this module:
- The OpenSIPS modules that offer actual database back-end connection
Exported Parameters
Section titled “Exported Parameters”cache_table (string)
Section titled “cache_table (string)”This parameter can be set multiple times in order to cache multiple SQL tables or even the same table but with a different configuration. The module distinguishes those different entries by an “id” string.
The caching entry is specified via this parameter that has it’s own subparameters. Each of those parameters are separated by a delimiter configured by spec delimiter and have the following format: param_name=param_value The parameters are:
-
id : cache entry id
-
db_url : the URL of the SQL database
-
cachedb_url : the URL of the CacheDB database
-
table : SQL database table name
-
key : SQL database column name of the “key” column
-
key_type : data type for the SQL “key” column:
- string
- int
If not present, default value is “string”.
-
columns : names of the columns to be cached from the SQL database, separated by a delimiter configured by columns delimiter. If not present, all the columns from the table will be cached
-
on_demand : specifies the type of caching:
- 0 : full caching
- 1 : on demand
If not present, default value is “0”.
-
expire : expire period for the values stored in the cache for the on demand caching type in seconds If not present, default value is “1 hour”
The parameters must be given in the exact order specified above.
Overall, the parameter does not have a default value, it must be set at least once in order to cache any table.
modparam("sql_cacher", "cache_table","id=caching_namedb_url=mysql://root:opensips@localhost/opensips_2_2cachedb_url=mongodb:mycluster://127.0.0.1:27017/db.coltable=table_namekey=column_name_0columns=column_name_1 column_name_2 column_name_3on_demand=0")spec_delimiter (string)
Section titled “spec_delimiter (string)”The delimiter to be used in the caching entry specification provided in the cache_table parameter to separate the subparameters. It must be a single character.
The default value is newline.
modparam("sql_cacher", "spec_delimiter", "\n")pvar_delimiter (string)
Section titled “pvar_delimiter (string)”The delimiter to be used in the “$sql_cached_value” pseudovariable to separate the caching id, the desired column name and the value of the key. It must be a single character.
The default value is ”:“.
modparam("sql_cacher", "pvar_delimiter", " ")columns_delimiter (string)
Section titled “columns_delimiter (string)”The delimiter to be used in the columns subparameter of the caching entry specification provided in the cache_table parameter to separate the desired columns names. It must be a single character.
The default value is ” “(space).
modparam("sql_cacher", "columns_delimiter", ",")sql_fetch_nr_rows (integer)
Section titled “sql_fetch_nr_rows (integer)”The number of rows to be fetched into OpenSIPS private memory in one chunk from the SQL database driver. When querying large tables, adjust this parameter accordingly to avoid the filling of OpenSIPS private memory.
The default value is “100”.
modparam("sql_cacher", "sql_fetch_nr_rows", 1000)full_caching_expire (integer)
Section titled “full_caching_expire (integer)”Expire period for the values stored in cache for the full caching type in seconds. This is the longest time that deleted or modified data remains in cache.
The default value is “24 hours”.
modparam("sql_cacher", "full_caching_expire", 3600)reload_interval (integer)
Section titled “reload_interval (integer)”This parameter represents how many seconds before the data expires (for full caching) the automatic reloading is triggered.
The default value is “60 s”.
modparam("sql_cacher", "reload_interval", 5)Exported Functions
Section titled “Exported Functions”No function exported to be used from configuration file.
Exported MI Functions
Section titled “Exported MI Functions”sql_cacher_reload
Section titled “sql_cacher_reload”Reloads the entire SQL table in cache in full caching mode.
Reloads the given key or invalidates all the keys in cache in on demand mode.
Parameters:
- id - the caching entry’s id
- key (optional) - the specific key to be reloaded, only makes sense in on demand mode.
...$ opensips-cli -x mi sql_cacher_reload subs_caching...$ opensips-cli -x mi sql_cacher_reload subs_caching alice@domain.com...Exported Pseudo-Variables
Section titled “Exported Pseudo-Variables”$sql_cached_value(id{sep}col{sep}key)
Section titled “$sql_cached_value(id{sep}col{sep}key)”The cached data is available through this read-only PV.The format is the following:
- sep : separator configured by pvar delimiter
- id : cache entry id
- col : name of the required column
- key : value of the “key” column
...$avp(a) = $sql_cached_value(caching_name:column_name_1:key1);...Usage Example
Section titled “Usage Example”This section provides an usage example for the caching of an SQL table.
Suppose one in interested in caching the columns: “host_name”, “reply_code”, “flags” and “next_domain” from the “carrierfailureroute” table of the OpenSIPS database.
...+----+---------+-----------+------------+--------+-----+-------------+| id | domain | host_name | reply_code | flags | mask | next_domain |+----+---------+-----------+------------+-------+------+-------------+| 1 | 99 | | 408 | 16 | 16 | || 2 | 99 | gw1 | 404 | 0 | 0 | 100 || 3 | 99 | gw2 | 50. | 0 | 0 | 100 || 4 | 99 | | 404 | 2048 | 2112 | asterisk-1 |+----+---------+-----------+------------+-------+------+-------------+...In the first place, the details of the caching must be provided by setting the module parameter “cache_table” in the OpenSIPS configuration script.
modparam("sql_cacher", "cache_table","id=carrier_fr_cachingdb_url=mysql://root:opensips@localhost/opensipscachedb_url=mongodb:mycluster://127.0.0.1:27017/my_db.coltable=carrierfailureroutekey=idcolumns=host_name reply_code flags next_domain")Next, the values of the cached columns ca be accessed through the “$sql_cached_value” PV.
...$avp(rc1) = $sql_cached_value(carrier_fr_caching:reply_code:1);$avp(rc2) = $sql_cached_value(carrier_fr_caching:reply_code:2);...var(some_id)=4;$avp(nd) = $sql_cached_value(carrier_fr_caching:next_domain:$var(some_id));...xlog("host name is: $sql_cached_value(carrier_fr_caching:host_name:2)");...Contributors
Section titled “Contributors”By Commit Statistics
Section titled “By Commit Statistics”Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
| # | Name | DevScore | Commits | Lines++ | Lines— |
|---|---|---|---|---|---|
| 1. | Vlad Patrascu (@rvlad-patrascu) | 94 | 42 | 3760 | 1204 |
| 2. | Liviu Chircu (@liviuchircu) | 25 | 18 | 264 | 213 |
| 3. | Razvan Crainea (@razvancrainea) | 16 | 14 | 29 | 18 |
| 4. | Stefan Darius (@dariusstefan) | 11 | 5 | 415 | 70 |
| 5. | Bogdan-Andrei Iancu (@bogdan-iancu) | 6 | 4 | 12 | 18 |
| 6. | Ionel Cerghit (@ionel-cerghit) | 4 | 1 | 55 | 97 |
| 7. | Dan Pascu (@danpascu) | 3 | 1 | 1 | 1 |
| 8. | Peter Lemenkov (@lemenkov) | 3 | 1 | 1 | 1 |
| 9. | Ovidiu Sas (@ovidiusas) | 3 | 1 | 1 | 1 |
(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
(3) ignoring whitespace edits, renamed files and auto-generated files
By Commit Activity
Section titled “By Commit Activity”| # | Name | Commit Activity |
|---|---|---|
| 1. | Stefan Darius (@dariusstefan) | Jun 2026 - Jul 2026 |
| 2. | Razvan Crainea (@razvancrainea) | Feb 2016 - Jun 2026 |
| 3. | Vlad Patrascu (@rvlad-patrascu) | Aug 2015 - Jul 2022 |
| 4. | Bogdan-Andrei Iancu (@bogdan-iancu) | May 2017 - Mar 2020 |
| 5. | Liviu Chircu (@liviuchircu) | Mar 2016 - Sep 2019 |
| 6. | Dan Pascu (@danpascu) | May 2019 - May 2019 |
| 7. | Peter Lemenkov (@lemenkov) | Jun 2018 - Jun 2018 |
| 8. | Ovidiu Sas (@ovidiusas) | Mar 2017 - Mar 2017 |
| 9. | Ionel Cerghit (@ionel-cerghit) | Dec 2015 - Dec 2015 |
(1) including any documentation-related commits, excluding merge commits
Documentation
Section titled “Documentation”Contributors
Section titled “Contributors”Last edited by: Razvan Crainea (@razvancrainea), Vlad Patrascu (@rvlad-patrascu), Liviu Chircu (@liviuchircu), Peter Lemenkov (@lemenkov), Bogdan-Andrei Iancu (@bogdan-iancu).
License
Section titled “License”All documentation files (i.e. .md extension) are licensed under the Creative Common License 4.0