Manage the database

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.

• Choose a database
• Configure the database connection
• SQLite companion files
• 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), 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.
• PostgreSQL (or PostgreSQL-compatible): a separate database server. Recommended for production use cases. Required for 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:

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

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

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