Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document database.options properly #723

Merged
merged 1 commit into from
Mar 28, 2024
Merged

Document database.options properly #723

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions config.example.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
yhabteab marked this conversation as resolved.
Show resolved Hide resolved
# 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.
yhabteab marked this conversation as resolved.
Show resolved Hide resolved
# 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
Expand Down
45 changes: 32 additions & 13 deletions doc/03-Configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading