RDS Databases

With Docker enabled, RDS instances run real database servers. You can connect with psql, mysql, or any database client and execute SQL against them.

Prerequisites

  • SIMFRA_DOCKER=true
  • Docker images for your database engine will be pulled automatically on first use

Supported Engines

Engine Default Image Default Port
postgres postgres:16 5432
mysql mysql:8.0 3306
mariadb mariadb:10.11 3306
aurora-postgresql postgres:16 5432
aurora-mysql mysql:8.0 3306

Override images with SIMFRA_RDS_IMAGE_POSTGRES, SIMFRA_RDS_IMAGE_MYSQL, or SIMFRA_RDS_IMAGE_MARIADB.

Creating an Instance

aws --endpoint-url http://localhost:4599 rds create-db-instance \
  --db-instance-identifier mydb \
  --engine postgres \
  --master-username admin \
  --master-user-password mypassword \
  --db-instance-class db.t3.micro

The instance starts in creating state. A background worker transitions it to available once the Docker container is running and the database is ready to accept connections. This typically takes a few seconds.

Connecting to the Database

Public Instances (PubliclyAccessible=true)

When an instance is publicly accessible, Simfra publishes its database port to the host from the SIMFRA_RDS_PORT_RANGE (default 10400-10499).

Find the assigned port in the API response:

aws --endpoint-url http://localhost:4599 rds describe-db-instances \
  --db-instance-identifier mydb \
  --query 'DBInstances[0].Endpoint'

{
  "Address": "mydb.abcdef123456.us-east-1.rds.simfra.dev",
  "Port": 10400
}

Connect:

psql -h localhost -p 10400 -U admin -d postgres

Private Instances (Default)

By default, RDS instances are private. No host ports are published. Access from:

  • Lambda or ECS containers on the same VPC network: use the RDS endpoint DNS name directly. Simfra DNS resolves it to the container IP.
  • Port forwarding from the host:
curl -X POST http://localhost:4599/_simfra/port-forwards \
  -d '{"targetArn":"arn:aws:rds:us-east-1:000000000000:db:mydb","targetPort":5432}'

The response includes the local port:

{
  "localPort": 11800,
  "targetPort": 5432
}

psql -h localhost -p 11800 -U admin -d postgres

Aurora Clusters

Aurora clusters create one or more DB instances backed by the same engine:

aws --endpoint-url http://localhost:4599 rds create-db-cluster \
  --db-cluster-identifier my-aurora \
  --engine aurora-postgresql \
  --master-username admin \
  --master-user-password mypassword

aws --endpoint-url http://localhost:4599 rds create-db-instance \
  --db-instance-identifier my-aurora-instance-1 \
  --db-cluster-identifier my-aurora \
  --engine aurora-postgresql \
  --db-instance-class db.r6g.large

The cluster provides separate reader and writer endpoints. Both resolve to the appropriate container IPs via Simfra DNS.

RDS Data API

Aurora clusters with HTTP endpoints enabled support the RDS Data API for executing SQL over HTTP:

aws --endpoint-url http://localhost:4599 rds enable-http-endpoint \
  --resource-arn arn:aws:rds:us-east-1:000000000000:cluster:my-aurora

aws --endpoint-url http://localhost:4599 rds-data execute-statement \
  --resource-arn arn:aws:rds:us-east-1:000000000000:cluster:my-aurora \
  --secret-arn arn:aws:secretsmanager:us-east-1:000000000000:secret:my-secret \
  --sql "SELECT 1 AS result"

The Data API connects to the real database container behind the scenes.

State Machine

RDS instances follow the same state transitions as real AWS:

Operation States
Create creating -> available
Stop stopping -> stopped
Start starting -> available
Delete deleting -> (removed)
Modify modifying -> available
Reboot rebooting -> available

Snapshots

DB snapshots capture the instance state. With Docker enabled, snapshots record the database metadata. Creating an instance from a snapshot creates a new container with the same engine and configuration.

RDS Proxy

RDS Proxy creates connection pooling containers:

aws --endpoint-url http://localhost:4599 rds create-db-proxy \
  --db-proxy-name my-proxy \
  --engine-family POSTGRESQL \
  --auth SecretArn=arn:aws:secretsmanager:us-east-1:000000000000:secret:my-secret \
  --role-arn arn:aws:iam::000000000000:role/rds-proxy-role \
  --vpc-subnet-ids subnet-xxx

Proxy endpoints are published from SIMFRA_RDS_PROXY_PORT_RANGE (default 10500-10599).

Cross-Service Integration

  • Lambda and ECS containers can connect to RDS endpoints by DNS name within the same VPC.
  • Secrets Manager: managed master passwords are stored as Secrets Manager secrets and rotated.
  • CloudWatch: RDS emits metrics (DatabaseConnections, CPUUtilization, etc.) that can be queried and used in alarms.
  • EventBridge: state changes emit events (e.g., RDS DB Instance State Change).

Next Steps