# Database FIFO interface

## Introduction

SER offers to its module developers a common DataBase(DB) interface, disregarding the database implementation (mysql, dbtext or postgres) that lays beneath it.

This feature is now extended and offered also to the SER users/administrators by DataBase FIFO Interface (or DB FIFO interface). So, DB FIFO interface is an extension of the internal DB interface through the FIFO server. Everybody from outside SER can operate SER's database (for adding/removing users, for manipulating aliases, access control wrights, etc) using the same FIFO commands without caring about the database type that's used by SER.

## Advantages

All external applications that need to work with SER's database (like serctl or serweb) can do so via DB FIFO interface without depending of a specific database driver. No modifications will be required when a new type of database will be added to SER.

Also, this approach, prevents any kind of confusion between the database type used by SER and the one used by these external applications. They will use automatically the same database as SER is configure to use.

## Limitations

DB FIFO interface is restricted to the limitation of the internal DB interface.

Also the size (can fit on only one line) and the content (\n or \r characters must be escaped) of a BLOB value is restricted.

## Configuration

FIFO server presents is required, so configure in your config file the FIFO file to be used by the SER FIFO server:

    fifo="/tmp/ser_fifo"

To enable the DB FIFO interface, it's required to load at least one database module (available for the moment are mysql, dbtext and postgres).

The database module that you want to use and the database configuration are configured via parameter `fifo_db_url`:

    fifo_db_url="mysql:mysql_url"
    fifo_db_url="dbtext:dbtext_url"

The format of the database URL depends of the used database implementation (see the documentation for each DB type).

NOTE: be sure to load the module the is specified into fifo_db_url!

If no fifo_db_url is specified or no appropriate DB module found, the DB FIFO interface will be disabled.

## DB FIFO commands

From FIFO point of view, all DB FIFO commands are mapped with the same name: DB. The first line of the command must contain the name of the DB command. Available are:

- SELECT

- UPDATE

- INSERT

- DELETE

- RAW_QUERY

- EAW_QUERY_RES

The grammar used in the commands definition can be found in next section "DB FIFO grammar". The presence of the `reply_fifo_file` in the FIFO command is required for all commands.

### `SELECT` command

This function implements SELECT DB directive. Its syntax is:

    :DB:reply_fifo_file
    select
    [COLUMN]*
    .
    TABLE_NAME
    [CVP]
    .

If no CVP line is present, the whole table.will be returned. If no COLUMN line is given, all table columns will be found in the result.

The result of the query will be return via reply_fifo_file in one raw per line format (only requested columns), the first line being the head of the table. The NULL values will be printed as "NULL".

### `INSERT` command

This function implements INSERT DB directive - inserts one row in a table. Its syntax is:

    :DB:reply_fifo_file
    insert
    TABLE_NAME
    [EQUAL_CVP]+
    .

Command returns nothing if success or, other way, an error message.

### `UPDATE` command

The function implements UPDATE DB directive - it is possible to modify one or more rows in a table. Its syntax is:

    :DB:reply_fifo_file
    update
    [EQUAL_CVP]+
    .
    TABLE_NAME
    [CVP]*
    .

Command returns nothing if success or, other way, an error message.

### `DELETE` command

This function implements DELETE DB directive - it is possible to delete one or more rows from a table. Its syntax is:

    :DB:reply_fifo_file
    delete
    TABLE_NAME
    [CVP]*
    .

If CVP list contain no lines, all rows will be deleted (table will be empty).

Command returns nothing if success or, other way, an error message.

### `RAW_QUERY` command

This function sends a raw query directly to the database driver without trying to understand the command. This command MUST NOT generate any response. Otherwise, the database driver can block or desynchronize (depending of the driver). Its syntax is:

    :DB:reply_fifo_file
    raw_query
    (ASCII)+

Command returns nothing if success or, other way, an error message.

### `RAW_QUERY_RES` command

This function sends a raw query directly to the database driver without trying to understand the command. This command MUST generate an response (even if an empty one). Otherwise, the database driver can block or desynchronize (depending of the driver). Its syntax is:

    :DB:reply_fifo_file
    raw_query_res
    (ASCII)+

Command's output format is identical with the one from `SELECT` command.

## DB FIFO grammar

    COLUMN=(alfa-numeric|'_')+

    GAP=' '|'\t'

    DEF_OP='='|'<'|'>'|'>='|'<='
    UNDEF_OP=(ASCII)+
    CAST_OP="int"|"double"|"string"|"date"|"blob"|"bitmap"

    INT_VAL=integer number
    DOUBLE_VAL=float number
    STRING_VAL='"' ASCII* '"'
    DATE_VAL='<' YEAR '-' MONTH '-' DAY ' ' HOUR ':' MINS ':' SECS '>'
    BLOB_VAL=STRING_VAL
    BITMAP_VAL=INT_VAL
    NULL_VAL="null"

    VALUE=('['CAST_OP']')?(INT_VAL|DOUBLE_VAL|STRING_VAL|DATE_VAL|
    		BLOB_VAL|BITMAP_VAL|NULL_VAL)

    CVP(column-value-pair)=
    		(COLUMN GAP* DEF_OP GAP* VALUE) | (COLUMN GAP+ UNDEF_OP GAP+ VALUE)
    EQUAL-CVP(column-equal-value-pair)=
    		(COLUMN GAP* '=' GAP* VALUE)