Nov 17, 202613 min read

Amazon RDS Proxy: When You Need It and How to Set It Up

What RDS Proxy does for PostgreSQL on RDS, when it pays for itself, how to create one with the AWS CLI or Terraform, how to connect Lambda functions and ECS services through it, what causes pinning, and how Encore handles database connections on AWS.

Illustration for Amazon RDS Proxy: When You Need It and How to Set It Up

Amazon RDS Proxy is a managed connection pooler for RDS and Aurora, and teams usually find it the week a Lambda function goes from ten concurrent invocations to five hundred and Postgres starts answering with too many connections. Each Postgres connection is a backend process with its own memory, and a fleet of short-lived clients that each open one can exhaust max_connections long before the CPU is busy.

This guide covers when RDS Proxy is worth its cost and when a sized pool is enough, how to create one with the AWS CLI and Terraform, how to connect Lambda functions and ECS services through it, which queries pin connections, and how Encore handles database connections for apps it deploys to AWS.

RDS Proxy at a glance

QuestionAnswer
What it doesPools and multiplexes client connections onto fewer database connections
EnginesRDS for PostgreSQL, MySQL, MariaDB, SQL Server, and Aurora PostgreSQL and MySQL
NetworkSame VPC as the database, never publicly accessible
Auth to the databaseSecrets Manager secret per database user, or end-to-end IAM
Auth from clientsDatabase password, or IAM tokens when IAMAuth is REQUIRED
PricingPer vCPU-hour of the target instances (2 vCPU minimum), per ACU-hour on Aurora Serverless v2 (8 ACU minimum)
Read replicasRDS instance targets are the writer only; Aurora can add reader endpoints
EncoreNot configured; services pool connections in-process against RDS or Aurora

Limits and auth options are from the RDS Proxy overview and the minimums from RDS Proxy pricing.

When you need RDS Proxy

Lambda is the clearest case, since each execution environment holds its own connection, concurrency can jump by hundreds in seconds, and environments are frozen and thawed with their connections still open, so the database sees a crowd of mostly idle sessions plus a burst of new TLS handshakes every time traffic spikes. The Lambda docs recommend a proxy for production for this reason, and AWS's planning guide adds instances that log too many connections errors, small T-class instances that run short of memory under connection load, and apps that open and close connections without a pool.

Faster failover is the second reason: during a Multi-AZ failover the proxy keeps accepting connections at the same address and routes them to the new primary, skipping the DNS caching delay, which AWS says cuts failover time by up to 66 percent for Multi-AZ DB instances. Connections in the middle of a transaction still fail, so retries stay in your code.

You usually do not need it for a handful of long-running services on ECS, EKS or EC2 that each keep a pool. Ten Fargate tasks with a pool of 20 open at most 200 connections, which an instance with max_connections at 1000 handles without help, and putting a proxy in front adds a network hop, a monthly charge based on the instance's vCPUs, and pinning rules to learn. The math changes when autoscaling can take tasks from 10 to 100, at which point the pools alone can reach 2,000 connections.

How RDS Proxy pools connections

Clients connect to the proxy endpoint as if it were the database. The proxy keeps a pool of database connections per target group, capped by MaxConnectionsPercent of the database's max_connections, and lends a connection to a client for the length of one transaction, a step AWS calls borrowing. When every connection is busy, new requests wait up to ConnectionBorrowTimeout, at most five minutes, and then fail with a timeout instead of piling more sessions onto Postgres.

Transaction-level reuse only works while no session state needs to survive between transactions. When the proxy sees a statement that changes session state, it pins that client to one database connection until the client disconnects, which turns pooling off for that client. For PostgreSQL the pinning rules include SET commands, SQL-level PREPARE and EXECUTE, temporary tables, cursors, LISTEN, session advisory locks such as pg_advisory_lock, sequence functions such as nextval, DISCARD ALL as a pool reset query, and any statement over 16 KB. Transaction-scoped advisory locks such as pg_advisory_xact_lock do not pin, and PostgreSQL proxies do not support session pinning filters, so settings you need on every connection belong in the proxy's initialization query.

Create RDS Proxy with the AWS CLI

The proxy logs in to Postgres as a real database user whose credentials live in Secrets Manager. Create a dedicated application user rather than using the master user, store it as a secret, and give the proxy a role that can read that secret:

~
# 1. The app user's credentials, as RDS Proxy expects them$ aws secretsmanager create-secret --name orders/db/orders_app \ --secret-string '{"username":"orders_app","password":"<strong password>"}' # 2. A role RDS can assume to read that secret$ aws iam create-role --role-name orders-db-proxy \ --assume-role-policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"Service":"rds.amazonaws.com"},"Action":"sts:AssumeRole"}]}'$ aws iam put-role-policy --role-name orders-db-proxy --policy-name read-db-secret \ --policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Action":"secretsmanager:GetSecretValue","Resource":"<secret ARN>"}]}' # 3. The proxy, in at least two private subnets, with TLS and IAM required from clients$ aws rds create-db-proxy --db-proxy-name orders --engine-family POSTGRESQL \ --role-arn arn:aws:iam::123456789012:role/orders-db-proxy \ --vpc-subnet-ids subnet-0a1 subnet-0b2 --vpc-security-group-ids sg-0proxy \ --require-tls \ --auth '[{"AuthScheme":"SECRETS","SecretArn":"<secret ARN>","IAMAuth":"REQUIRED","ClientPasswordAuthType":"POSTGRES_SCRAM_SHA_256"}]' # 4. Point the default target group at the database and size the pool$ aws rds register-db-proxy-targets --db-proxy-name orders --db-instance-identifiers orders-db$ aws rds modify-db-proxy-target-group --db-proxy-name orders --target-group-name default \ --connection-pool-config MaxConnectionsPercent=75,MaxIdleConnectionsPercent=25,ConnectionBorrowTimeout=30 # 5. Wait for the target to report AVAILABLE, then read the endpoint$ aws rds describe-db-proxy-targets --db-proxy-name orders --query 'Targets[].TargetHealth.State'$ aws rds describe-db-proxies --db-proxy-name orders --query 'DBProxies[0].Endpoint'

The proxy's security group needs inbound 5432 from your app's security group and outbound 5432 to the database, and the database's group needs inbound 5432 from the proxy. Keep MaxConnectionsPercent below 100 when other clients, such as migrations or a reporting tool, connect to the database directly. The flags are from the create-db-proxy guide, which also covers end-to-end IAM, where the proxy logs in to the database with IAM instead of a stored secret.

Create RDS Proxy with Terraform

The same setup as Terraform, validated with Terraform 1.13 and AWS provider 6.73, assuming the VPC, subnets and RDS instance already exist:

# rds_proxy.tf variable "vpc_id" { type = string } variable "private_subnet_ids" { type = list(string) } variable "db_instance_id" { type = string } variable "db_security_group_id" { type = string } variable "app_security_group_id" { type = string } variable "db_user_secret_arn" { type = string description = "Secrets Manager secret with {\"username\":...,\"password\":...} for the app's database user" } # The role RDS Proxy assumes to read the database user's secret. resource "aws_iam_role" "proxy" { name = "orders-db-proxy" assume_role_policy = jsonencode({ Version = "2012-10-17" Statement = [{ Effect = "Allow" Principal = { Service = "rds.amazonaws.com" } Action = "sts:AssumeRole" }] }) } resource "aws_iam_role_policy" "proxy_secrets" { role = aws_iam_role.proxy.id policy = jsonencode({ Version = "2012-10-17" Statement = [{ Effect = "Allow" Action = ["secretsmanager:GetSecretValue"] Resource = [var.db_user_secret_arn] }] }) } resource "aws_security_group" "proxy" { name = "orders-db-proxy" vpc_id = var.vpc_id } # Apps reach the proxy on 5432. resource "aws_vpc_security_group_ingress_rule" "proxy_from_app" { security_group_id = aws_security_group.proxy.id referenced_security_group_id = var.app_security_group_id ip_protocol = "tcp" from_port = 5432 to_port = 5432 } # The proxy reaches the database on 5432. resource "aws_vpc_security_group_egress_rule" "proxy_to_db" { security_group_id = aws_security_group.proxy.id referenced_security_group_id = var.db_security_group_id ip_protocol = "tcp" from_port = 5432 to_port = 5432 } resource "aws_vpc_security_group_ingress_rule" "db_from_proxy" { security_group_id = var.db_security_group_id referenced_security_group_id = aws_security_group.proxy.id ip_protocol = "tcp" from_port = 5432 to_port = 5432 } resource "aws_db_proxy" "orders" { name = "orders" engine_family = "POSTGRESQL" role_arn = aws_iam_role.proxy.arn vpc_subnet_ids = var.private_subnet_ids vpc_security_group_ids = [aws_security_group.proxy.id] require_tls = true idle_client_timeout = 1800 auth { auth_scheme = "SECRETS" secret_arn = var.db_user_secret_arn iam_auth = "REQUIRED" client_password_auth_type = "POSTGRES_SCRAM_SHA_256" } } resource "aws_db_proxy_default_target_group" "orders" { db_proxy_name = aws_db_proxy.orders.name connection_pool_config { max_connections_percent = 75 max_idle_connections_percent = 25 connection_borrow_timeout = 30 } } resource "aws_db_proxy_target" "orders" { db_proxy_name = aws_db_proxy.orders.name target_group_name = aws_db_proxy_default_target_group.orders.name db_instance_identifier = var.db_instance_id } output "proxy_endpoint" { value = aws_db_proxy.orders.endpoint } data "aws_caller_identity" "current" {} data "aws_region" "current" {} # Attach to the Lambda execution role or ECS task role that connects through the proxy. resource "aws_iam_policy" "connect_via_proxy" { name = "orders-db-proxy-connect" policy = jsonencode({ Version = "2012-10-17" Statement = [{ Effect = "Allow" Action = "rds-db:connect" Resource = "arn:aws:rds-db:${data.aws_region.current.region}:${data.aws_caller_identity.current.account_id}:dbuser:${element(split(":", aws_db_proxy.orders.arn), 6)}/orders_app" }] }) }

The rds-db:connect resource uses the proxy's resource ID, the prx-... part of its ARN, rather than the database's, since clients authenticate to the proxy and not to the instance. For a fuller RDS setup in Terraform, see RDS with Terraform.

Connect a Lambda function through RDS Proxy

Put the function in the proxy's VPC with a security group the proxy allows, attach the connect_via_proxy policy to its execution role, and create the pool outside the handler so every invocation in an execution environment reuses it. With IAMAuth set to REQUIRED, the password is a short-lived token signed with the function's role, generated by @aws-sdk/rds-signer:

// handler.ts import { Signer } from "@aws-sdk/rds-signer"; import type { APIGatewayProxyHandlerV2 } from "aws-lambda"; import pg from "pg"; const host = process.env.PROXY_ENDPOINT!; // orders.proxy-xxxx.us-east-1.rds.amazonaws.com const user = process.env.DB_USER!; // orders_app, the user in the proxy's secret const signer = new Signer({ hostname: host, port: 5432, username: user }); // Created once per execution environment and reused across invocations. // One connection per environment: Lambda runs one request at a time in it, // and the proxy multiplexes these client connections onto a smaller pool. const pool = new pg.Pool({ host, port: 5432, user, database: "orders", password: () => signer.getAuthToken(), // a fresh 15 minute IAM token per new connection ssl: true, // RDS Proxy presents an ACM certificate, trusted by Node's default CA store max: 1, idleTimeoutMillis: 60_000, }); export const handler: APIGatewayProxyHandlerV2 = async (event) => { const id = event.pathParameters?.id; if (!id) return { statusCode: 400, body: "missing id" }; const { rows } = await pool.query( "SELECT id, status, total_cents FROM orders WHERE id = $1", [id], ); if (rows.length === 0) return { statusCode: 404, body: "not found" }; return { statusCode: 200, body: JSON.stringify(rows[0]) }; };

The token is only checked when a connection opens, so a long-lived connection keeps working after its token expires, and pg calls the password function again for each new connection. RDS Proxy uses certificates from AWS Certificate Manager, so unlike a direct RDS connection there is no RDS CA bundle to ship with the function. The Lambda console can also do the wiring for you under Configuration > RDS databases > Connect to RDS database, followed by Add proxy.

Connect ECS services through RDS Proxy

An ECS service keeps its own pool and only changes its host to the proxy endpoint, with the task role holding rds-db:connect and the same token approach, or with a password from Secrets Manager if the proxy's IAMAuth is DISABLED. The proxy does not remove the need to size pools: each task's pool size times the maximum task count should stay within what the proxy is allowed to borrow, and a borrow timeout shorter than your request timeout makes overload show up as fast, clear errors instead of slow requests. For the network and task role setup without a proxy, see connecting ECS Fargate to RDS.

Watch DatabaseConnectionsCurrentlySessionPinned in CloudWatch after switching. If it tracks your client connection count, something in the session is pinning, often a SET in a connection setup hook or a pool's DISCARD ALL reset. Drivers that cache prepared statements are worth testing too: pgx does by default, and adding default_query_exec_mode=exec to its connection string turns that off if the pinned count stays high.

How Encore handles database connections on AWS

Encore

Encore brings infrastructure from code to Postgres on AWS: a database declared in a Go or TypeScript service becomes a logical database on an RDS for PostgreSQL instance or an Aurora PostgreSQL cluster in your own AWS account, in private subnets that only accept connections from your services, as the AWS infrastructure docs describe. Encore does not create an RDS Proxy. Services run as long-running containers on Fargate or EKS rather than as Lambda functions, and each process keeps a pool per database, so the burst of short-lived connections that RDS Proxy exists to absorb does not come from the app.

Set up the app

Get started
brew install encoredev/tap/encore &&
encore app create
Copy

Run in your terminal to get started locally.

~
$ encore app create shop --example=hello-world$ cd shop && mkdir -p orders/migrations
// orders/orders.go package orders import ( "context" "errors" "encore.dev/beta/errs" "encore.dev/storage/sqldb" ) // Becomes a database on the environment's RDS or Aurora server on AWS. // The Go runtime keeps one pgx pool per database in each process. var db = sqldb.NewDatabase("orders", sqldb.DatabaseConfig{ Migrations: "./migrations", }) type Order struct { ID int64 `json:"id"` Status string `json:"status"` TotalCents int64 `json:"total_cents"` } type CreateParams struct { TotalCents int64 `json:"total_cents"` } //encore:api public method=POST path=/orders func Create(ctx context.Context, p *CreateParams) (*Order, error) { if p.TotalCents <= 0 { return nil, &errs.Error{Code: errs.InvalidArgument, Message: "total_cents must be positive"} } o := &Order{Status: "pending", TotalCents: p.TotalCents} err := db.QueryRow(ctx, `INSERT INTO orders (status, total_cents) VALUES ($1, $2) RETURNING id`, o.Status, o.TotalCents, ).Scan(&o.ID) return o, err } //encore:api public method=GET path=/orders/:id func Get(ctx context.Context, id int64) (*Order, error) { o := &Order{ID: id} err := db.QueryRow(ctx, `SELECT status, total_cents FROM orders WHERE id = $1`, id, ).Scan(&o.Status, &o.TotalCents) if errors.Is(err, sqldb.ErrNoRows) { return nil, &errs.Error{Code: errs.NotFound, Message: "order not found"} } return o, err }
-- orders/migrations/1_create_orders.up.sql CREATE TABLE orders ( id BIGSERIAL PRIMARY KEY, status TEXT NOT NULL, total_cents BIGINT NOT NULL CHECK (total_cents > 0), created_at TIMESTAMPTZ NOT NULL DEFAULT now() );
~/shop
$ encore run$ curl -X POST localhost:4000/orders -d '{"total_cents":4200}'{"id":1,"status":"pending","total_cents":4200}$ curl localhost:4000/orders/1{"id":1,"status":"pending","total_cents":4200}

encore run starts Postgres locally and applies the migration, and the same code deploys to AWS, where migrations run on each deploy. The Go database docs cover the query API and db.Stdlib() for code that expects database/sql.

Connection math on Encore

In Encore's Go runtime each database pool is a pgx pool capped at 30 connections per process unless the environment's runtime configuration sets another maximum, with connection lifetimes jittered so that tasks started by the same deploy do not reconnect at the same moment. A new RDS instance comes up Multi-AZ with max_connections at 1000, and that value can be raised per environment in the Encore dashboard along with the instance class, with a change to max connections rebooting the instance. Ten containers using one database therefore stay at or below 300 connections, and the number to check when you raise task counts is containers times 30 against max_connections.

Each container also connects with its own Postgres login role, a member of a per-service role that can only reach the databases that service uses, and you can view and rotate those credentials as described in managing database users. For an existing RDS or Aurora database, including one that already has a proxy for other clients, importing it connects your Encore services to the server directly while the database stays yours.

The database is declared next to the code that queries it, so an AI coding agent that adds a table and an endpoint does both in one change and can run it against a local Postgres with encore run before anything reaches AWS.

Best fit: teams on AWS that want Postgres on RDS or Aurora in their own account, with pools, roles and migrations set up from the services that use them.

RDS Proxy pricing and limits

RDS Proxy is billed per vCPU-hour of the instances behind it, with a minimum of 2 vCPUs, or per ACU-hour consumed on Aurora Serverless v2, with a minimum of 8 ACUs, so a proxy in front of a db.m5.large costs the same whether it serves ten clients or ten thousand. Each account can have 20 proxies by default, each proxy up to 200 secrets and 20 extra endpoints, and the default endpoint spans two Availability Zones. The proxy cannot be reached from outside its VPC, so local development needs a bastion, VPN or SSM port forwarding, the same options covered in connecting to a private RDS database from your laptop.

Frequently asked questions

What is Amazon RDS Proxy?

RDS Proxy is a managed connection pooler that sits between your application and an RDS or Aurora database inside your VPC. Clients connect to the proxy endpoint, and the proxy shares a smaller set of database connections between them, reusing a connection at the end of each transaction unless the session is pinned.

When do I need RDS Proxy?

Use it when many short-lived clients, most often Lambda functions, open more connections than the database can hold, when you see too many connections errors after scaling out, or when you want faster, less disruptive Multi-AZ failovers. A small number of long-running containers that each keep a sized connection pool usually do not need it.

How do I connect a Lambda function to RDS Proxy?

Put the function in the proxy's VPC, allow its security group to reach the proxy on port 5432, and grant its execution role rds-db:connect on the proxy's dbuser ARN. In Node, create a pg Pool outside the handler with max set to 1, ssl enabled, and a password function that returns a token from the Signer in @aws-sdk/rds-signer.

Does Encore set up RDS Proxy?

Encore does not create an RDS Proxy: it runs services on AWS as long-running containers on Fargate or EKS, and the Go runtime keeps a connection pool per database in each process, 30 connections by default, against an RDS or Aurora server with max_connections at 1000 by default. If you need RDS Proxy for other clients, you create it yourself in your AWS account.

Deploy to your cloud on AWS and Google Cloud
without managing infrastructure

Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders