Multiple DB nodes in obm-sync

## Introduction

Starting with OBM 2.5.9 and 3.1.2, obm-sync implements application level load-balancing of database transactions accross any number of nodes.
This works by leveraging the concept of _read-only_ nodes.
Such nodes are able to process _read-only_ transactions, i.e.: transactions where only SQL SELECT commands are sent.

In typical high-availability architectures, a _master_ node is replicated to a number of _slave_ nodes.
To benefit more from the slave nodes you can use them to process read-only database queries, thus increasing the overall throughput of OBM.

## Configuration

To use the new feature, you will have to create a new _databases.ini_ configuration file in _/etc/obm_.
This file is a standard [INI file](http://en.wikipedia.org/wiki/INI_file) with the following layout:

[node-name]
key = value

[node-name]
key = value

...

The available properties are given in the table below:

| Key | Description | Required? | Default Value |
| ----- |
| dbtype | The type of RDBMS. Valid values are _PGSQL_ and _MYSQL_ | Yes | N/A |
| host | The ip address of the node. | Yes | N/A |
| port | The port that the server is listening on. | No | If dbtype=PGSQL, 5432. If dbtype=MYSQL, 3306. |
| db | The name of the OBM database. | Yes | N/A |
| user | The username used to access the database. | Yes | N/A |
| password | The password of the above username. | Yes | N/A |
| database-max-connection-pool-size | The maximum number of DB connections in this node's connection pool. | No | 10 |
| database-min-connection-pool-size | The minimum number of DB connections in this node's connection pool. | No | 10% of _database-max-connection-pool-size_ |
| read-only | Whether this node is a read-only node. Valid values are _true_ and _false_. | No | false |

Please keep in mind that only one node with _read-only=false_ can be configured.

Here's an example of a _databases.ini_ file for a 3 nodes PostgreSQL cluster, using the default pool size:

[master]
dbtype=PGSQL
host=1.2.3.4
db=obm
user=obm
password=obm

[slave1]
dbtype=PGSQL
host=1.2.3.5
db=obm
user=obm
password=obm
read-only=true

[slave2]
dbtype=PGSQL
host=1.2.3.6
db=obm
user=obm
password=obm
read-only=true

## Upgrading ?

The implementation automatically falls back to using _/etc/obm/obm_conf.ini_ if it couldn't read _/etc/obm/databases.ini_.
This means that when you upgrade from an earlier version obm-sync will keep on working as usual and you aren't required to change anything in your configuration. Smooth, isn't it?Nike Air Max 270