FlociClone/docs/services/rds.md

RDS

Protocol: Query (XML) for management API + PostgreSQL / MySQL / SQL Server wire protocol for data plane Management Endpoint: POST http://localhost:4566/ Data Endpoint: localhost:<proxy-port> (TCP)

Floci manages real PostgreSQL, MySQL, MariaDB, and SQL Server Docker containers and proxies TCP connections to them, including IAM authentication support where the protocol supports it. SQL Server uses a transparent TCP relay for its native TDS protocol.

RDS Data API (rds-data) is documented separately because it uses REST JSON routes instead of the RDS Query protocol. See RDS Data API.

Supported Management Actions

Action	Description
CreateDBInstance	Start a new database instance
DescribeDBInstances	List instances and their connection info — the list form includes DocumentDB and Neptune instances and takes an engine filter
DeleteDBInstance	Stop and remove an instance
ModifyDBInstance	Update instance settings
RebootDBInstance	Restart a database instance
StopDBInstance	Stop a standalone instance temporarily: an optional DBSnapshotIdentifier first, then its container goes away while the record, endpoint and volume stay
StartDBInstance	Start a stopped instance on the volume it kept, same endpoint
StopDBCluster	Stop a cluster and its member instances
StartDBCluster	Start a stopped cluster and its members
RebootDBCluster	Restart a cluster's database and its members' proxies
CreateDBInstanceReadReplica	Create a read replica of a PostgreSQL instance, initialised from a copy of the source; see Read replicas
PromoteReadReplica	Detach a read replica into a standalone instance and turn automated backups on
SwitchoverReadReplica	Refused with InvalidDBInstanceState: AWS supports switchover only for Oracle and SQL Server replicas, neither of which is emulated
PromoteReadReplicaDBCluster	Refused with InvalidDBClusterStateFault: no cluster is created as a replica of an instance
DescribeOrderableDBInstanceOptions	List deterministic instance class options
DescribeEvents	-
CreateDBSubnetGroup	Create a DB subnet group; tags given here are readable through ListTagsForResource
DescribeDBSubnetGroups	List DB subnet groups
ModifyDBSubnetGroup	Update DB subnet group description and subnet list
DeleteDBSubnetGroup	Delete a DB subnet group
CreateDBCluster	Create an Aurora-compatible cluster
DescribeDBClusters	List clusters — the list form covers the RDS family, DocumentDB and Neptune clusters included, and takes an engine filter
DeleteDBCluster	Delete a cluster
ModifyDBCluster	Update cluster settings
CreateDBParameterGroup	Create a parameter group
DescribeDBParameterGroups	List parameter groups
DeleteDBParameterGroup	Delete a parameter group
ModifyDBParameterGroup	Update parameter group settings
CopyDBParameterGroup	Copy a parameter group (by name or ARN) with its family and parameter overrides into a new group
ResetDBParameterGroup	Reset named parameters, or all of them, to engine defaults
DescribeDBParameters	List parameters in a group
CreateDBClusterParameterGroup	Create an Aurora-compatible cluster parameter group
DescribeDBClusterParameterGroups	List cluster parameter groups
DeleteDBClusterParameterGroup	Delete a cluster parameter group
ModifyDBClusterParameterGroup	Update cluster parameter group settings
CopyDBClusterParameterGroup	Copy a cluster parameter group into a new group; a managed default.* group cannot be copied, as on AWS
ResetDBClusterParameterGroup	Reset named cluster parameters, or all of them, to engine defaults
DescribeDBClusterParameters	List parameters in a cluster group
CreateOptionGroup	Create an option group
CopyOptionGroup	Copy an option group with its engine, major version and options into a new group
DescribeOptionGroups	List option groups, including the implicit default: groups
ModifyOptionGroup	Add, update, or remove options in an option group
DeleteOptionGroup	Delete an option group
CreateDBSnapshot	Create a snapshot of a DB instance
DeleteDBSnapshot	Delete an available manual DB snapshot and its saved data
CopyDBSnapshot	Copy an available DB snapshot, optionally copying tags or overriding the option group and KMS key
ModifyDBSnapshot	Change the engine version or option group of an available manual DB snapshot
RestoreDBInstanceFromDBSnapshot	Create a new DB instance from a snapshot
DescribeDBSnapshots	List DB instance snapshots
DescribeDBSnapshotAttributes	Return a snapshot's restore attribute (accounts authorized to copy/restore it)
ModifyDBSnapshotAttribute	Add or remove accounts authorized to copy/restore a snapshot
DescribeDBProxies	List DB proxies
CreateDBProxy	Create a DB proxy
ModifyDBProxy	Update mutable DB proxy authentication, logging, timeout, TLS, role, and security-group settings
DeleteDBProxy	Delete a DB proxy
RegisterDBProxyTargets	Register a cluster or instance as a proxy target
DeregisterDBProxyTargets	Remove a cluster or instance from a proxy target group
DescribeDBProxyTargetGroups	List a proxy's target groups
ModifyDBProxyTargetGroup	Update target-group connection-pool configuration
DescribeDBProxyTargets	List a proxy target group's registered targets
DescribeDBClusterSnapshots	List cluster snapshots, filtered by DBClusterSnapshotIdentifier, DBClusterIdentifier and SnapshotType
CreateDBClusterSnapshot	Take a manual snapshot of an available cluster, with its data and Tags
DeleteDBClusterSnapshot	Delete an available cluster snapshot and its data; the response carries Status deleted
CopyDBClusterSnapshot	Copy an available cluster snapshot (by identifier or same-region ARN) to a new manual one with its data; CopyTags and Tags; the copy reports SourceDBClusterSnapshotArn
RestoreDBClusterFromSnapshot	Create a cluster from a cluster snapshot's settings and data; Engine must match the snapshot's
DescribeDBClusterSnapshotAttributes	Return the restore attribute of a cluster snapshot
ModifyDBClusterSnapshotAttribute	Add or remove restore values (account ids or all) on a cluster snapshot
DescribeGlobalClusters	List the account's global clusters with their primary and secondary members; see Global clusters
CreateGlobalCluster	Create an Aurora global database, empty or with an existing Aurora cluster as its primary
ModifyGlobalCluster	Rename a global cluster, set deletion protection, or upgrade its engine version (members follow)
DeleteGlobalCluster	Delete a global cluster once every member has been removed and deletion protection is off
RemoveFromGlobalCluster	Detach a member into a standalone cluster; the primary goes last
FailoverGlobalCluster	Promote a secondary to primary (failover with AllowDataLoss, or switchover)
SwitchoverGlobalCluster	Promote a secondary to primary and demote the current primary to a secondary
FailoverDBCluster	Move a DB cluster's writer role to a reader instance, the named one or the first
AddTagsToResource	Add tags to a DB resource
ListTagsForResource	List tags for a DB resource
RemoveTagsFromResource	Remove tags from a DB resource

CreateDBInstance stores StorageEncrypted, KmsKeyId, BackupRetentionPeriod, PreferredBackupWindow, PreferredMaintenanceWindow and CopyTagsToSnapshot, and DescribeDBInstances returns them; ModifyDBInstance changes the backup settings and the windows. The same checks as on AWS apply (KmsKeyId needs StorageEncrypted, windows are at least 30 minutes and may not overlap). KmsKeyId is accepted as a key ARN, key id, alias ARN or alias name, resolved against the KMS store in the request's region and returned as the key ARN; a key that does not exist or is not enabled is KMSKeyNotAccessibleFault. Where AWS picks a random window, Floci uses 04:00-06:00 and mon:00:00-mon:03:00 (or, when the window given on create overlaps the usual default, a 30-minute window starting where the given one ends); a window given on modify is checked against the instance's other window. Modifications apply immediately — PendingModifiedValues is not modeled.

!!! note "Stopping and starting"

`StopDBInstance` and `StopDBCluster` follow the user guide: the response reports `stopping`
(`StopDBCluster` for the cluster and its members), the stored status settles to `stopped`,
and `StartDBInstance` / `StartDBCluster` report `starting` and settle to `available`. While
stopped, the identifier, endpoint (same port), parameter and option groups and the Docker
volume all stay, so the data comes back on start; the container itself is removed and the
endpoint refuses connections. `StopDBInstance` refuses a cluster member (use `StopDBCluster`),
a read replica or an instance that has one, and anything not `available`, with
`InvalidDBInstanceState`; `ModifyDBInstance` on a stopped instance is refused the same way.
`DeleteDBInstance` works on a stopped instance. A stopped instance or cluster stays stopped
across an emulator restart. Not modeled: the automatic restart after seven days, and the
Multi-AZ SQL Server restriction.

!!! note "DB snapshot tagging and lifecycle"

`CreateDBSnapshot` accepts `Tags`, and `TagResource`/`UntagResource`/`ListTagsForResource`
work against a snapshot's ARN like they do for other tagged resource types.
`DescribeDBSnapshotAttributes`/`ModifyDBSnapshotAttribute` are modeled as plain in-memory
state (no real cross-account sharing). Available manual snapshots can be deleted, copied by
identifier or ARN, and modified. Copies retain the source data and can copy source tags or add
request tags. Snapshots are region-scoped like DB instances and clusters: `DBSnapshotArn` reflects
the request's signed region, and a snapshot is only visible to `Describe`/`Tag` calls signed
for that same region. Cluster snapshots follow the same lifecycle: `CreateDBClusterSnapshot`
dumps the cluster's database, `RestoreDBClusterFromSnapshot` loads it into a new cluster, and
`Copy`, `Delete` and the `restore` attribute behave as they do for instance snapshots, under
`arn:aws:rds:<region>:<account>:cluster-snapshot:<name>`. RDS reserved instances aren't
modeled (there's no reserved-instance API), so tagging doesn't apply to them.

Configuration

Variable	Default	Description
FLOCI_SERVICES_RDS_ENABLED	true	Enable or disable the service
FLOCI_SERVICES_RDS_MOCK	false	true = metadata only (no Docker container or auth proxy)
FLOCI_SERVICES_RDS_PROXY_BASE_PORT	7001	First host port in the RDS proxy range
FLOCI_SERVICES_RDS_PROXY_MAX_PORT	7099	Last host port in the RDS proxy range
FLOCI_SERVICES_RDS_ENDPOINT_HOST	(auto-detected)	Hostname advertised in RDS endpoints; when set in Docker, Floci advertises each proxy's published host port
FLOCI_SERVICES_RDS_DEFAULT_POSTGRES_IMAGE	postgres:16-alpine	Docker image for PostgreSQL instances
FLOCI_SERVICES_RDS_DEFAULT_MYSQL_IMAGE	mysql:8.0	Docker image for MySQL instances
FLOCI_SERVICES_RDS_DEFAULT_MARIADB_IMAGE	mariadb:11	Docker image for MariaDB instances
FLOCI_SERVICES_RDS_DEFAULT_SQL_SERVER_IMAGE	mcr.microsoft.com/mssql/server:2022-latest	Docker image for SQL Server instances
FLOCI_SERVICES_RDS_PROXY_HANDSHAKE_TIMEOUT_MILLIS	10000	Max time a client has to complete the startup/auth handshake before the proxy drops it
FLOCI_SERVICES_RDS_PROXY_BACKEND_CONNECT_TIMEOUT_MILLIS	5000	Max time the proxy waits for the backend TCP connect
FLOCI_SERVICES_RDS_PROXY_MAX_CONNECTIONS	100	Max concurrent connections per proxy before new ones are refused

Docker Compose

RDS requires the Docker socket and port range exposure. For private registry authentication and other Docker settings see Docker Configuration.

When Docker publishes RDS proxy ports dynamically, set FLOCI_SERVICES_RDS_ENDPOINT_HOST to the hostname used by clients. Floci inspects its own container through the Docker socket and returns the corresponding published port from DescribeDBInstances and DescribeDBClusters. Leave the setting unset to retain the auto-detected endpoint host and configured proxy port.

services:
  floci:
    image: floci/floci:latest
    ports:
      - "4566:4566"
      - "7001-7099:7001-7099"   # RDS proxy ports
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      FLOCI_SERVICES_DOCKER_NETWORK: my-project_default
      FLOCI_SERVICES_RDS_PROXY_BASE_PORT: "7001"

Without a reachable Docker daemon

A DB instance or cluster record is metadata. Its identifier, ARN, endpoint address and tags come from Floci's configuration, not from Docker. When no daemon is reachable, because Floci runs inside Docker with no socket mounted or the daemon on the host is stopped, CreateDBInstance and CreateDBCluster still succeed and the resource reaches available. DescribeDBInstances, ModifyDBInstance, the tagging APIs and DeleteDBInstance all work on that record, and Floci logs a warning naming the missing daemon.

Nothing listens behind the endpoint in that state. The backing container is retried by every operation that needs the live database, so it starts as soon as a daemon becomes reachable. Until then, RDS Data API calls fail with a modelled InternalServerErrorException that names the missing daemon. A daemon that is reachable but cannot start the container still fails CreateDBInstance outright, since that is a real error rather than a degraded mode.

Mock mode (CI / tests)

Set FLOCI_SERVICES_RDS_MOCK=true when you only need the management API shape: clusters and instances are registered as available immediately, with no Docker container or auth proxy behind them. Each resource still gets a unique endpoint port, but nothing listens on it.

# docker-compose.yml — CI / test environment
services:
  floci:
    image: floci/floci:latest
    environment:
      FLOCI_SERVICES_RDS_MOCK: "true"

!!! note "Switching modes over persisted state" With a persistent storage mode, changing FLOCI_SERVICES_RDS_MOCK between restarts is best-effort, as with the other mock-capable services: resources created in real mode and deleted under mock leave their containers and volumes behind, and resources created in mock mode are restored with fresh, empty containers when loaded in real mode.

!!! warning "DB proxy endpoint routing"

DB proxy control-plane resources and target registration are modeled, but Floci's current
single-host TCP relay cannot expose multiple same-engine DB proxies as distinct AWS-style bare
hostnames on the same engine-default port. The standard Docker Compose mapping also exposes
only the `7001-7099` instance/cluster proxy range, not `1433`, `3306`, or `5432`. Use mock mode
for DB proxy provisioning workflows until a dedicated endpoint-routing design is implemented.

!!! note "DB proxy control-plane settings"

Proxy and target-group settings are persisted and round-trip through the RDS Query API and
CloudFormation. Pool sizing, borrow timeout, idle timeout, TLS, init-query, and session-pinning
settings are currently control-plane metadata; the TCP relay does not yet implement those data-plane
behaviors. `DefaultAuthScheme=IAM_AUTH` is supported for control-plane workflows, but a real-mode
proxy using that scheme cannot register a target until backend IAM authentication is implemented.
Requests to `RegisterDBProxyTargets`, `DeregisterDBProxyTargets`, and
`DescribeDBProxyTargets` use the `default` target group when `TargetGroupName` is omitted,
matching the RDS API contract.
`CreateDBProxy`/`AWS::RDS::DBProxy` accept `EndpointNetworkType` (`IPV4`, `IPV6`, or `DUAL`) and
`TargetConnectionNetworkType` (`IPV4` or `IPV6`) and round-trip them like the other proxy
settings above; the TCP relay itself still only listens on IPv4, so a non-`IPV4` value is
accepted as control-plane metadata rather than making the relay dual-stack. A non-`IPV4` value
is rejected with `InvalidParameterValue` unless the proxy's VPC and every subnet in
`VpcSubnetIds` already carry an associated IPv6 CIDR block, matching AWS's own network
prerequisites for RDS Proxy.

Aurora Serverless v2 scaling

CreateDBCluster, ModifyDBCluster, and DescribeDBClusters support the AWS ServerlessV2ScalingConfiguration Query shape for aurora-mysql and aurora-postgresql clusters. Requests that apply this configuration to another engine fail with InvalidParameterCombination.

The minimum and maximum capacities use half-ACU increments; the maximum must be at least 1 ACU and no greater than 256 ACUs. AWS's actual maximum depends on the Aurora engine and platform version, while Floci currently applies the 256-ACU ceiling uniformly.

When MinCapacity is zero, SecondsUntilAutoPause accepts 300–86,400 seconds and defaults to 300. Changing the minimum to a nonzero value removes the auto-pause interval, matching the AWS response shape. AWS limits zero-capacity auto-pause to compatible Aurora versions; Floci does not currently enforce that version matrix. ModifyDBCluster accepts partial scaling updates and preserves omitted values. AWS::RDS::DBCluster creation also maps the equivalent CloudFormation property.

If a persisted cluster record does not contain its original AWS engine identifier, Floci rejects a new scaling configuration instead of assuming that the cluster is Aurora.

This is control-plane compatibility: Floci persists and returns the scaling configuration, but it does not resize or automatically pause the backing Docker container.

Examples

export AWS_ENDPOINT_URL=http://localhost:4566

# Create a PostgreSQL instance
aws rds create-db-instance \
  --db-instance-identifier mypostgres \
  --db-instance-class db.t3.micro \
  --engine postgres \
  --master-username admin \
  --master-user-password secret123 \
  --allocated-storage 20 \
  --endpoint-url $AWS_ENDPOINT_URL

# Get connection details
aws rds describe-db-instances \
  --db-instance-identifier mypostgres \
  --query 'DBInstances[0].Endpoint' \
  --endpoint-url $AWS_ENDPOINT_URL

# Connect with psql (use the port returned above)
psql -h localhost -p 7001 -U admin

# Create a MySQL instance
aws rds create-db-instance \
  --db-instance-identifier mymysql \
  --db-instance-class db.t3.micro \
  --engine mysql \
  --master-username root \
  --master-user-password secret123 \
  --allocated-storage 20 \
  --endpoint-url $AWS_ENDPOINT_URL

# Connect with mysql client
mysql -h 127.0.0.1 -P 7002 -u root -psecret123

Supported Engines

Engine	Default image
postgres	postgres:16-alpine
mysql	mysql:8.0
mariadb	mariadb:11

Override the image per-instance with the --engine-version flag or globally via environment variables. Aurora MySQL versions such as 8.0.mysql_aurora.3.08.0 use the MySQL version in front, so that example runs mysql:8.0.

Option Groups

Option groups are metadata: Floci stores the options you add, returns them on the wire, and attaches a group to a DB instance, but it does not install the underlying engine feature in the container.

As on AWS, every engine has an implicit default:<engine>-<major version> group that DescribeOptionGroups returns even when you have created none. Floci ships the defaults for the engines it can run (postgres 13–18, mysql 8.0/8.4, mariadb 10.11/11.2/11.4), so an instance created without --option-group-name reports the matching default. Default groups can't be modified, deleted, or tagged.

CreateOptionGroup accepts any EngineName AWS accepts — including oracle-*, sqlserver-*, and db2-* — so a Terraform aws_db_option_group for an engine Floci cannot start still applies. Attaching one to a DB instance requires the group's engine and major engine version to match the instance, as on AWS: a mysql 8.0 group can't be attached to a mysql 8.4 instance. A mismatch fails with InvalidParameterCombination.

aws rds create-option-group \
  --option-group-name my-og \
  --engine-name mysql \
  --major-engine-version 8.0 \
  --option-group-description "MySQL options" \
  --endpoint-url $AWS_ENDPOINT_URL

aws rds modify-option-group \
  --option-group-name my-og \
  --options OptionName=MEMCACHED,Port=11211 \
  --apply-immediately \
  --endpoint-url $AWS_ENDPOINT_URL

aws rds describe-option-groups \
  --engine-name mysql \
  --endpoint-url $AWS_ENDPOINT_URL

Deleting a group that is still attached to a DB instance fails with InvalidOptionGroupStateFault, matching AWS.

Known gaps, all deliberate:

Behavior	Status
DescribeOptionGroupOptions	Not implemented: the per-engine option catalog is not modeled
OptionGroupQuotaExceededFault (AWS caps an account at 20 groups)	Not enforced — capping a local emulator would only get in a test's way
OptionSetting metadata (DataType, ApplyType, AllowedValues, DefaultValue, Description)	Omitted — it would require the per-engine option catalog DescribeOptionGroupOptions serves
MaxRecords / Marker pagination	Every group is returned in one page, as with every other RDS list action

Read replicas

CreateDBInstanceReadReplica creates a standalone instance with its own container and endpoint. As on AWS it inherits the source's engine, version, credentials and database name and, unless the request overrides them, the instance class, storage and minor version upgrade setting. A replica in the source's region also inherits the source's parameter group, option group, subnet group and security groups; a replica in another region (source given by ARN, --region set to the destination) gets that region's defaults. IAM authentication and CopyTagsToSnapshot are off unless requested. The replica starts with BackupRetentionPeriod 0. Both ends report the link the way DescribeDBInstances does: the replica carries ReadReplicaSourceDBInstanceIdentifier and a StatusInfos entry of type read replication, the source lists it under ReadReplicaDBInstanceIdentifiers; within a region the link is the identifier, across regions it is the ARN. A DBSubnetGroupName with a source given by plain identifier is refused with DBSubnetGroupNotAllowedFault, as on AWS.

The replica's database is initialised from a pg_dumpall of the source taken when the replica is created, the same mechanism RestoreDBInstanceFromDBSnapshot uses, so it holds the source's data as of that moment. Writes made to the source afterwards are not streamed to the replica. Because the copy is dump based, only PostgreSQL sources are accepted; MySQL and MariaDB sources are refused with InvalidDBInstanceState, as CreateDBSnapshot refuses them. A source with automated backups off (BackupRetentionPeriod 0) is refused with the same error AWS uses.

PromoteReadReplica clears the link on both ends, sets the requested BackupRetentionPeriod (one day when omitted) and PreferredBackupWindow, and reboots the instance as AWS does, so open connections drop while the container, endpoint and data stay. Deleting a source promotes its same-region replicas; a cross-region replica keeps its link with the replication status terminated until it is promoted or deleted, which is what AWS does for PostgreSQL. Deleting a replica drops it from its source's list.

Global clusters

CreateGlobalCluster creates an Aurora global database (aurora-mysql or aurora-postgresql), either empty or with an existing Aurora cluster as its primary through SourceDBClusterIdentifier (an ARN, or an identifier in the request's region), in which case engine, version, database name and encryption come from that cluster and may not be given, as on AWS. The record is account wide: its ARN has no region and DescribeGlobalClusters lists it from any region.

CreateDBCluster with GlobalClusterIdentifier joins a cluster: the first one becomes the primary, every later one a secondary. A secondary must be in a region that holds neither the primary nor another secondary, may not carry its own master credentials or database name (it takes the primary's), and its database is initialised from a pg_dumpall of the primary the way a read replica is, so only aurora-postgresql primaries accept secondaries; writes after that are not streamed. DescribeGlobalClusters reports every member with IsWriter and, on the primary, the secondaries under Readers; DescribeDBClusters reports GlobalClusterIdentifier on members.

SwitchoverGlobalCluster, and FailoverGlobalCluster with or without AllowDataLoss, promote the named secondary and demote the current primary to a secondary, the topology AWS keeps for a switchover and restores after a managed failover once the old primary region is healthy again. The response is the completed state; AWS answers with a pending FailoverState because the operation runs asynchronously there. RemoveFromGlobalCluster detaches a member into a standalone cluster; the primary can only be removed once every secondary is gone, and deleting the primary cluster while secondaries remain is refused the same way. DeleteGlobalCluster needs an empty global cluster with deletion protection off.

FailoverDBCluster moves the writer role inside a DB cluster to the named reader instance, or to the first reader when none is named; a cluster with no reader has nothing to fail over to and is refused. DescribeDBClusters reports the role as IsClusterWriter, and deleting the writer promotes a remaining member, as Aurora does on its own.

Persistence

Each DB instance and cluster gets its own named Docker volume (floci-rds-{volumeId}) created automatically. No configuration is required.

Scenario	Volume behavior
memory mode (default)	Volume is removed automatically when the instance is deleted
persistent / hybrid / wal	Volume is retained after delete — data survives for manual recovery

# CI — ephemeral, volumes cleaned up on each delete
FLOCI_STORAGE_MODE=memory

# Local dev — retain DB data across Floci restarts
FLOCI_STORAGE_MODE=hybrid

# Local dev — also remove volumes immediately on delete
FLOCI_STORAGE_MODE=hybrid
FLOCI_STORAGE_PRUNE_VOLUMES_ON_DELETE=true

To use a host bind mount instead of a named volume (advanced), set an absolute path:

FLOCI_STORAGE_HOST_PERSISTENT_PATH=/absolute/host/path/data

!!! note "Docker Desktop on macOS" Named volumes work correctly on Docker Desktop for macOS. Bind mounts to paths inside the Floci container are not supported — use named volumes (the default).

Authentication

The RDS auth proxy validates the master username and password at the proxy layer. All other database users are passed through directly to the backend engine — create them with standard SQL (CREATE USER) and connect as normal.

IAM database authentication is also supported. Set --enable-iam-database-authentication at instance creation time and use aws rds generate-db-auth-token to obtain a token.

On PostgreSQL, the token names a database role (DBUser) and the session runs as that role: current_user and session_user both report it, objects it creates are owned by it, and a token naming a role the database does not have is refused with FATAL: role "..." does not exist. Create the role first with CREATE ROLE <name> WITH LOGIN as the master user, and grant it whatever the application needs.

Underneath, the proxy reaches the container as the master user and hands the session over to the token's role, so an IAM session that talks its way back to the master role, via RESET SESSION AUTHORIZATION and its variants, is terminated with FATAL: permission denied to set session authorization rather than being allowed to regain superuser. SET ROLE is untouched: PostgreSQL still permission-checks it against the token's role, exactly as on RDS. One difference from RDS: the proxy learns of the switch from PostgreSQL's own report, so when several statements are batched into a single query after the switch, their results are returned before the session is closed.

On MySQL, AWSAuthenticationPlugin is proprietary to RDS and ships in no public MySQL build, so CREATE USER ... IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS' would fail against the container with ERROR 1524 (HY000): Plugin 'AWSAuthenticationPlugin' is not loaded. The proxy rewrites that clause to IDENTIFIED WITH mysql_native_password AS '*000...0', an authentication string no password hashes to. The account is therefore created, can be granted to and can be dropped, but holds no password of its own, which is what an IAM DB user is: an account whose credentials come from IAM rather than from MySQL. This is the MySQL counterpart of the empty rds_iam role Floci pre-creates for PostgreSQL.

Two limits follow from that. SHOW CREATE USER reports the substituted plugin rather than AWSAuthenticationPlugin, so a Terraform or Pulumi refresh sees drift on auth_plugin. And connecting with a token is not yet emulated for MySQL: unlike PostgreSQL, which receives the password in cleartext, MySQL sends a scramble, so the proxy would have to drive the mysql_clear_password auth switch that real RDS triggers before it could see a token to validate.

TLS / SSL

The RDS auth proxy terminates TLS itself (the backend container stays plaintext) using a self-signed CA whose Subject Alternative Names cover every advertised host Floci has handed out for a DB instance, cluster, or RDS Proxy — the Docker bridge IP, host.docker.internal, localhost, or whatever rds.endpointHost resolves to. The CA is persisted at {storage.persistent-path}/tls/rds-ca.crt and grows its SAN list as new hosts appear, so the same root survives restarts and works for every local database, not just the one that generated it.

Floci logs the certificate path (and the PGSSLROOTCERT hint) the first time it generates or loads it:

RDS proxy TLS: CA cert at ./data/tls/rds-ca.crt
RDS proxy TLS: for sslmode=verify-full set PGSSLROOTCERT=./data/tls/rds-ca.crt

Because the SAN matches the address you actually connect to, verify-full (the same level Aurora enforces in AWS) works locally too — no need to fall back to sslmode=disable just to exercise the same connection-string settings you use in production:

# PostgreSQL
PGSSLROOTCERT=./data/tls/rds-ca.crt psql "host=localhost port=7001 user=admin sslmode=verify-full"

# MySQL / MariaDB
mysql -h 127.0.0.1 -P 7002 -u root -psecret123 \
  --ssl-mode=VERIFY_IDENTITY --ssl-ca=./data/tls/rds-ca.crt