# Database Configuration Reference

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).

## Modes

Use [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-configuration-files) to open `netdata.conf` and set your preferred mode:

```text
[db]
  # dbengine, ram, none
  db = dbengine
```

`mode` is also accepted for backwards compatibility.

## Tiers

### Retention Settings

:::note

In a Parent-Child setup, these settings control the Parent's total storage for metrics collected locally and metrics received from Children.

Child and Parent storage are independent:

- A Child can keep local history based on its own `[db].db`.
- Streamed metrics can also be persisted on the Parent, in the Parent's own dbengine files.

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).

:::

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:

| Setting                        | Retention Behavior                                                                                                                       |
|--------------------------------|------------------------------------------------------------------------------------------------------------------------------------------|
| Size Limit = 0, Time Limit > 0 | **Time based:** data is stored for a specific duration regardless of disk usage                                                          |
| Time Limit = 0, Size Limit > 0 | **Space based:** data is stored with a disk space limit, regardless of time                                                              |
| 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 |

:::note

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).

:::

You can change these limits using [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-configuration-files) to open `netdata.conf`:

```text
[db]
    db = dbengine
    storage tiers = 3

    # Tier 0, per second data. Set to 0 for no limit.
    dbengine tier 0 retention size = 1GiB
    dbengine tier 0 retention time = 14d

    # Tier 1, per minute data. Set to 0 for no limit.
    dbengine tier 1 retention size = 1GiB
    dbengine tier 1 retention time = 3mo

    # Tier 2, per hour data. Set to 0 for no limit.
    dbengine tier 2 retention size = 1GiB
    dbengine tier 2 retention time = 2y
```

### Update Every and Tier Granularity

`[db].update every` sets the base data collection interval. It accepts whole-second values in the 1–3600 seconds range; values outside this range are clamped to the nearest bound. Tier 0 stores data at this interval, and every higher tier derives its granularity by multiplying from the tier below it. The per-tier multiplier is `dbengine tier X update every iterations` (`60` by default for each tier above 0), so the effective resolution of a tier is `update every` multiplied by every multiplier below it:

| `update every` | Tier 0 | Tier 1 (`×60`) | Tier 2 (`×60×60`) |
|:--------------:|:------:|:--------------:|:-----------------:|
| `1s` (default) | 1s     | 60s            | 3600s (1 hour)    |
| `5s`           | 5s     | 300s           | 18000s (5 hours)  |

Changing `update every` shifts the resolution of every tier proportionally, but the per-tier **retention time** limits (`dbengine tier X retention time`) are wall-clock durations and do **not** change automatically — you do not need to lower retention when you raise `update every`.

Because a longer `update every` collects fewer samples per unit of time, the same per-tier disk size holds more time of data, so you may optionally reduce `dbengine tier X retention size`. For the full disk-sizing implications, see [Disk Requirements & Retention](/docs/netdata-agent/sizing-netdata-agents/disk-requirements-and-retention.md).

In a Parent-Child setup, each Child streams its own `update every` to the Parent. The Parent stores that Child's metrics at the Child's collection interval, so a Child's `update every` affects only that Child's data granularity on the Parent. The Parent's `[db].update every` applies only to metrics the Parent collects locally.

### Legacy Configuration

<details>
<summary><strong>v1.99.0 and prior</strong></summary>

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.

```text
storage tiers = 3
# Tier 0, per second data. Set to 0 for no limit.
dbengine tier 0 disk space MB = 1024
dbengine tier 0 retention days = 14
# Tier 1, per minute data. Set to 0 for no limit.
dbengine tier 1 disk space MB = 1024
dbengine tier 1 retention days = 90
# Tier 2, per hour data. Set to 0 for no limit.
dbengine tier 2 disk space MB = 1024
dbengine tier 2 retention days = 730
```

</details>

<details>
<summary><strong>v1.45.6 and prior</strong></summary>

Netdata versions prior to v1.46.0 relied on disk space-based retention.

**Default Retention Limits:**

| Tier | Resolution          | Size Limit |
|------|---------------------|------------|
| 0    | high (per second)   | 256 MB     |
| 1    | middle (per minute) | 128 MB     |
| 2    | low (per hour)      | 64 GiB     |

You can change these limits in `netdata.conf`:

```text
[db]
    mode = dbengine
    storage tiers = 3
    # Tier 0, per second data
    dbengine multihost disk space MB = 256
    # Tier 1, per minute data
    dbengine tier 1 multihost disk space MB = 1024
    # Tier 2, per hour data
    dbengine tier 2 multihost disk space MB = 1024
```

</details>

## Cache Sizes

There are two cache sizes that you can configure in `netdata.conf` to better optimize the Database:

1. `[db].dbengine page cache size`: controls the size of the cache that keeps metric data on memory.
2. `[db].dbengine extent cache size`: controls the size of the cache that keeps in memory compressed data blocks.

:::info

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.

:::

### Monitoring Cache Memory Usage

You can check how much memory the dbengine caches are currently consuming directly from the dashboard.

The total memory used by the database always appears as the **dbengine** dimension in the **Netdata Memory** chart (under the **Netdata** section → **Memory Usage** family). This gives a quick view of the database's overall memory footprint without any extra configuration.

For a detailed breakdown into individual caches, the dedicated dbengine cache charts require **extended pulse statistics**, which are disabled by default. To enable them, use [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-configuration-files) to open `netdata.conf` and set:

```text
[pulse]
    extended = yes
```

[Restart the Agent](/docs/netdata-agent/start-stop-restart.md) for the change to take effect. Once enabled, the following charts appear under the **Netdata** section:

- In the **dbengine memory** family, the **Netdata DB Memory** chart breaks total database memory down by component: main cache, open cache, extent cache, metrics registry, buffers, and allocator bookkeeping (aral structures, aral padding, pgd padding).
- In the **dbengine main cache**, **dbengine open cache**, and **dbengine extent cache** families:
  - **Netdata main Cache Memory**, **Netdata open Cache Memory**, and **Netdata extent Cache Memory** show how each cache's memory is distributed across its states — hot, dirty, clean, free, index, evicting, and flushing.
  - **Netdata main Target Cache Memory**, **Netdata open Target Cache Memory**, and **Netdata extent Target Cache Memory** show each cache's current memory size alongside its target (wanted) size.

To check whether your configured cache sizes provide enough headroom, compare the **current** value against the **wanted** value in the Target Cache Memory charts. When a cache consistently operates at its target, increasing `dbengine page cache size` or `dbengine extent cache size` may improve caching efficiency.
