AWS - RDS PostgreSQL

RDS PostgreSQL agent setup

For an overview of how the DBtune agent works, see agent overview.

Prerequisites

Before starting the DBtune agent, ensure you have completed the database setup steps.

AWS Parameter group for RDS

Create a custom parameter group and assign it to the RDS database instance. DBtune will tune the database parameters through the parameter group, we recommend to have one custom parameter group per database that will be tuned through DBtune.

AWS IAM permissions

The policy below contains the permissions required by the agent to collect metrics and perform tuning. The policy can be applied through a role granted to an IAM user or anywhere across the AWS login chain. The rds:RebootDBInstance permission is only required if you want to perform tuning with restart.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "DescribeRDSInstanceTypes",
            "Effect": "Allow",
            "Action": "ec2:DescribeInstanceTypes",
            "Resource": "*"
        },
        {
            "Sid": "DescribeDBInstance",
            "Effect": "Allow",
            "Action": [
                "rds:DescribeDBInstances",
            ],
            "Resource": "*"
        },
        {
            "Sid": "GetDBMetrics",
            "Effect": "Allow",
            "Action": [
                "cloudwatch:GetMetricStatistics",
                "pi:GetResourceMetrics"
            ],
            "Resource": "*"
        },
        {
            "Sid": "ModifyDBParameterGroup",
            "Effect": "Allow",
            "Action": [
                "rds:ModifyDBParameterGroup"
            ],
            "Resource": "*"
        },
        {
            "Sid": "RebootDBInstance",
            "Effect": "Allow",
            "Action": [
                "rds:RebootDBInstance"
            ],
            "Resource": "*"
        }
    ]
}

Setting up the agent

Run the DBtune agent using Docker with RDS-specific configuration:

docker run --restart always --detach \
    -e DBT_POSTGRESQL_CONNECTION_URL="postgresql://..." \
    -e DBT_RDS_DATABASE_IDENTIFIER={rds_database_identifier} \
    -e DBT_RDS_PARAMETER_GROUP_NAME={parameter_group_name} \
    -e DBT_AWS_REGION={aws_region} \
    -e DBT_AWS_ACCESS_KEY_ID={aws_access_key_id} \
    -e DBT_AWS_SECRET_ACCESS_KEY={aws_secret_access_key} \
    -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 --rds

info

AWS credentials (DBT_AWS_ACCESS_KEY_ID and DBT_AWS_SECRET_ACCESS_KEY) are optional. If not provided, the agent will use the default AWS credential chain, which includes WebIdentity tokens.

For information about common environment variables (DBT_DBTUNE_* and DBT_POSTGRESQL_*), see agent overview - common environment variables.

AWS RDS-specific environment variables

Variable	Description
DBT_RDS_DATABASE_IDENTIFIER	Identifier of the RDS instance you want to optimize.
DBT_RDS_PARAMETER_GROUP_NAME	Name of the parameter group for the instance.
DBT_AWS_ACCESS_KEY_ID	(Optional) AWS access key ID that DBtune will use to authenticate with AWS services.
DBT_AWS_SECRET_ACCESS_KEY	(Optional) AWS secret access key that DBtune will use to authenticate with AWS services.
DBT_AWS_REGION	AWS region where your database is located.

Parameters tuned

DBtune supports multiple tuning modes that determine which parameters can be optimized. For a detailed explanation of tuning modes, see tuning modes.

Reload-only tuning mode

The following parameters are tuned in reload-only mode:

1. work_mem
2. random_page_cost
3. seq_page_cost
4. checkpoint_completion_target
5. effective_io_concurrency
6. max_parallel_workers_per_gather
7. max_parallel_workers
8. max_wal_size
9. min_wal_size
10. bgwriter_lru_maxpages
11. bgwriter_delay
12. effective_cache_size
13. maintenance_work_mem
14. default_statistics_target
15. max_parallel_maintenance_workers

Restart tuning mode

The following parameters are tuned in restart mode, in addition to all reload-only parameters:

16. shared_buffers
17. max_worker_processes
18. wal_buffers