Table of Contents
List of Tables
The Perl Virtual Database (VDB) provides a virtualization framework for OpenSIPS's database access. It does not handle a particular database engine itself but lets the user relay database requests to arbitrary Perl functions.
This module cannot be used "out of the box". The user has to supply functionality dedicated to the client module. See below for options.
The module can be used in all current OpenSIPS modules that need database access. Relaying of insert, update, query and delete operations is supported.
Modules can be configured to use the db_perlvdb module as database backend using the db_url_parameter:
modparam("acc", "db_url", "perlvdb:OpenSIPS::VDB::Adapter::AccountingSIPtrace")
This configuration options tells acc module that it should use the db_perlvdb module which will in turn use the Perl class OpenSIPS::VDB::Adapter::AccountingSIPtrace to relay the database requests.
The following modules must be loaded before this module:
perl -- Perl module
OpenSIPS uses a database API for requests of numerous different types of data. Four primary operations are supported:
query
insert
update
delete
This module relays these database requests to user implemented Perl functions.
A client module has to be configured to use the db_perlvdb module in conjunction
with a Perl class to provide the functions. The configured class needs to
inherit from the base class OpenSIPS::VDB.
Derived classes have to implement the necessary
functions "query", "insert", "update" and/or "delete". The client module
specifies the necessary functions.
To find out which functions are called from a module, its processes may
be evaluated with the OpenSIPS::VDB::Adapter::Describe class which will
log incoming requests (without actually providing any real functionality).
While users can directly implement their desired functionality in a class derived from OpenSIPS::VDB, it is advisable to split the implementation into an Adapter that transforms the relational structured parameters into pure Perl function arguments, and add a virtual table (VTab) to provide the relaying to an underlying technology.
Before introducing the higher level concepts of this module, the used datatypes will briefly be explained. The OpenSIPS Perl library includes some data types that have to be used in this module:
A value includes a data type flag and a value. Valid data types are DB_INT, DB_DOUBLE, DB_STRING, DB_STR, DB_DATETIME, DB_BLOB, DB_BITMAP. A new variable may be created with
my $val = new OpenSIPS::VDB::Value(DB_STRING, "foobar");
Value objects contain the type() and data() methods to get or set the type and data attributes.
The Pair class is derived from the Value class and additionally contains a column name (key). A new variable may be created with
my $pair = new OpenSIPS::VDB::Pair("foo", DB_STRING, "bar");
where foo is the key and bar is the value. Additonally to the methods of the Value class, it contains a key() method to get or set the key attribute.
The ReqCond class is used for select condition and is derived from the Pair class. It contains an addtional operator attribute. A new variable may be created with
my $cond = new OpenSIPS::VDB::ReqCond("foo", ">", DB_INT, 5);
where foo is the key, "greater" is the operator and 5 is the value to compare. Additonally to the methods of the Pair class, it contains an op() method to get or set the operator attribute.
This class represents a column definition or database schema. It contains an array for the column names and an array for the column types. Both arrays need to have the same length. A new variable may be created with
my @types = { DB_INT, DB_STRING };
my @names = { "id", "vals" };
my $cols = new OpenSIPS::VDB::Column(\@types, \@names);
The class contains the methods type() and name() to get or set the type and name arrays.
Adapters should be used to turn the relational structured database request into pure Perl function arguments. The alias_db function alias_db_lookup for example takes a user/host pair, and turns it into another user/host pair. The Alias adapter turns the ReqCond array into two separate scalars that are used as parameters for a VTab call.
Adapter classes have to inherit from the OpenSIPS::VDB base class and may provide one or more functions with the names insert, update, replace, query and/or delete, depending on the module which is to be used with the adapter. While modules such as alias_db only require a query function, others -- such as siptrace -- depend on inserts only.
The implemented functions need to deal with the correct data types. The parameter and return types are listed in this section.
insert() is passed an array of OpenSIPS::VDB::Pair objects. It should return an integer value.
replace() is passed an array of OpenSIPS::VDB::Pair objects. This function is currently not used by any publicly available modules. It should return an integer value.
delete() is passed an array of OpenSIPS::VDB::ReqCond objects. It should return an integer value.
update() is passed an array of OpenSIPS::VDB::ReqCond objects (which rows to update) and an array of OpenSIPS::VDB::Pair objects (new data). It should return an integer value.
query() is passed an array of OpenSIPS::VDB::ReqCond objects (which rows to select), an array of strings (which column names to return) and a single string by which column to sort. It should return an object of type OpenSIPS::VDB::Result.
VTabs (virtual tables) provide a particular implementation for an adapter. The Alias adapter e.g. calls a function with two parameters (user, host) and expects a hash to be returned with the two elements username and domain, or undef (when no result is found). A sample VTab implementation for the Alias adapter demonstrates this technique with a Perl hash that contains the alias data.
The standard Adapter/VTab pattern lets the user choose between three options on how to implement VTabs:
Single function. When a function is used as a virtual table, it is passed the operation name (insert, replace, update, query, delete) as its first parameter. The function may be implemented in the main namespace.
Package/class. The defined class needs to have an init() function. It will be called during the first call of that VTab. Addtionally, the package has to define the necessary functions insert, replace, update, delete and/or query. These functions will be called in a function context (first parameter is the class name).
Object. The defined class needs to have a new() function which will return a reference to the newly created object. This object needs to define the necessary functions insert, replace, update, delete and/or query. These functions will be called in a method context (first parameter is a reference to the object).
Table 3.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) | 26 | 19 | 257 | 202 |
| 2. | Bastian Friedrich | 19 | 2 | 1820 | 18 |
| 3. | Liviu Chircu (@liviuchircu) | 14 | 12 | 25 | 57 |
| 4. | Razvan Crainea (@razvancrainea) | 11 | 9 | 27 | 14 |
| 5. | Daniel-Constantin Mierla (@miconda) | 9 | 7 | 27 | 25 |
| 6. | Maksym Sobolyev (@sobomax) | 5 | 3 | 5 | 21 |
| 7. | Henning Westerholt (@henningw) | 4 | 2 | 14 | 13 |
| 8. | Vlad Patrascu (@rvlad-patrascu) | 4 | 2 | 10 | 10 |
| 9. | Ancuta Onofrei | 3 | 1 | 13 | 20 |
| 10. | Konstantin Bokarius | 3 | 1 | 3 | 5 |
All remaining contributors: Alexandra Titoc, Julián Moreno Patiño, Peter Lemenkov (@lemenkov), Edson Gellert Schubert.
(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 3.2. Most recently active contributors(1) to this module
| Name | Commit Activity | |
|---|---|---|
| 1. | Alexandra Titoc | Sep 2024 - Sep 2024 |
| 2. | Liviu Chircu (@liviuchircu) | Mar 2014 - May 2024 |
| 3. | Razvan Crainea (@razvancrainea) | Aug 2015 - Aug 2023 |
| 4. | Maksym Sobolyev (@sobomax) | Oct 2022 - Feb 2023 |
| 5. | Bogdan-Andrei Iancu (@bogdan-iancu) | Jul 2007 - Apr 2019 |
| 6. | Vlad Patrascu (@rvlad-patrascu) | May 2017 - Apr 2019 |
| 7. | Peter Lemenkov (@lemenkov) | Jun 2018 - Jun 2018 |
| 8. | Julián Moreno Patiño | Feb 2016 - Feb 2016 |
| 9. | Daniel-Constantin Mierla (@miconda) | Oct 2007 - Mar 2008 |
| 10. | Konstantin Bokarius | Mar 2008 - Mar 2008 |
All remaining contributors: Edson Gellert Schubert, Henning Westerholt (@henningw), Ancuta Onofrei, Bastian Friedrich.
(1) including any documentation-related commits, excluding merge commits
Last edited by: Peter Lemenkov (@lemenkov), Liviu Chircu (@liviuchircu), Bogdan-Andrei Iancu (@bogdan-iancu), Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson Gellert Schubert, Bastian Friedrich.
Documentation Copyrights:
Copyright © 2007 Collax GmbH