Database FIFO interface

$Revision$ $Date$ 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.

<function>SELECT</function> 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".

<function>INSERT</function> 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.

<function>UPDATE</function> 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.

<function>DELETE</function> 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.

<function>RAW_QUERY</function> 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.

<function>RAW_QUERY_RES</function> 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.