DBtune agent setup

About the DBtune agent

DBtune offers a database monitoring agent that operates within your network, securely transmitting metric data to DBtune and applying new proposed configurations. The agent is available as a ready-to-use Docker image hosted on public repositories.

Prerequisites

Before setting up the DBtune agent, ensure the following requirements are met:

Network access

Please ask your infosec department to whitelist the following URL for external access: https://app.dbtune.com.

Database setup

1. Install pg_stat_statements

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

important

If manually installing by copying the .control, .sql, and .so files, make sure you use files that match your PostgreSQL version. Using incompatible versions (e.g., pg_stat_statements 1.4 with PostgreSQL 16) can cause errors, such as missing columns like total_exec_time.

2. Create a DBtune user

Create a dedicated database user for the DBtune agent:

CREATE USER dbtune WITH PASSWORD '{dbtune_password}';

Replace {dbtune_password} with a secure password.

3. Grant necessary permissions

Grant the DBtune user the required monitoring permissions:

GRANT pg_monitor TO dbtune;

The pg_monitor role provides read-only access to monitoring views and functions needed by the agent.

System requirements

• Superuser access to PostgreSQL
• PostgreSQL versions > 12
• OS: A Linux system
• Server hosting the database: On-prem server or self-managed cloud instance, e.g., EC2, GCE, Azure VM

note

Some managed database services (AWS RDS, Aurora, Google Cloud SQL, Aiven) handle these requirements differently. See your database-specific documentation for details.

How it works

The DBtune agent is a lightweight monitoring component that:

1. Collects performance metrics from your database server and system resources
2. Transmits metrics securely to the DBtune tuning service
3. Applies recommended configurations when approved by you
4. Operates within your network - it never transfers sensitive data like table contents or metadata

Deployment options

The agent can be deployed in multiple ways:

• Docker container (recommended for most users)
• Kubernetes using Helm charts or raw manifests
• Binary executable for direct installation on the host system
• Cloud-native deployments using platform-specific configurations (ECS, Cloud Run, etc.)

Security and privacy

The agent only retrieves performance metrics and configuration parameters from your database.

It does not access or transmit:

• Table data or row contents
• Database metadata (table names, column names, schemas)
• Query parameters or user data
• Credentials or authentication tokens

For more details on what data is collected, see agent monitoring and privacy.

Running the agent

Docker deployment

There are multiple ways to run the DBtune agent. The recommended approach for most users is using Docker containers. Below is a general example:

docker run --restart always --detach \
    -e DBT_POSTGRESQL_CONNECTION_URL="postgresql://..." \
    -e [PROVIDER_SPECIFIC_VARIABLES] \
    -e DBT_DBTUNE_SERVER_URL=https://app.dbtune.com \
    -e DBT_DBTUNE_API_KEY=your-dbtune-api-key \
    -e DBT_DBTUNE_DATABASE_ID=your-dbtune-database-id \
    public.ecr.aws/dbtune/dbtune/agent:latest [--provider-flag]

See your database-specific documentation for the complete setup command with all required variables.

• PostgreSQL
• AWS RDS for PostgreSQL
• AWS Aurora PostgreSQL
• Google Cloud SQL for PostgreSQL
• Aiven for PostgreSQL
• EnterpriseDB Postgres Advanced Server (EPAS)

Common environment variables

The following environment variables are common across all database platforms:

DBtune platform variables

Variable	Description
DBT_DBTUNE_SERVER_URL	URL of the DBtune server (typically https://app.dbtune.com).
DBT_DBTUNE_API_KEY	Your DBtune API key for authentication.
DBT_DBTUNE_DATABASE_ID	Database ID assigned by DBtune for this database instance.

tip

You will get the DBT_DBTUNE_* variables from the agent tab when setting up your database in the DBtune platform.

PostgreSQL connection variables

Variable	Description
DBT_POSTGRESQL_CONNECTION_URL	Connection URL to your PostgreSQL database (format: postgresql://user:password@host:port/dbname).
DBT_POSTGRESQL_INCLUDE_QUERIES	Optional: Whether to send query text to help identify queries in the DBtune platform (default is false).

Additional resources

• DBtune agent GitHub repository - Source code and detailed documentation