# &adminguide;

## Overview

The module implements a simplified database engine based on text files. It can be used by &kamailio; DB interface instead of other database module (like MySQL).

The module is meant for use in demos or small devices that do not support other DB modules. It keeps everything in memory and if you deal with large amount of data you may run out of memory quickly. Also, it does not implement all standard database facilities (like order by), it includes minimal functionality to work properly (who knows ?!?) with &kamailio;.

NOTE: the timestamp is printed in an integer value from time_t structure. If you use it in a system that cannot do this conversion, it will fail (support for such situation is in to-do list).

NOTE: even when db_text is in non-caching mode, the module does not write back to hard drive after changes. In this mode, the module checks if the corresponding file on disk has changed, and reloads it. The write to disk happens at &kamailio; shut down. If db_text is in caching mode, many "reload" functions in various modules will not work.

### Design of dbtext engine

The dbtext database system architecture:

- A database is represented by a directory in the local file system.

  NOTE: when you use dbtext in &kamailio;, the database URL for modules must be the path to the directory where the table-files are located, prefixed by text://, e.g., text:///var/dbtext/ser. If there is no / after text:// then CFG_DIR/ is inserted at the beginning of the database path. So, either you provide an absolute path to database directory or a relative one to CFG_DIR directory.

  Do not forget that all databases in &kamailio; needs the version table.

- A table is represented by a text file inside database directory.

### Internal format of a dbtext table

The first line is the definition of the columns. Each column must be declared in the following format:

- the name of column must not include white spaces.

- the format of a column definition is: name(type,attr).

- between two column definitions must be a white space, e.g., first_name(str) last_name(str).

- the type of a column can be:

  - int - integer numbers.

  - double - real numbers with two decimals.

  - str - strings with maximum size of 4KB.

- a column can have one of the attributes:

  - auto - only for 'int' columns, the maximum value in that column is incremented and stored in this field if it is not provided in queries.

  - null - accept null values in column fields.

  - if no attribute is set, the fields of the column cannot have null value.

- each other line is a row with data. The line ends with \n.

- the fields are separated by :.

- no value between two ':' (or between ':' and start/end of a row) means null value. If the parameter "emptystring" is enabled, db_text sets a NULL string to an empty string value.

- next characters must be escaped in strings: \n, \r, \t, :.

- 0 -- the zero value must be escaped too.

#### Sample of a dbtext table

    ...
    id(int,auto) name(str) flag(double) desc(str,null)
    1:nick:0.34:a\tgood\: friend
    2:cole:-3.75:colleague
    3:bob:2.50:
    ...

#### Minimal &kamailio; location dbtext table definition

    ...
    username(str) contact(str) expires(int) q(double) callid(str) cseq(int)
    ...

#### Minimal &kamailio; subscriber dbtext table example

    ...
    username(str) password(str) ha1(str) domain(str) ha1b(str)
    suser:supasswd:xxx:alpha.org:xxx
    ...

## Known limitations

This database interface does not support data insertion with default values. All such values specified in the database template are ignored. So it is advisable to specify all data for a column at insertion operations.

## Dependencies

### &kamailio; modules

These modules must be loaded before this module:

- none.

### External libraries or applications

These libraries or applications must be installed before running &kamailio; with this module:

- none.

## Parameters

### `db_mode` (integer)

Set caching mode (0) or non-caching mode (1). In caching mode, data is loaded at startup. In non-caching mode, the module checks every time a table is requested whether the corresponding file on disk has changed, and if yes, will re-load the table from file.

Default value is 0.

#### Set `db_mode` parameter

    ...
    modparam("db_text", "db_mode", 1)
    ...

### `db_delim` (string)

Set the delimiter inside the db_text file.

Default value is :.

#### Set `db_mode` parameter

    ...
    modparam("db_text", "db_delim", "|")
    ...

### `default_connection` (string)

connection for use with rpc query command.

Default value is none (off).

#### Set `default_connection` parameter

                        ...
                        modparam("db_text", "default_connection", "text:///var/db/kamailio/dbtext")
                        ...

### `emptystring` (integer)

db_text by default handles an empty string as a NULL value. Some modules, like the dialplan module, does not accept NULL strings. If you enable emptystring an empty string will not be NULL, but an empty string.

Default value is 0 (off).

#### Set `emptystring` parameter

    ...
    modparam("db_text", "emptystring", 1)
    ...

### `file_buffer_size` (integer)

size of the buffer used to read the text file. Some presence tables have columns with large content.

Default value is 16384.

#### Set `file_buffer_size` parameter

    ...
    modparam("db_text", "file_buffer_size", 8192)
    ...

### `max_result_rows` (integer)

number of rows to read from the text file.

Default value is 100000.

#### Set `max_result_rows` parameter

    ...
    modparam("db_text", "max_result_rows", 1000000)
    ...

## Exported RPC Functions

### `db_text.dump`

Write back to hard drive all modified tables.

Name: db_text.dump

Parameters: none

RPC Command Format:

                kamctl rpc db_text.dump

### `db_text.query`

run sql command

Name: db_text.query

Parameters: sqlcmd

RPC Command Format:

                kamctl rpc db_text.query 'select * from location where username="xxx"'

## Installation and Running

Compile the module and load it instead of mysql or other DB modules.

REMINDER: when you use text in &kamailio;, the database URL for modules must be the path to the directory where the table-files are located, prefixed by text://, e.g., text:///var/dbtext/ser. If there is no / after text:// then CFG_DIR/ is inserted at the beginning of the database path. So, either you provide an absolute path to database directory or a relative one to CFG_DIR directory.

### Load the dbtext module

    ...
    loadmodule "/path/to/kamailio/modules_k/db_text.so"
    ...
    modparam("module_name", "db_url", "text:///path/to/dbtext/database")
    ...

### Using db_text with a basic &kamailio; configuration

Here are definitions for the most important tables as well as a basic configuration file to use db_text with &kamailio;. The table structures may change in time and you will have to adjust these examples. Check the source code directory utils/kamctl/dbtext/kamailio for current definitions.

You have to populate the table 'subscriber' by hand with user profiles in order to have authentication. To use with the given configuration file, the table files must be placed in the '/tmp/serdb' directory.

#### Definition of 'subscriber' table (one line)

    ...
    username(str) domain(str) password(str) first_name(str) last_name(str) phone(str) email_address(str) datetime_created(int) datetime_modified(int) confirmation(str) flag(str) sendnotification(str) greeting(str) ha1(str) ha1b(str) perms(str) allow_find(str) timezone(str,null) rpid(str,null)
    ...

#### Definition of 'location' and 'aliases' tables (one line)

    ...
    username(str) domain(str,null) contact(str,null) received(str) expires(int,null) q(double,null) callid(str,null) cseq(int,null) last_modified(str) flags(int) user_agent(str) socket(str)
    ...

#### Definition of 'version' table and sample records

    ...
    table_name(str) table_version(int)
    subscriber:3
    location:6
    aliases:6
    ...

#### Configuration file

    ...

    ...