| 1 | # Database Configuration Reference |
| 2 | |
| 3 | You can configure the Agent's Database through the database settings. For a deeper understanding of the Database components, see the [Database overview](/src/database/README.md). |
| 4 | |
| 5 | ## Modes |
| 6 | |
| 7 | Use [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-configuration-files) to open `netdata.conf` and set your preferred mode: |
| 8 | |
| 9 | ```text |
| 10 | [db] |
| 11 | # dbengine, ram, none |
| 12 | mode = dbengine |
| 13 | ``` |
| 14 | |
| 15 | ## Tiers |
| 16 | |
| 17 | ### Retention Settings |
| 18 | |
| 19 | :::note |
| 20 | |
| 21 | In a Parent-Child setup, these settings control the Parent's total storage for metrics collected locally and metrics received from Children. |
| 22 | |
| 23 | Child and Parent storage are independent: |
| 24 | |
| 25 | - A Child can keep local history based on its own `[db].mode`. |
| 26 | - Streamed metrics can also be persisted on the Parent, in the Parent's own dbengine files. |
| 27 | |
| 28 | Retention size is enforced **per-tier**, not per Child, so all streaming Children share the Parent's tier quota. For Parent sizing guidance, see [Parent Retention Sizing](/docs/netdata-agent/sizing-netdata-agents/disk-requirements-and-retention.md#parent-retention-sizing). |
| 29 | |
| 30 | ::: |
| 31 | |
| 32 | You can fine-tune retention for each tier by setting a time limit or size limit. Setting a limit to 0 disables it. This enables the following retention strategies: |
| 33 | |
| 34 | | Setting | Retention Behavior | |
| 35 | |--------------------------------|------------------------------------------------------------------------------------------------------------------------------------------| |
| 36 | | Size Limit = 0, Time Limit > 0 | **Time based:** data is stored for a specific duration regardless of disk usage | |
| 37 | | Time Limit = 0, Size Limit > 0 | **Space based:** data is stored with a disk space limit, regardless of time | |
| 38 | | Time Limit > 0, Size Limit > 0 | **Combined time and space limits:** data is deleted once it reaches either the time limit or the disk space limit, whichever comes first | |
| 39 | |
| 40 | :::note |
| 41 | |
| 42 | Retention size limits are soft targets, not hard caps enforced at write time. Actual disk usage can temporarily exceed the configured limit. For the detailed enforcement behavior, see [Retention Size Enforcement](/src/database/README.md#retention-size-enforcement). |
| 43 | |
| 44 | ::: |
| 45 | |
| 46 | You can change these limits using [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-configuration-files) to open `netdata.conf`: |
| 47 | |
| 48 | ```text |
| 49 | [db] |
| 50 | mode = dbengine |
| 51 | storage tiers = 3 |
| 52 | |
| 53 | # Tier 0, per second data. Set to 0 for no limit. |
| 54 | dbengine tier 0 retention size = 1GiB |
| 55 | dbengine tier 0 retention time = 14d |
| 56 | |
| 57 | # Tier 1, per minute data. Set to 0 for no limit. |
| 58 | dbengine tier 1 retention size = 1GiB |
| 59 | dbengine tier 1 retention time = 3mo |
| 60 | |
| 61 | # Tier 2, per hour data. Set to 0 for no limit. |
| 62 | dbengine tier 2 retention size = 1GiB |
| 63 | dbengine tier 2 retention time = 2y |
| 64 | ``` |
| 65 | |
| 66 | ### Legacy Configuration |
| 67 | |
| 68 | <details> |
| 69 | <summary><strong>v1.99.0 and prior</strong></summary> |
| 70 | |
| 71 | Netdata prior to v2 supports the following configuration options in `netdata.conf`. They have the same defaults as the latest v2, but the unit of each value is given in the option name, not at the value. |
| 72 | |
| 73 | ```text |
| 74 | storage tiers = 3 |
| 75 | # Tier 0, per second data. Set to 0 for no limit. |
| 76 | dbengine tier 0 disk space MB = 1024 |
| 77 | dbengine tier 0 retention days = 14 |
| 78 | # Tier 1, per minute data. Set to 0 for no limit. |
| 79 | dbengine tier 1 disk space MB = 1024 |
| 80 | dbengine tier 1 retention days = 90 |
| 81 | # Tier 2, per hour data. Set to 0 for no limit. |
| 82 | dbengine tier 2 disk space MB = 1024 |
| 83 | dbengine tier 2 retention days = 730 |
| 84 | ``` |
| 85 | |
| 86 | </details> |
| 87 | |
| 88 | <details> |
| 89 | <summary><strong>v1.45.6 and prior</strong></summary> |
| 90 | |
| 91 | Netdata versions prior to v1.46.0 relied on disk space-based retention. |
| 92 | |
| 93 | **Default Retention Limits:** |
| 94 | |
| 95 | | Tier | Resolution | Size Limit | |
| 96 | |------|---------------------|------------| |
| 97 | | 0 | high (per second) | 256 MB | |
| 98 | | 1 | middle (per minute) | 128 MB | |
| 99 | | 2 | low (per hour) | 64 GiB | |
| 100 | |
| 101 | You can change these limits in `netdata.conf`: |
| 102 | |
| 103 | ```text |
| 104 | [db] |
| 105 | mode = dbengine |
| 106 | storage tiers = 3 |
| 107 | # Tier 0, per second data |
| 108 | dbengine multihost disk space MB = 256 |
| 109 | # Tier 1, per minute data |
| 110 | dbengine tier 1 multihost disk space MB = 1024 |
| 111 | # Tier 2, per hour data |
| 112 | dbengine tier 2 multihost disk space MB = 1024 |
| 113 | ``` |
| 114 | |
| 115 | </details> |
| 116 | |
| 117 | ## Cache Sizes |
| 118 | |
| 119 | There are two cache sizes that you can configure in `netdata.conf` to better optimize the Database: |
| 120 | |
| 121 | 1. `[db].dbengine page cache size`: controls the size of the cache that keeps metric data on memory. |
| 122 | 2. `[db].dbengine extent cache size`: controls the size of the cache that keeps in memory compressed data blocks. |
| 123 | |
| 124 | :::info |
| 125 | |
| 126 | Both of them are dynamically adjusted to use some of the total memory computed above. The configuration in `netdata.conf` allows providing additional memory to them, increasing their caching efficiency. |
| 127 | |
| 128 | ::: |