# xSQL High Availability Parameters

> The xSQL configuration file can be used to define eXtremeDB High Availability parameters corresponding to the C API ``mco_ha_params_t`` structure.

> ### For an overview see page Configuration File Parameters

> The `ha_params` section consists of a set of "name : value" pairs enclosed within braces. For example:

>         ha_params : {
>             master_ports : [ ":tcp:6100", ":udp:6100"],
>             master_params : {
>                 ...
>             }
>             ...
>             connection_strings: [ "192.168.1.100:5000", "192.168.1.102:5000" ],
>             connect_interval : 1000,
>             connect_attempts : 5,
>             ...
>             replica_params : {
>                 mode_flags : [ force_sync ],
>                 ...
>             }
>         }

> The master side `master_ports` parameter defines one or more listener ports, thus supporting the multi-channel runtime configuration. The replica side `connection_strings` parameter defines a list of IP addresses to connect to the master in the replica mode. If the connection strings are present, xSQL initializes itself in replica mode and attempts to connect to the list of master nodes defined by this parameter. The number of connect attempts is defined through the `connect_attempts` parameter and the time interval between the attempts is defined by the value of the `connect_interval` parameter. If xSQL is unable to connect to either of the master nodes listed in the `connection_strings` list and the `master_ports` are present, then xSQL turns into master mode. If the `master_ports` are undefined, then xSQL quits. Consequently, if the `connection_strings` are undefined, but the `master_ports` are, then xSQL runs as a master.

> The following table lists the possible options for the `ha_params` section with the corresponding C API structures and values specified in the comment:

> Option,
> in "name : example value" form
> Description
> master_ports : [ ":tcp:6100", ":udp:6100" ],

> Address(es) of master(s). Transport-dependend, ":tcp:5000" (or just "5000"), ":udp:5000" or ":pipe:/tmp/test00"

> (See also mco_HA_attach_replica() )

> master_params : {...}
> Master parameters. Corresponds to `mco_HA_master_params_t` structure (See below Master_Params)
> keep_alive_interval : 1000,
> Interval between keep-alive messages in milliseconds
> trans_window_size : 10,
> Transaction window size (See also `mco_HA_set_trans_window_size()`)
> connect_timeout : 2000,

> Connection timeout period in milliseconds, used on both master and replica sides.

> (See `mco_HA_attach_master()` and `mco_HA_attach_replica()`)

> connection_strings: [ "192.168.1.100:5000", "192.168.1.102:5000" ],

> Connection string(s). Transport-dependent, ":tcp:192.168.1.100:5000" (or just # "192.168.1.100:5000"), ":udp:192.168.1.100:5000" or ":pipe:/tmp/test00"

> xSQL will try to connect to addresses in a round-robin manner

> connect_interval : 1000,
> Interval between connection attempts in milliseconds, unsigned
> connect_attempts : 5,
> Maximum number of connect rounds, unsigned
> cancel_port : 4321,
> Number of port used for cancel socket. If 0, cancellation will be disabled. Default value is 9990
> replica_params : {...}
> Replica parameters. Corresponds to `mco_HA_replica_params_t` structure (See below Replica_Params)
> switch_mode : "master",

> Defines the initial HA switch mode. Possible values are "auto" (default), "master", "replica" or "standalone".

> In the "auto" mode, if the xSQLconfiguration file specifies master and replica side parameters, the HA runtime runs xSQL in a replica mode and makes several attempts to connect to the master node. If those attempts are unsuccessful, then xSQLis runs as a master.

> In the "master" mode xSQL will only be run s a master, regardless of the replica parameters in its configuration file; in the "replica" mode xSQL only runs as a replica, again regardless of the master parameters in the config file. In the "standalone" mode the xSQL server temporarily ignores HA all together.

> (function `xsql_ha_set_switch_mode()` can be called to change the `switch_mode` at runtime)

> ## Master_Params

> The `ha_params::master_params` section is defined as follows:

> Option,
> in "name : example value" form
> Description
> mode_flags : hotsync,

> Master modes & options flags (`mco_HA_master_params_t::mode_flags`). Combination of

> `mcast_reliable` (`MCO_HAMODE_MCAST_RELIABLE`),

> `hotsync` (`MCO_HAMODE_HOTSYNCH`) and

> `binevolution` (`MCO_HAMODE_BINEVOLUTION`)

> (Other modes are enabled automatically - see below)

> max_number_of_replicas : 10,
> Maximum number of replicas that can connect to master `(mco_HA_master_params_t::max_number_of_replicas`), unsigned
> quorum : 1
> Initial value for the HA quorum
> async_databuf_size : 100m,

> Size of buffer for asynchronous replication in bytes (`mco_HA_master_params_t::async_databuf::size`), unsigned

> (If not 0, enables async replication mode (`MCO_HAMODE_ASYNC`))

> trans_log_length : 100,

> Maximum number of transactions stored on master side (`mco_HA_master_params_t::trans_log_length`), unsigned

> (If not 0, enables stateful replication (`MCO_HAMODE_STATEFUL_REPLICATION`))

> commit_timeout : 2000,
> Timeout to send transaction in milliseconds (`mco_HA_master_params_t::commit_timeout`), unsigned
> initial_timeout : 60000,
> Initial synchronization timeout in milliseconds (`mco_HA_master_params_t::initial_timeout`), unsigned
> synch_timeout : 2000,
> Timeout for waiting replica's ACK in milliseconds (`mco_HA_master_params_t::synch_timeout`), unsigned
> detach_timeout : 1000,
> Timeout for detaching replica in milliseconds (`mco_HA_master_params_t::detach_timeout`), unsigned
> mcast_address : "224.0.0.1:12345",

> Multicast address in form "<IP/hostname>:<port>" or "<port>" (`mco_HA_master_params_t::mcast_addr` and `mco_HA_master_params_t::mcast_port`), string

> ( Enables multicast replication mode (`MCO_HAMODE_MCAST`))

> hotsync_msg_objects : 100,

> Number of objects to send at once during hot-synchronization (`mco_HA_master_params_t::hotsync_msg_objects`), unsigned

> (Makes sense only if `hotsync` mode)

> hotsync_msg_size : 100k

> Max message size during hot-synchronization in bytes (`mco_HA_master_params_t::hotsync_msg_size`), unsigned

> (Makes sense only if `hotsync` mode)

> compression_level : 9,
> The level of compression: 0 - no compression; 1 - best speed, 9 - best compression. Default value is 0
> ssl_params : {...}
> Master-specific SSL settings. See the global `ssl_params` section for the description of the parameters and their default values. These parameters override the global settings. To inherit the global `ssl_params` settings, leave the `ssl_params` section empty. (They have the same parameters and default values as the global section, except for `ca_path` and `ca_file`, which are only allowed in the global section.)

> ## Replica_Params

> The `ha_params::relica_params` section is defined as follows:

> Option name : example value
> Comment
> mode_flags : [ force_sync ],

> Modes & options flags (mco_HA_replica_params_t::mode_flags). Combination of

> `force_master` (`MCO_HAMODE_FORCE_MASTER`) and

> `force_sync` (`MCO_HAMODE_FORCE_SYNC`)

> `MCO_HAMODE_EXPLICIT_WRITE_ACCESS`

> initial_timeout : 60000,
> Initial synchronization timeout in milliseconds (`mco_HA_replica_params_t::initial_timeout`), unsigned
> commit_timeout : 2000,
> Timeout to receive transaction data from master in milliseconds (`mco_HA_replica_params_t::commit_timeout`), unsigned
> wait_data_timeout : 5000,
> Max time between two consecutive transactions in milliseconds (`mco_HA_replica_params_t::wait_data_timeout`), unsigned
> repeat_counter : 3,
> Max number of attempts to repeat commit for reliable multicast (`mco_HA_replica_params_t::repeat_counter`), unsigned
> mcast_address : "224.0.0.1:12345",
> # Multicast address in form "<IP/hostname>:<port>" or "<port>" (`mco_HA_replica_params_t::mcast_addr` and `mco_HA_replica_params_t::mcast_port`), string
> initial_commit_policy : no_sync,

> Disk commit policy during initial synchronization (`mco_HA_replica_params_t::initial_commit_policy`) One of :

> - `sync_flush` (`MCO_COMMIT_SYNC_FLUSH`),
> - `buffered` (`MCO_COMMIT_BUFFERED`),
> - `delayed` (`MCO_COMMIT_DELAYED`) or
> - `no_sync` (`MCO_COMMIT_NO_SYNC`)
> initial_objs_in_trans : 100
> Number of objects per transaction during initial synchronization (`mco_HA_replica_params_t::initial_objs_in_trans`), unsigned
> ssl_params : {...}
> Replica-specific SSL settings. See the global ``ssl_params`` section for the description of the parameters and their default values. These parameters override the global settings. To inherit the global `ssl_params` settings, leave the `ssl_params` section empty. (They have the same parameters and default values as the global section, except for `ca_path` and `ca_file`, which are only allowed in the global section.)
> batch_commit_length : 10,
> The maximum number of the transactions (coming from master) that can be merged on the replica side. Default value is 0 (no limit) (See C structure `HA_Params` for further details)
> batch_commit_bsize : 100k,
> The maximum total size of the serialized transactions (in bytes) that can be merged on the replica side. This parameter can be used to prevent merging a very large transactions. Default value is 0 (no limit) (See C structure `HA_Params` for further details)
> batch_commit_period : 1000,
> The maximum period of time (in milliseconds) that the commit on the replica can be delayed. This parameter helps in cases where master sends some number of transactions and then becomes idle, but `batch_commit_length` and/or `batch_commit_bsize` has not been reached. The `batch_commit_period` ensures that such batch transactions will eventually be commited during the specified period of time. Default value is 1000 (1 second) (See C structure `HA_Params` for further details)
> compression_level : 9,
> The level of compression: 0 = no compression; 1 = best speed, 9 - best compression. Default value is 0

> ## Note on Batch Commit Parameters

> If both `batch_commit_length` and `batch_commit_bsize` are 0, the batch commit is not used (regardless of `batch_commit_period` value). This is the default behavior.