1.1. Overview

The Perl Virtual Database (VDB) provides a virtualization framework for OpenSER'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 OpenSER modules that need database access. Relaying of insert, update, query and delete operations is supported.

Modules can be configured to use the perlvdb module as database backend using the db_url_parameter:

modparam("acc", "db_url", "perlvdb:OpenSER::VDB::Adapter::AccountingSIPtrace")

This configuration options tells acc module that it should use the perlvdb module which will in turn use the Perl class OpenSER::VDB::Adapter::AccountingSIPtrace to relay the database requests.

1.2. Dependencies

1.3. Exported Parameters

None.

1.4. Exported Functions

None.

2.1. Introduction

OpenSER 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.

2.2. Base class OpenSER::VDB

A client module has to be configured to use the perlvdb module in conjunction with a Perl class to provide the functions. The configured class needs to inherit from the base class OpenSER::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 OpenSER::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 OpenSER::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.

2.3. Data types

Before introducing the higher level concepts of this module, the used datatypes will briefly be explained. The OpenSER Perl library includes some data types that have to be used in this module:

my $val = new OpenSER::VDB::Value(DB_STRING, "foobar");

my $pair = new OpenSER::VDB::Pair("foo", DB_STRING, "bar");

my $cond = new OpenSER::VDB::ReqCond("foo", ">", DB_INT, 5);

my @types = { DB_INT, DB_STRING };
my @names = { "id", "vals" };
my $cols = new OpenSER::VDB::Column(\@types, \@names);

2.4. Adapters

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 OpenSER::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.

2.5. VTabs

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).