db_cachedb Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview

              1.1.1. The idea

        1.2. Dependencies

              1.2.1. OpenSIPS Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. cachedb_url (str)

        1.4. Examples of Usage

              1.4.1. Distributed Subscriber Base

        1.5. Current Limitations

              1.5.1. CacheDB modules integration
              1.5.2. Extensive Testing Needed
              1.5.3. CacheDB Specific 'schema' and other
                      incompatibilities

   2. Contributors

        2.1. By Commit Statistics
        2.2. By Commit Activity

   3. Documentation

        3.1. Contributors

   List of Tables

   2.1. Top contributors by DevScore^(1), authored commits^(2) and
          lines added/removed^(3)

   2.2. Most recently active contributors^(1) to this module

   List of Examples

   1.1. Set cachedb_url parameter
   1.2. OpenSIPS CFG Snippet for using DB_CACHEDB

Chapter 1. Admin Guide

1.1. Overview

1.1.1.  The idea

   The db_cachedb module will expose the same front db api,
   however it will run on top of a NoSQL back-end, emulating the
   SQL calls to the back-end specific queries. Thus, any OpenSIPS
   module that would regularily need a regular SQL-based database,
   will now be able to run over a NoSQL back-end, allowing for a
   much easier distribution and integration of the currently
   existing OpenSIPS modules in a distributed environment.

1.2. Dependencies

1.2.1. OpenSIPS Modules

   The following modules must be loaded before this module:
     * At least one NoSQL cachedb_* module.

1.2.2. External Libraries or Applications

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

1.3. Exported Parameters

1.3.1.  cachedb_url (str)

   The URL for the CacheDB back-end to be used. It can be set more
   than one time.

   Example 1.1. Set cachedb_url parameter
...
modparam("db_cachedb","cachedb_url","mongodb:mycluster://127.0.0.1:27017
/db.col")
...

1.4. Examples of Usage

1.4.1.  Distributed Subscriber Base

   In order to achieve such a setup, one would have to set the
   db_url parameter of the auth_db module to point to the
   DB_CACHEDB URL.

   Example 1.2. OpenSIPS CFG Snippet for using DB_CACHEDB
loadmodule "auth_db.so"
modparam("auth_db", "load_credentials", "$avp(user_rpid)=rpid")

loadmodule "db_cachedb.so"
loadmodule "cachedb_mongodb.so"
...
modparam("db_cachedb","cachedb_url","mongodb:mycluster://127.0.0.1:27017
/my_db.col")
modparam("auth_db","db_url","cachedb://mongodb:mycluster")
...

   With such a setup, the auth_db module will load the subscribers
   from the MongoDB cluster, in the 'my_db' database, in the
   'subscriber' collection.

   The same mechanism/setup can be used to run other modules (
   like usrloc, dialog, permissions, drouting, etc ) on top of a
   cachedb cluster.

1.5. Current Limitations

1.5.1.  CacheDB modules integration

   Currently the only cachedb_* module that implements this
   functionality is the cachedb_mongodb module, so currently you
   can only emulate SQL queries to a MongoDB instance/cluster.
   There are plans to also extend this functionality to other
   cachedb_* backends, like Cassandra and CouchBase.

1.5.2.  Extensive Testing Needed

   Since there are many OpenSIPS modules that currently use the DB
   interface, it wasn't feasible to test all scenarios with all
   modules, and there still might be some incompatibilities. The
   module was tested with some regularily used modules ( like
   usrloc, dialog, permissions, drouting ), but more testing is
   very much welcome, and feedback is appreciated.

1.5.3.  CacheDB Specific 'schema' and other incompatibilities

   Since the NoSQL backends do not usually have a strict schema
   involved, we do not provide scripts for creating such schemas,
   since the insertion ops will trigger the dynamically creation
   of the schema and info. Still, a specific data collection needs
   to be present, and that is the equivalent of the 'version'
   table from the SQL. Since most modules check the version table
   at the module setup, it's the user's responsability to setup
   such a 'version' collection in the respective NoSQL back-end.
   For example, for the MongoDB cluster, 'version' is a reserved
   keyword, so one would have to change the default version table
   that OpenSIPS uses ( via the 'db_version_table' global
   parameter ) and then manually insert the version number with
   something like db.my_version_table.insert({table_version :
   NumberInt(5), table_name : "address"})

Chapter 2. Contributors

2.1. By Commit Statistics

   Table 2.1. Top contributors by DevScore^(1), authored
   commits^(2) and lines added/removed^(3)
     Name DevScore Commits Lines ++ Lines --
   1. Vlad Paiu (@vladpaiu) 10 3 626 7
   2. Liviu Chircu (@liviuchircu) 9 7 31 32
   3. Razvan Crainea (@razvancrainea) 7 5 7 5
   4. Vlad Patrascu (@rvlad-patrascu) 4 2 3 2
   5. Bogdan-Andrei Iancu (@bogdan-iancu) 4 2 3 1
   6. Peter Lemenkov (@lemenkov) 3 1 1 1
   7. Walter Doekes (@wdoekes) 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. 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

2.2. By Commit Activity

   Table 2.2. Most recently active contributors^(1) to this module
                     Name                   Commit Activity
   1. Razvan Crainea (@razvancrainea)     Aug 2015 - Sep 2019
   2. Bogdan-Andrei Iancu (@bogdan-iancu) Oct 2014 - Apr 2019
   3. Vlad Patrascu (@rvlad-patrascu)     May 2017 - Apr 2019
   4. Peter Lemenkov (@lemenkov)          Jun 2018 - Jun 2018
   5. Liviu Chircu (@liviuchircu)         Mar 2014 - Jun 2018
   6. Walter Doekes (@wdoekes)            May 2014 - May 2014
   7. Vlad Paiu (@vladpaiu)               Feb 2013 - Mar 2013

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

Chapter 3. Documentation

3.1. Contributors

   Last edited by: Peter Lemenkov (@lemenkov), Liviu Chircu
   (@liviuchircu), Walter Doekes (@wdoekes), Vlad Paiu
   (@vladpaiu).

   Documentation Copyrights:

   Copyright © 2013 www.opensips-solutions.com
