Skip to main content

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 database services (AWS RDS, Aurora, Google Cloud SQL, Aiven, Azure Flexible Server, CloudNativePG) 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 \
    -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

Kubernetes deployment​

The agent is a single stateless container — no persistent storage or Services are required.

Step 1 — Create a Secret

Storing credentials in a Kubernetes Secret is recommended rather than hardcoding them in the manifest:

kubectl create secret generic dbtune-agent \
  --from-literal=api-key=<your-api-key> \
  --from-literal=db-connection-string=postgresql://user:password@host:5432/dbname

Step 2 — Apply the Deployment

Save the following as dbtune-agent.yaml and apply it:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: dbtune-agent
spec:
  replicas: 1
  selector:
    matchLabels:
      app: dbtune-agent
  template:
    metadata:
      labels:
        app: dbtune-agent
    spec:
      containers:
        - name: dbtune-agent
          image: public.ecr.aws/dbtune/dbtune/agent:latest
          env:
            - name: DBT_DBTUNE_SERVER_URL
              value: "https://app.dbtune.com"
            - name: DBT_DBTUNE_API_KEY
              valueFrom:
                secretKeyRef:
                  name: dbtune-agent
                  key: api-key
            - name: DBT_DBTUNE_DATABASE_ID
              value: "<your-database-id>"
            - name: DBT_POSTGRESQL_CONNECTION_URL
              valueFrom:
                secretKeyRef:
                  name: dbtune-agent
                  key: db-connection-string
kubectl apply -f dbtune-agent.yaml

Step 3 — Verify

kubectl logs deployment/dbtune-agent

The agent connects outbound to your PostgreSQL instance and to app.dbtune.com. No inbound ports are needed.

tip

If your PostgreSQL is running on the same Kubernetes node, use the node's IP address in the connection string rather than localhost. Inside a pod, localhost refers to the pod itself, not the host.

Database-specific setup​

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

Common environment variables​

The following environment variables are common across all database platforms:

DBtune platform variables​

VariableDescription
DBT_DBTUNE_SERVER_URLURL of the DBtune server (typically https://app.dbtune.com).
DBT_DBTUNE_API_KEYYour DBtune API key for authentication.
DBT_DBTUNE_DATABASE_IDDatabase 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​

VariableDescription
DBT_POSTGRESQL_CONNECTION_URLConnection URL to your PostgreSQL database (format: postgresql://user:password@host:port/dbname).
DBT_POSTGRESQL_INCLUDE_QUERIESOptional: Whether to send query text to help identify queries in the DBtune platform (default is false).

Additional resources​

Last updated on