cachedb_local Module

List of Tables

3.1. Top contributors by DevScore⁽¹⁾, authored commits⁽²⁾ and lines added/removed⁽³⁾
3.2. Most recently active contributors⁽¹⁾ to this module

List of Examples

1.1. Set cachedb_url parameter
1.2. Set cache_collections parameter
1.3. Set cache_clean_period parameter
1.4. Setting the cluster_id parameter
1.5. Set cluster_persistency parameter
1.6. cache_remove_chunk usage

Chapter 1. Admin Guide

1.1. Overview

This module is an implementation of a local cache system designed as a hash table. It uses the Key-Value interface exported by OpenSIPS core. Starting with version 2.3, the module can have multiple hash tables, called collections. Each url for cachedb_local module points to one collection. One collection can be shared between multiple urls.

1.2. Clustering

Cachedb_local clustering is a mechanism used to mirror local cache changes taking place in one OpenSIPS instance to one or multiple other instances without the need of third party dependencies. The process is simplified by using the clusterer module which facilitates the management of a cluster of OpenSIPS noeds and the sending of replication-related BIN packets (binary-encoded, using proto_bin). This might be usefull for implementing a hot stand-by system, where the stand-by instance can take over without the need of filling the cache by its own.

The following cache operations will be distributet within the cluster:

cache_store
cache_remove
cache_add
cache_sub

In addition to the event-driven replication, an OpenSIPS instance will first try to learn all the local cache information from antoher node in the cluster at startup. The data synchronization mechanism requires defining one of the nodes in the cluster as a "seed" node. See the clusterer module for details on how to do this and why is it needed.

Limitations: The clustering operations are not atomic and constistency over the cluster nodes is not guaranteed.

1.3. Dependencies

1.3.1. OpenSIPS Modules

The following modules must be loaded before this module:

clusterer, if cluster_id is set.

1.3.2. External Libraries or Applications

The following libraries or applications must be installed before running OpenSIPS with this module loaded:

none

1.4. Exported Parameters

1.4.1. `cachedb_url` (string)

URL parameter used to define cachedb_local collections. One collection can belong to multiple URLs, but one URL can have only one collection. Redefining an URL with the same schema and group name will result in overwriting that URL. Each collection used in URL definition must be defined using cachedb_collection parameter. The collection shall be defined as a normal database, at the end of the URL as in the examples. In the script the collection shall be identified using the schema and, if exists, the group name.

“If no URL defined, the url with no group name and collection "default" will be used.”.

Example 1.1. Set cachedb_url parameter

...
### for this example, if no collection is defined, the default collection named
### "default" shall be used
modparam("cachedb_local", "cachedb_url", "local://")
### this URL will use the collection named collection1; it will overwrite the
### previous url definition which was using the "default" collection
modparam("cachedb_local", "cachedb_url", "local:///collection1")
### this URL will use collection2; it will be referenced from the script
### with "local:group2"
modparam("cachedb_local", "cachedb_url", "local:group2:///collection2")

## how to use the URLs from the script
## as defined above, this call will use collection1
cache_store("local", ...)
## as defined above, this call will use collection2
cache_store("local:group2", ...)
...

1.4.2. `cache_collections` (string)

Using this parameter, collections(hash tables) and their sizes can be defined. Each collection definition must be separated one from another using ';'. Default size for a hash is 512. The size must be separated from the name of the collection using '='. Every collection that is defined in this parameter SHOULD be used in at least one URL, else you'll receive a WARNING.

The "default" collection always gets created, even when not included in this list of collections.

Example 1.2. Set cache_collections parameter

...
## creating collection1 with default size (512) and collection2 with custom size
## 2^5 (32); we also changed the size of the default collection, which would have been
## created anyway from 2^9 - 512 (default value) to 2^4 - 16
modparam("cachedb_local", "cache_collections", "collection1; collection2 = 5; default = 4")
...

1.4.3. `cache_clean_period` (int)

The time interval in seconds at which to go through all the records and delete the expired ones.

Default value is “600 (10 minutes)”.

Example 1.3. Set cache_clean_period parameter

...
modparam("cachedb_local", "cache_clean_period", 1200)
...

1.4.4. `cluster_id` (int)

Specifies the cluster ID which this instance will send to and receive cache data.

Default value is 0 (replication disabled).

Example 1.4. Setting the cluster_id parameter

...
modparam("cachedb_local", "cluster_id", 1)
...

1.4.5. `cluster_persistency` (string)

Controls the behavior of the OpenSIPS local cachedb clustering following a restart.

This parameter may take the following values:

"none" - no explicit data synchronization following a restart. The node starts empty.
"sync-from-cluster" - enable cluster-based restart persistency. Following a restart, an OpenSIPS cluster node will search for a healthy "donor" node from which to mirror the entire user location dataset via direct cluster sync (TCP-based, binary-encoded data transfer). This will require the configuration of one or multiple "seed" nodes in the cluster.

Default value is "sync-from-cluster".

Example 1.5. Set cluster_persistency parameter

...
modparam("cachedb_local", "cluster_persistency", "sync-from-cluster")
...

1.5. Exported Functions

1.5.1. `cache_remove_chunk([collection,] glob)`

Remove all keys from local cache that match the glob pattern corresponding to a certain collection or the 'default' collection if none defined. Keep in mind that collection name is different than group name, which identifies the engine in cachedb operations.

Parameters:

collection (string, optional)
glob (string)

This function can be used from all routes

Example 1.6. cache_remove_chunk usage

	...
	cache_remove_chunk("myinfo_*");
	cache_remove_chunk("collection1", "myinfo_*");
	...

1.6. Exported MI Functions

1.6.1. `cache_remove_chunk`

Removes all local cache entries that match the provided glob param.

Parameters :

glob - keys that match glob will be removed
collection(optional) - collection from which the keys shall be removed; if no collection set, the default collection will be used;

MI FIFO Command Format:

opensips-cli -x mi cache_remove_chunk "keyprefix*" collection

Chapter 2. Frequently Asked Questions

2.1.	What happened with old cache_table_size parameter?
	The parameter was removed because it was redundant. Since the addition of collections, the old hash now belongs to the default collection. This collection is created every time and it has a default size of 512. The size can be changed by setting the default collection size using cache_collections paramter.

Chapter 3. Contributors

3.1. By Commit Statistics

Table 3.1. Top contributors by DevScore⁽¹⁾, authored commits⁽²⁾ and lines added/removed⁽³⁾

	Name	DevScore	Commits	Lines ++	Lines --
1.	Vlad Paiu (@vladpaiu)	32	10	1155	693
2.	Liviu Chircu (@liviuchircu)	22	16	127	191
3.	Bogdan-Andrei Iancu (@bogdan-iancu)	16	14	46	50
4.	Vlad Patrascu (@rvlad-patrascu)	16	12	107	127
5.	Anca Vamanu	13	5	739	54
6.	Andrei Dragus	9	4	182	181
7.	Fabian Gast (@fgast)	9	3	517	48
8.	Ionut Ionita (@ionutrazvanionita)	9	3	513	55
9.	Razvan Crainea (@razvancrainea)	7	5	8	6
10.	Maksym Sobolyev (@sobomax)	4	2	6	6

All remaining contributors: Peter Lemenkov (@lemenkov), Dusan Klinec (@ph4r05), Ryan Bullock (@rrb3942), Julián Moreno Patiño, Zero King (@l2dy).

(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

3.2. By Commit Activity

Table 3.2. Most recently active contributors⁽¹⁾ to this module

	Name	Commit Activity
1.	Maksym Sobolyev (@sobomax)	Jan 2021 - Mar 2023
2.	Vlad Patrascu (@rvlad-patrascu)	Jan 2017 - Oct 2022
3.	Liviu Chircu (@liviuchircu)	Mar 2014 - Aug 2022
4.	Zero King (@l2dy)	Mar 2020 - Mar 2020
5.	Peter Lemenkov (@lemenkov)	Jun 2018 - Feb 2020
6.	Razvan Crainea (@razvancrainea)	Aug 2015 - Sep 2019
7.	Bogdan-Andrei Iancu (@bogdan-iancu)	Jan 2009 - Apr 2019
8.	Fabian Gast (@fgast)	Dec 2018 - Dec 2018
9.	Ionut Ionita (@ionutrazvanionita)	Jan 2017 - Jan 2017
10.	Julián Moreno Patiño	Feb 2016 - Feb 2016

All remaining contributors: Dusan Klinec (@ph4r05), Ryan Bullock (@rrb3942), Vlad Paiu (@vladpaiu), Andrei Dragus, Anca Vamanu.

(1) including any documentation-related commits, excluding merge commits

Chapter 4. Documentation

4.1. Contributors

Last edited by: Liviu Chircu (@liviuchircu), Vlad Patrascu (@rvlad-patrascu), Zero King (@l2dy), Bogdan-Andrei Iancu (@bogdan-iancu), Fabian Gast (@fgast), Peter Lemenkov (@lemenkov), Ionut Ionita (@ionutrazvanionita), Vlad Paiu (@vladpaiu), Andrei Dragus, Anca Vamanu.