Docs / RDS Docker Databases

RDS (PostgreSQL, MySQL): API reference

Run real PostgreSQL, MySQL, and MariaDB databases as Docker containers. Create them with the RDS API, connect with standard database clients.

Want a runnable walkthrough? See RDS: demo & walkthrough.

Enable RDS Docker Backend

RDS_DOCKER_BACKEND=1 localemu start

Setting RDS_DOCKER_BACKEND=1 tells LocalEmu to start real database containers instead of using mocked responses.

Supported Engines

Engine	Default Image	Supported Versions
`postgres`	`postgres:16`	13, 14, 15, 16, 17
`mysql`	`mysql:8.0`	5.7, 8.0, 8.4
`mariadb`	`mariadb:11.4`	10.6, 10.11, 11.4
`aurora-mysql`	`mysql:8.0`	8.0 (MySQL-compatible)
`aurora-postgresql`	`postgres:16`	16 (PostgreSQL-compatible)

Create a PostgreSQL Instance

$ awsemu rds create-db-instance \
    --db-instance-identifier my-postgres \
    --engine postgres \
    --engine-version 16 \
    --master-username admin \
    --master-user-password secretpass \
    --db-instance-class db.t3.micro

DBInstanceIdentifier: my-postgres
Engine: postgres
EngineVersion: 16
DBInstanceStatus: available

Get the connection endpoint

$ awsemu rds describe-db-instances \
    --db-instance-identifier my-postgres \
    --query 'DBInstances[0].Endpoint'

Address: localhost
Port: 49267  # Dynamically assigned at create time

Connect with psql

$ PORT=$(awsemu rds describe-db-instances --db-instance-identifier my-postgres \
    --query 'DBInstances[0].Endpoint.Port' --output text)
$ psql -h localhost -p $PORT -U admin -d postgres
Password: secretpass

postgres=> CREATE TABLE users (id serial PRIMARY KEY, name text);
CREATE TABLE
postgres=> INSERT INTO users (name) VALUES ('Alice'), ('Bob');
INSERT 0 2

Any standard client works: psql, pgAdmin, psycopg2, SQLAlchemy, Prisma, or any PostgreSQL driver.

Create a MySQL Instance

$ awsemu rds create-db-instance \
    --db-instance-identifier my-mysql \
    --engine mysql \
    --engine-version 8.0 \
    --master-username admin \
    --master-user-password secretpass \
    --db-instance-class db.t3.micro

Engine: mysql
DBInstanceStatus: available

Connect with mysql client

$ PORT=$(awsemu rds describe-db-instances --db-instance-identifier my-mysql \
    --query 'DBInstances[0].Endpoint.Port' --output text)
$ mysql -h 127.0.0.1 -P $PORT -u admin -psecretpass

Any MySQL client works: mysql CLI, MySQL Workbench, pymysql, mysql-connector, Sequelize, or any MySQL driver.

Container Naming and Labels

Each RDS instance runs in a Docker container named localemu-rds-<db-instance-identifier>. Containers are tagged with labels for easy filtering.

$ docker ps --filter "label=localemu.service=rds"

CONTAINER ID   IMAGE          STATUS       NAMES
a1b2c3d4e5f6   postgres:16    Up 3 min     localemu-rds-my-postgres
b2c3d4e5f6a7   mysql:8.0      Up 1 min     localemu-rds-my-mysql

Label	Description
`localemu.service`	Always set to `rds`
`localemu.db-instance-id`	The DB instance identifier
`localemu.engine`	The database engine (postgres, mysql, mariadb)

Master password

Always pass --master-user-password on create-db-instance. The value goes straight into the engine container's POSTGRES_PASSWORD / MYSQL_ROOT_PASSWORD / MARIADB_ROOT_PASSWORD env var at startup, so it is the actual password your client will need to connect.

If you omit the flag, LocalEmu does what real RDS does and generates a 30-character cryptographically random password (_generate_random_password() in services/rds/provider.py, same character set AWS uses for auto-generated passwords). The AWS RDS API does not return master passwords on read paths, and neither does LocalEmu, so an auto-generated password leaves you with a database you cannot connect to. Pass --master-user-password explicitly, or call modify-db-instance --master-user-password <new> afterwards to set a password you actually know.

Cleanup

Containers are removed automatically when you delete a DB instance or stop LocalEmu. No orphaned containers.

$ awsemu rds delete-db-instance \
    --db-instance-identifier my-postgres \
    --skip-final-snapshot

DBInstanceStatus: deleting

$ docker ps --filter "name=localemu-rds-my-postgres"
CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES
(empty - container removed)

← EC2 Docker Instances OpenSearch →