src/modules/db_perlvdb/README
9125d64c
 Perl Virtual Database Module
 
 Bastian Friedrich
 
    Collax GmbH
 
 Edited by
 
 Bastian Friedrich
 
9cb2a163
    Copyright © 2007 Collax GmbH
d9bb387b
      __________________________________________________________________
9125d64c
 
    Table of Contents
d77df08a
 
9fc784c6
    1. Admin Guide
9125d64c
 
d9bb387b
         1. Overview
         2. Dependencies
9125d64c
 
d9bb387b
               2.1. Kamailio Modules
               2.2. External Libraries or Applications
9125d64c
 
ba7961bb
         3. Parameters
         4. Functions
9125d64c
 
9fc784c6
    2. Developer Guide
9125d64c
 
d9bb387b
         1. Introduction
e5e82115
         2. Base class Kamailio::VDB
d9bb387b
         3. Data types
9125d64c
 
e5e82115
               3.1. Kamailio::VDB::Value
               3.2. Kamailio::VDB::Pair
               3.3. Kamailio::VDB::ReqCond
               3.4. Kamailio::VDB::Column
               3.5. Kamailio::VDB::Result
9125d64c
 
d9bb387b
         4. Adapters
9125d64c
 
d9bb387b
               4.1. Function parameters
9125d64c
 
d9bb387b
         5. VTabs
d77df08a
 
9fc784c6
 Chapter 1. Admin Guide
9125d64c
 
d9bb387b
    Table of Contents
 
    1. Overview
    2. Dependencies
 
         2.1. Kamailio Modules
         2.2. External Libraries or Applications
 
ba7961bb
    3. Parameters
    4. Functions
d9bb387b
 
 1. Overview
9125d64c
 
d9bb387b
    The Perl Virtual Database (VDB) provides a virtualization framework for
    Kamailio's database access. It does not handle a particular database
    engine itself but lets the user relay database requests to arbitrary
    Perl functions.
9125d64c
 
d9bb387b
    This module cannot be used "out of the box". The user has to supply
    functionality dedicated to the client module. See below for options.
9125d64c
 
d9bb387b
    The module can be used in all current Kamailio modules that need
    database access. Relaying of insert, update, query and delete
    operations is supported.
9125d64c
 
bcacfa0c
    Modules can be configured to use the db_perlvdb module as database
    backend using the db_url_parameter:
e5e82115
 modparam("acc", "db_url", "perlvdb:Kamailio::VDB::Adapter::AccountingSIPtrace")
9125d64c
 
d9bb387b
    This configuration options tells acc module that it should use the
bcacfa0c
    db_perlvdb module which will in turn use the Perl class
e5e82115
    Kamailio::VDB::Adapter::AccountingSIPtrace to relay the database
989206bd
    requests.
9125d64c
 
d9bb387b
 2. Dependencies
 
    2.1. Kamailio Modules
    2.2. External Libraries or Applications
9125d64c
 
d9bb387b
 2.1. Kamailio Modules
9125d64c
 
    The following modules must be loaded before this module:
bcacfa0c
      * app_perl -- Perl Application module
9125d64c
 
d9bb387b
 2.2. External Libraries or Applications
9125d64c
 
d9bb387b
    The following libraries or applications must be installed before
    running Kamailio with this module loaded:
bcacfa0c
      * None (Besides the ones mentioned in the app_perl module
        documentation).
9125d64c
 
ba7961bb
 3. Parameters
9125d64c
 
    None.
 
ba7961bb
 4. Functions
9125d64c
 
    None.
 
9fc784c6
 Chapter 2. Developer Guide
9125d64c
 
d9bb387b
    Table of Contents
 
    1. Introduction
e5e82115
    2. Base class Kamailio::VDB
d9bb387b
    3. Data types
 
e5e82115
         3.1. Kamailio::VDB::Value
         3.2. Kamailio::VDB::Pair
         3.3. Kamailio::VDB::ReqCond
         3.4. Kamailio::VDB::Column
         3.5. Kamailio::VDB::Result
9125d64c
 
d9bb387b
    4. Adapters
 
         4.1. Function parameters
 
    5. VTabs
 
 1. Introduction
 
e5e82115
    Kamailio uses a database API for requests of numerous different types
    of data. Four primary operations are supported:
9125d64c
      * query
      * insert
      * update
      * delete
 
d9bb387b
    This module relays these database requests to user implemented Perl
    functions.
9125d64c
 
e5e82115
 2. Base class Kamailio::VDB
9125d64c
 
bcacfa0c
    A client module has to be configured to use the db_perlvdb module in
d9bb387b
    conjunction with a Perl class to provide the functions. The configured
e5e82115
    class needs to inherit from the base class Kamailio::VDB.
9125d64c
 
d9bb387b
    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
e5e82115
    Kamailio::VDB::Adapter::Describe class which will log incoming requests
d9bb387b
    (without actually providing any real functionality).
9125d64c
 
d9bb387b
    While users can directly implement their desired functionality in a
e5e82115
    class derived from Kamailio::VDB, it is advisable to split the
d9bb387b
    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.
9125d64c
 
d9bb387b
 3. Data types
9125d64c
 
e5e82115
    3.1. Kamailio::VDB::Value
    3.2. Kamailio::VDB::Pair
    3.3. Kamailio::VDB::ReqCond
    3.4. Kamailio::VDB::Column
    3.5. Kamailio::VDB::Result
9125d64c
 
d9bb387b
    Before introducing the higher level concepts of this module, the used
e5e82115
    datatypes will briefly be explained. The Kamailio Perl library includes
d9bb387b
    some data types that have to be used in this module:
9125d64c
 
e5e82115
 3.1. Kamailio::VDB::Value
d9bb387b
 
    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
e5e82115
 my $val = new Kamailio::VDB::Value(DB_STRING, "foobar");
9125d64c
 
d9bb387b
    Value objects contain the type() and data() methods to get or set the
    type and data attributes.
9125d64c
 
e5e82115
 3.2. Kamailio::VDB::Pair
9125d64c
 
989206bd
    The Pair class is derived from the Value class and additionally
d9bb387b
    contains a column name (key). A new variable may be created with
e5e82115
 my $pair = new Kamailio::VDB::Pair("foo", DB_STRING, "bar");
9125d64c
 
8868e624
    where foo is the key and bar is the value. Additionally to the methods
d9bb387b
    of the Value class, it contains a key() method to get or set the key
    attribute.
9125d64c
 
e5e82115
 3.3. Kamailio::VDB::ReqCond
9125d64c
 
d9bb387b
    The ReqCond class is used for select condition and is derived from the
8868e624
    Pair class. It contains an additional operator attribute. A new
    variable may be created with
e5e82115
 my $cond = new Kamailio::VDB::ReqCond("foo", ">", DB_INT, 5);
9125d64c
 
d9bb387b
    where foo is the key, "greater" is the operator and 5 is the value to
8868e624
    compare. Additionally to the methods of the Pair class, it contains an
d9bb387b
    op() method to get or set the operator attribute.
9125d64c
 
e5e82115
 3.4. Kamailio::VDB::Column
9125d64c
 
d9bb387b
    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
9125d64c
 my @types = { DB_INT, DB_STRING };
 my @names = { "id", "vals" };
e5e82115
 my $cols = new Kamailio::VDB::Column(\@types, \@names);
9125d64c
 
d9bb387b
    The class contains the methods type() and name() to get or set the type
    and name arrays.
 
e5e82115
 3.5. Kamailio::VDB::Result
d9bb387b
 
    The Result class represents a query result. It contains a schema (class
    Column) and an array of rows, where each row is an array of Values. The
    object methods coldefs() and rows() may be used to get and set the
    object attributes.
9125d64c
 
d9bb387b
 4. Adapters
9125d64c
 
d9bb387b
    4.1. Function parameters
9125d64c
 
d9bb387b
    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.
9125d64c
 
e5e82115
    Adapter classes have to inherit from the Kamailio::VDB base class and
d9bb387b
    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.
9125d64c
 
d9bb387b
 4.1. Function parameters
9125d64c
 
d9bb387b
    The implemented functions need to deal with the correct data types. The
    parameter and return types are listed in this section.
9125d64c
 
e5e82115
    insert() is passed an array of Kamailio::VDB::Pair objects. It should
d9bb387b
    return an integer value.
9125d64c
 
e5e82115
    replace() is passed an array of Kamailio::VDB::Pair objects. This
d9bb387b
    function is currently not used by any publicly available modules. It
9125d64c
    should return an integer value.
 
e5e82115
    delete() is passed an array of Kamailio::VDB::ReqCond objects. It
    should return an integer value.
9125d64c
 
e5e82115
    update() is passed an array of Kamailio::VDB::ReqCond objects (which
    rows to update) and an array of Kamailio::VDB::Pair objects (new data).
9125d64c
    It should return an integer value.
 
e5e82115
    query() is passed an array of Kamailio::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 Kamailio::VDB::Result.
d9bb387b
 
 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.
8868e624
        It will be called during the first call of that VTab. Additionally,
d9bb387b
        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).