Update the docs for outgoing pools

- Update the format of changed options
- Put ODBS after PGSQL/MySQL, as it is less common
- Mention required options explicitly
- Add changed options to the migration guide

doc/configuration/outgoing-connections.md

@@ -75,10 +75,52 @@ For example:
 
 #### `outgoing_pools.rdbms.*.connection.driver`
 * **Syntax:** string, one of `"pgsql"`, `"mysql"` or `"odbc"` (a supported driver)
+* **Default:** none - this option is mandatory
 * **Example:** `driver = "psgql"`
 
 Selects the driver for RDBMS connection. The choice of a driver impacts the set of available options.
 
+#### `outgoing_pools.rdbms.*.connection.keepalive_interval`
+* **Syntax:** positive integer
+* **Default:** not set - disabled by default
+* **Example:** `keepalive_interval = 30`
+
+When enabled, MongooseIM will send `SELECT 1 `query through every DB connection at given interval to keep them open. This option should be used to ensure that database connections are restarted after they became broken (e.g. due to a database restart or a load balancer dropping connections). Currently, not every network-related error returned from a database driver to a regular query will imply a connection restart.
+
+#### `outgoing_pools.rdbms.*.connection.max_start_interval`
+* **Syntax:** positive integer
+* **Default:** 30
+* **Example:** `max_start_interval = 30`
+
+When MongooseIM fails to connect to the DB, it retries with an exponential backoff. This option limits the backoff time for faster reconnection when the DB becomes reachable again.
+
+### Options for `pgsql` and `mysql`
+
+#### `outgoing_pools.rdbms.*.connection.host`
+* **Syntax:** string
+* **Default:** no default; required for `pgsql` and `mysql`
+* **Example:** `host = "localhost"`
+
+#### `outgoing_pools.rdbms.*.connection.port`
+* **Syntax:** string
+* **Default:** `5432` for `pgsql`; `3306` for `mysql`
+* **Example:** `host = "localhost"`
+
+#### `outgoing_pools.rdbms.*.connection.database`
+* **Syntax:** string
+* **Default:** no default; required for `pgsql` and `mysql`
+* **Example:** `database = "mim-db"`
+
+#### `outgoing_pools.rdbms.*.connection.username`
+* **Syntax:** string
+* **Default:** no default; required for `pgsql` and `mysql`
+* **Example:** `username = "mim-user"`
+
+#### `outgoing_pools.rdbms.*.connection.password`
+* **Syntax:** string
+* **Default:** no default; required for `pgsql` and `mysql`
+* **Example:** `password = "mim-password"`
+
 ### ODBC options
 
 #### `outgoing_pools.rdbms.*.connection.settings`
@@ -107,35 +149,11 @@ sslmode     = verify-full
 sslrootcert = /path/to/ca/cert
 ```
 
-### Other RDBMS backends
-
-#### `outgoing_pools.rdbms.*.connection.host`
-* **Syntax:** string
-* **Example:** `host = "localhost"`
-
-#### `outgoing_pools.rdbms.*.connection.database`
-* **Syntax:** string
-* **Example:** `database = "mim-db"`
-
-#### `outgoing_pools.rdbms.*.connection.username`
-* **Syntax:** string
-* **Example:** `username = "mim-user"`
-
-#### `outgoing_pools.rdbms.*.connection.password`
-* **Syntax:** string
-* **Example:** `password = "mim-password"`
-
-#### `outgoing_pools.rdbms.*.connection.keepalive_interval`
-* **Syntax:** positive integer
-* **Default:** undefined (keep-alive not activated)
-* **Example:** `keepalive_interval = 30`
-
-When enabled, MongooseIM will send SELECT 1 query through every DB connection at given interval to keep them open. This option should be used to ensure that database connections are restarted after they became broken (e.g. due to a database restart or a load balancer dropping connections). Currently, not every network-related error returned from a database driver to a regular query will imply a connection restart.
-
 ## HTTP options
 
 ### `outgoing_pools.http.*.connection.host`
 * **Syntax:** `"http[s]://string[:integer]"`
+* **Default:** no default; this option is mandatory
 * **Example:** `host = "https://server.com:879"`
 
 ### `outgoing_pools.http.*.connection.path_prefix`
@@ -156,7 +174,7 @@ HTTP also supports all TLS-specific options described in the TLS section.
 
 ## Redis-specific options
 
-Redis can be used as a session manager backend. 
+Redis can be used as a session manager backend.
 Global distribution (implemented in `mod_global_distrib`) requires Redis pool.
 
 There are two important limitations:
@@ -195,10 +213,12 @@ Currently, only one Riak connection pool can exist for each supported XMPP host
 
 ### `outgoing_pools.riak.*.connection.address`
 * **Syntax:** string
+* **Default:** none, this option is mandatory
 * **Example:** `address = "127.0.0.1"`
 
 ### `outgoing_pools.riak.*.connection.port`
 * **Syntax:** integer
+* **Default:** none, this option is mandatory
 * **Example:** `port = 8087`
 
 ### `outgoing_pools.riak.*.connection.credentials`
@@ -213,9 +233,9 @@ Riak also supports all TLS-specific options described in the TLS section.
 ## Cassandra options
 
 ### `outgoing_pools.cassandra.*.connection.servers`
-* **Syntax:** a TOML array of tables containing keys `"ip_adddress"` and `"port"`
-* **Default:** `[{ip_address = "localhost", port = 9042}]`
-* **Example:** `servers = [{ip_address = "host_one", port = 9042}, {ip_address = "host_two", port = 9042}]`
+* **Syntax:** a TOML array of tables containing keys `"host"` and `"port"`
+* **Default:** `[{host = "localhost", port = 9042}]`
+* **Example:** `servers = [{host = "host_one", port = 9042}, {host = "host_two", port = 9042}]`
 
 ### `outgoing_pools.cassandra.*.connection.keyspace`
 * **Syntax:** string
@@ -226,10 +246,12 @@ To use plain text authentication (using cqerl_auth_plain_handler module):
 
 ### `outgoing_pools.cassandra.*.connection.auth.plain.username`
 * **Syntax:** string
+* **Default:** none, this option is mandatory
 * **Example:** `username = "auser"`
 
 ### `outgoing_pools.cassandra.*.connection.auth.plain.password`
 * **Syntax:** string
+* **Default:** none, this option is mandatory
 * **Example:** `password = "somesecretpassword"`
 
 Support for other authentication modules may be added in the future.
@@ -241,7 +263,7 @@ Cassandra also supports all TLS-specific options described in the TLS section.
 Currently, only one pool tagged `default` can be used.
 
 ### `outgoing_pools.elastic.default.connection.host`
-* **Syntax:** string
+* **Syntax:** non-empty string
 * **Default:** `"localhost"`
 * **Example:** `host = "otherhost"`
 
@@ -286,25 +308,25 @@ The `Tag` parameter must be set to `event_pusher` in order to be able to use
 the pool for [`mod_event_pusher_rabbit`](../modules/mod_event_pusher_rabbit.md).
 Any other `Tag` can be used for other purposes.
 
-### `outgoing_pools.rabbit.*.connection.amqp_host`
+### `outgoing_pools.rabbit.*.connection.host`
 * **Syntax:** string
 * **Default:** `"localhost"`
-* **Example:** `amqp_host = "anotherhost"`
+* **Example:** `host = "anotherhost"`
 
-### `outgoing_pools.rabbit.*.connection.amqp_port`
+### `outgoing_pools.rabbit.*.connection.port`
 * **Syntax:** integer
 * **Default:** `5672`
-* **Example:** `amqp_port = 4561`
+* **Example:** `port = 4561`
 
-### `outgoing_pools.rabbit.*.connection.amqp_username`
+### `outgoing_pools.rabbit.*.connection.username`
 * **Syntax:** string
 * **Default:** `"guest"`
-* **Example:** `amqp_username = "corpop"`
+* **Example:** `username = "corpop"`
 
-### `outgoing_pools.rabbit.*.connection.amqp_password`
+### `outgoing_pools.rabbit.*.connection.password`
 * **Syntax:** string
 * **Default:** `"guest"`
-* **Example:** `amqp_password = "guest"`
+* **Example:** `password = "guest"`
 
 ### `outgoing_pools.rabbit.*.connection.confirms_enabled`
 * **Syntax:** boolean
@@ -332,10 +354,10 @@ Sets a limit of messages in a worker's mailbox above which the worker starts dro
 * **Default:** `389` (or `636` if encryption is enabled)
 * **Example:** `port = 800`
 
-### `outgoing_pools.ldap.*.connection.rootdn`
+### `outgoing_pools.ldap.*.connection.root_dn`
 * **Syntax:** string
-* **Default:** empty string 
-* **Example:** `rootdn = "cn=admin,dc=example,dc=com"`
+* **Default:** empty string
+* **Example:** `root_dn = "cn=admin,dc=example,dc=com"`
 
 Leaving out this option makes it an anonymous connection, which most likely is what you want.
 
@@ -345,18 +367,14 @@ Leaving out this option makes it an anonymous connection, which most likely is w
 * **Example:** `password = "topsecret"`
 
 ### `outgoing_pools.ldap.*.connection.connect_interval`
-* **Syntax:** integer
+* **Syntax:** positive integer
 * **Default:** `10000`
 * **Example:** `connect_interval = 20000`
 
 Reconnect interval after a failed connection.
 
-### `outgoing_pools.ldap.*.connection.encrypt`
-* **Syntax:** string, one of: `"none"` or `"tls"`
-* **Default:** `"none"`
-* **Example:** `encrypt = "tls"`
-
-LDAP also supports all TLS-specific options described in the TLS section (provided `encrypt` is set to `tls`).
+LDAP also supports all TLS-specific options described in the TLS section.
+To enable TLS, you need to include the `tls` subsection (it can be empty).
 
 ## TLS options
 

doc/migrations/5.0.0_5.1.0.md

@@ -18,6 +18,15 @@ See the description of [`current_domain`](../configuration/acl.md#aclmatch) for
 
 See the [auth configuration](../configuration/auth.md) for details.
 
+### Section `outgoing_pools`
+
+A few options of the outgoing connection pools were changed for consistency:
+
+* [Cassandra servers](../configuration/outgoing-connections.md#outgoing_poolscassandraconnectionservers): `ip_address` was renamed to `host`,
+* [RabbitMQ](../configuration/outgoing-connections.md#rabbitmq-options): the `amqp_` option prefix was removed,
+* [LDAP](../configuration/outgoing-connections.md#ldap-options): `rootdn` was renamed to `root_dn`;
+`encrypt` was removed (the `tls` option should be used instead).
+
 ### Section `s2s`
 
 * All options can be set globally or inside `host_config`.