diff --git a/config.example.yml b/config.example.yml index 33587d521..f5fd13a06 100644 --- a/config.example.yml +++ b/config.example.yml @@ -23,6 +23,33 @@ database: # Database password. password: CHANGEME + # List of low-level database options that can be set to influence some Icinga DB internal default behaviours. + # Do not change the defaults if you don't have to! + options: + # Maximum number of connections Icinga DB is allowed to open in parallel to the database. + # By default, Icinga DB is allowed to open up to "16" connections whenever necessary. + # Setting this to a number less than or equal to "-1" allows Icinga DB to open an unlimited number of connections. + # However, it is not possible to set this option to "0". +# max_connections: 16 + + # Maximum number of queries allowed to connect to a single database table simultaneously. + # By default, Icinga DB is allowed to execute up to "8" queries of any kind, e.g. INSERT,UPDATE,DELETE + # concurrently on a given table. + # It is not possible to set this option to a smaller number than "1". +# max_connections_per_table: 8 + + # Maximum number of placeholders Icinga DB is allowed to use for a single SQL statement. + # By default, Icinga DB uses up to "8192" placeholders when necessary, which showed the + # best performance in terms of execution time and parallelism in our tests. + # It is not possible to set this option to a smaller number than "1". +# max_placeholders_per_statement: 8192 + + # Maximum number of rows Icinga DB is allowed to select, delete, update or insert in a single transaction. + # By default, Icinga DB selects,deletes,updates,inserts up to "8192" rows in a single transaction, which showed + # the best performance in terms of execution time and parallelism in our tests. + # It is not possible to set this option to a smaller number than "1". +# max_rows_per_transaction: 8192 + # Connection configuration for the Redis server where Icinga 2 writes its configuration, state and history items. # This is the same connection as configured in the 'icingadb' feature of the corresponding Icinga 2 node. # High availability setups require a dedicated Redis server per Icinga 2 node and diff --git a/doc/03-Configuration.md b/doc/03-Configuration.md index e059722b8..5eb77575a 100644 --- a/doc/03-Configuration.md +++ b/doc/03-Configuration.md @@ -29,19 +29,38 @@ This is also the database used in [Icinga DB Web](https://icinga.com/docs/icinga-db-web) to view and work with the data. In high availability setups, all Icinga DB instances must write to the same database. -| Option | Description | -|----------|--------------------------------------------------------------------------------------------------------| -| type | **Optional.** Either `mysql` (default) or `pgsql`. | -| host | **Required.** Database host or absolute Unix socket path. | -| port | **Optional.** Database port. By default, the MySQL or PostgreSQL port, depending on the database type. | -| database | **Required.** Database name. | -| user | **Required.** Database username. | -| password | **Optional.** Database password. | -| tls | **Optional.** Whether to use TLS. | -| cert | **Optional.** Path to TLS client certificate. | -| key | **Optional.** Path to TLS private key. | -| ca | **Optional.** Path to TLS CA certificate. | -| insecure | **Optional.** Whether not to verify the peer. | +| Option | Description | +|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| type | **Optional.** Either `mysql` (default) or `pgsql`. | +| host | **Required.** Database host or absolute Unix socket path. | +| port | **Optional.** Database port. By default, the MySQL or PostgreSQL port, depending on the database type. | +| database | **Required.** Database name. | +| user | **Required.** Database username. | +| password | **Optional.** Database password. | +| tls | **Optional.** Whether to use TLS. | +| cert | **Optional.** Path to TLS client certificate. | +| key | **Optional.** Path to TLS private key. | +| ca | **Optional.** Path to TLS CA certificate. | +| insecure | **Optional.** Whether not to verify the peer. | +| options | **Optional.** List of low-level database options that can be set to influence some Icinga DB internal default behaviours. See [database options](#database-options) for details. | + +### Database Options + +Each of these configuration options are highly technical with thoroughly considered and tested default values that you +should only change when you exactly know what you are doing. You can use these options to influence the Icinga DB default +behaviour, how it interacts with databases, thus the defaults are usually sufficient for most users and do not need any +manual adjustments. + +!!! important + + Do not change the defaults if you do not have to! + +| Option | Description | +|--------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------| +| max_connections | **Optional.** Maximum number of database connections Icinga DB is allowed to open in parallel if necessary. Defaults to `16`. | +| max_connections_per_table | **Optional.** Maximum number of queries Icinga DB is allowed to execute on a single table concurrently. Defaults to `8`. | +| max_placeholders_per_statement | **Optional.** Maximum number of placeholders Icinga DB is allowed to use for a single SQL statement. Defaults to `8192`. | +| max_rows_per_transaction | **Optional.** Maximum number of rows Icinga DB is allowed to `SELECT`,`DELETE`,`UPDATE` or `INSERT` in a single transaction. Defaults to `8192`. | ## Logging Configuration