---
title: Manage the database
description: Telegraf Controller stores all application state in a SQLite (default) or PostgreSQL database. Learn where the database lives, how to configure it, and how to back it up and restore it.
url: https://docs.influxdata.com/telegraf/controller/admin/database/
estimated_tokens: 915
publisher: InfluxData
canonical: https://docs.influxdata.com/telegraf/controller/admin/database/
date: '2026-09-22T08:51:42-06:00'
lastmod: '2026-09-22T08:51:42-06:00'
---

Telegraf Controller stores all application state in a relational database:
configurations and configuration versions, configuration groups, agents,
labels, reporting rules, users, tokens, and settings.
Losing the database means losing all of this data, so operators should know
where the database lives, how to back it up, and how to repair it.
For database error messages and repair procedures, see[Troubleshoot the database](/telegraf/controller/admin/troubleshoot/database/).

* [Choose a database](#choose-a-database)
* [Configure the database connection](#configure-the-database-connection)
* [SQLite companion files](#sqlite-companion-files)
* [Audit log storage is separate](#audit-log-storage-is-separate)

## Choose a database

* **SQLite** (default): zero-setup embedded database.
  Recommended for development or light workloads.
  Data lives in a single local file that Telegraf Controller creates
  automatically on first run (for default file paths, see[Default SQLite data locations](/telegraf/controller/install/#default-sqlite-data-locations)),
  and backups are simple.
  SQLite supports one Telegraf Controller instance at a time, requires a
  local filesystem, and serializes writes, so a heavy agent workload can
  cause[lock contention](/telegraf/controller/admin/troubleshoot/database/#identify-the-failure-type).
* **PostgreSQL** (or PostgreSQL-compatible): a separate database server.
  Recommended for production use cases.
  Required for [high availability](/telegraf/controller/admin/high-availability/),
  and the right choice when you want the database on separate
  infrastructure from the Telegraf Controller host or want to reuse
  existing PostgreSQL backup, monitoring, and operations tooling.

## Configure the database connection

Use the `--database` command flag or the `DATABASE_URL` environment variable
to specify the database connection string:

```bash
# Use a custom SQLite database location
telegraf_controller --database="/path/to/database.db"

# Use PostgreSQL
telegraf_controller --database="postgresql://user:password@localhost:5432/telegraf_controller"
```

For the full list of database-related options, see the[configuration options reference](/telegraf/controller/reference/config-options/).

## SQLite companion files

While Telegraf Controller runs, SQLite creates two companion files next to
the database file: a write-ahead log (`sqlite.db-wal`) and a shared-memory
file (`sqlite.db-shm`).

> [!Warning]
> The `-wal` and `-shm` files are part of the database.
> Never delete, move, or edit them while they exist.
> Removing a write-ahead log can corrupt the database or silently discard
> recent writes.

Restrict access to the database file and its companion files, for example
with `chmod 600`, so only the user running Telegraf Controller can read
them.

## Audit log storage is separate

If you use [audit logging](/telegraf/controller/admin/audit-logs/),
Telegraf Controller writes audit records to separate per-month SQLite
files, not to the application database.
Include both in your backup strategy.
See[Back up and restore audit log files](/telegraf/controller/admin/database/back-up-and-restore/#back-up-and-restore-audit-log-files).

## [Back up and restore](/telegraf/controller/admin/database/back-up-and-restore/)

Back up the Telegraf Controller database safely while the server is running or stopped, and restore from a backup.

#### Related

* [Telegraf Controller configuration options](/telegraf/controller/reference/config-options/)
* [High availability](/telegraf/controller/admin/high-availability/)
* [Troubleshoot the database](/telegraf/controller/admin/troubleshoot/database/)