Skip to content

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)

Recoverable backend startup failures

If a persisted database's container or authentication relay cannot start when Floci restarts, Floci retains the database record, data volume, and reserved endpoint port and retries when its backend is next needed. A failed restore does not release or renumber a reserved endpoint; a retry or the next boot uses the same port. This recoverable emulator condition uses available, the same metadata-only status as a restart without a reachable Docker daemon, not AWS's terminal failed state. It does not guarantee that a database connection is ready while Docker is unavailable. Port allocation failures still report failed because no endpoint could be allocated.

A successful lazy retry updates legacy failed records to available only after the container and relay are ready. Older records whose endpoint was cleared receive a new relay endpoint on retry. A failed retry leaves their status unchanged and cleans up the attempted backend and any newly allocated relay port.

Instance and cluster start operations, and cluster reboot, reconstruct a missing relay endpoint through the same retry path. Retrying a cluster directly, or resolving its ARN for a Data API request, also restores its missing member relays without restarting a healthy cluster backend or rebinding members that already recovered. Data API cluster-ARN resolution checks for missing members even when the cluster backend is already running, so a member relay that fails once is retried on the next request. Stopped members remain stopped until a control-plane start operation. When the cluster and all active members have backends, Data API resolution skips the synchronized recovery path, so healthy queries do not wait for unrelated container starts or image pulls. Lazy cluster recovery tries every active member even if one relay fails; a failed member does not prevent Data API access through a recovered cluster backend, and repeated member failures are logged at debug level. Start and reboot report member relay errors after trying all members and mark those members failed until a successful retry.

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.

MySQL and MariaDB master-grant script uploads, and snapshot dump script and restore archive uploads, retry transient Docker connection failures up to six attempts with exponential backoff starting at 500 ms. Every attempt sends a fresh archive. Containers start, or snapshot restore commands run, only after the upload succeeds. A permanent Docker error or exhausted retries follows the existing failure path. The PostgreSQL restore SQL readiness retry policy is unchanged.

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

RDS endpoints return the us-east-1 hosted zone ID Z2R2ITUGPM61AM in all regions until regional values are captured. Floci Route 53 resolves aliases by DNS name and does not check this ID. The us-east-1 value is shown in the AWS CLI RDS example.

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, MySQL or MariaDB 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
DescribeDBEngineVersions List the engine catalogue's versions with their parameter group family, default flag and upgrade targets
DescribeEngineDefaultParameters Return a known family's default parameters (an empty list, as Floci's default groups hold none)
DescribeEngineDefaultClusterParameters Return a known family's default cluster parameters (an empty list, as for instances)
DescribeValidDBInstanceModifications Return the storage an instance can move to: its type and the sizes a modify stores as asked
DescribeOrderableDBInstanceOptions List the orderable engine, version and instance class combinations from the engine catalogue; see Engine catalogue
DescribeEvents -
DescribeCertificates List the Region's RDS certificate authorities and the one new instances get; see Certificate authorities
ModifyCertificates Set or remove the account's default certificate authority for new instances
CreateEventSubscription Create an event notification subscription (stored, nothing is published)
DescribeEventSubscriptions List subscriptions, or the one the request names
ModifyEventSubscription Update the members the request names
DeleteEventSubscription Delete a subscription
CreateDBClusterEndpoint Create an Aurora custom endpoint (READER or ANY) with a static or exclusion member list; see Cluster endpoints
DescribeDBClusterEndpoints List a cluster's built-in writer and reader endpoints and its custom endpoints, with the four documented filters
ModifyDBClusterEndpoint Change a custom endpoint's type or member list
DeleteDBClusterEndpoint Delete a custom endpoint
EnableHttpEndpoint Turn on an Aurora cluster's Data API endpoint by ARN; see Data API endpoint
DisableHttpEndpoint Turn off a cluster's Data API endpoint by ARN
DescribeDBLogFiles List an instance's log files, read from its database container; see Log files
DownloadDBLogFilePortion Read a block of a log file, from the start or the most recent lines
AddRoleToDBCluster Associate an IAM role with a cluster, optionally for a feature; see IAM role associations
RemoveRoleFromDBCluster Remove a role from a cluster
AddRoleToDBInstance Associate an IAM role with an instance for a feature
RemoveRoleFromDBInstance Remove a role from an instance
AddSourceIdentifierToSubscription Add a source id to a subscription
RemoveSourceIdentifierFromSubscription Remove a source id from a subscription
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
RestoreDBInstanceToPointInTime Create a new DB instance from a source instance at a time in its restorable window; see Point in time restore
DescribeDBInstanceAutomatedBackups List the Region's instance automated backups: active for live instances, retained and replicating ones; see Automated backups
DeleteDBInstanceAutomatedBackup Delete a retained instance automated backup by DbiResourceId or DBInstanceAutomatedBackupsArn
StartDBInstanceAutomatedBackupsReplication Replicate a source instance's automated backups from its Region to this one (metadata only)
StopDBInstanceAutomatedBackupsReplication Stop replicating to this Region; the replica is kept as retained
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 and its endpoints
CreateDBProxyEndpoint Add a read/write or read-only endpoint to a DB proxy; see the proxy note below
DescribeDBProxyEndpoints List proxy endpoints, each proxy's default endpoint first, filtered by DBProxyName and DBProxyEndpointName
ModifyDBProxyEndpoint Rename a proxy endpoint or replace its security groups
DeleteDBProxyEndpoint Delete a proxy endpoint
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
RestoreDBClusterToPointInTime Create a cluster from a source cluster at a time in its restorable window; see Point in time restore
DescribeDBClusterAutomatedBackups List the Region's retained cluster automated backups; see Automated backups
DeleteDBClusterAutomatedBackup Delete a retained cluster automated backup by DbClusterResourceId
DescribeDBClusterSnapshotAttributes Return the restore attribute of a cluster snapshot
ModifyDBClusterSnapshotAttribute Add or remove restore values (account ids or all) on a cluster snapshot
StartExportTask Export a DB snapshot or DB cluster snapshot to S3 as Parquet; see Exporting snapshots to Amazon S3
DescribeExportTasks List export tasks, by ExportTaskIdentifier, SourceArn, SourceType and the export-task-identifier, s3-bucket, source-arn and status filters
CancelExportTask Cancel a running export task; what it already wrote stays in the bucket
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
CreateBlueGreenDeployment Stage a green copy of a DB instance with a new engine version, parameter group, class or storage; see Blue/Green deployments
DescribeBlueGreenDeployments List blue/green deployments, by identifier and the blue-green-deployment-identifier, blue-green-deployment-name, source and target filters
SwitchoverBlueGreenDeployment Make the green instance production: it takes the blue name, ARN, endpoint and tags, and blue becomes <name>-old1
DeleteBlueGreenDeployment Delete a deployment, with DeleteTarget also deleting the green instance before switchover
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.

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.

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. AWS doesn't document a ModifyDBSnapshot that names neither EngineVersion nor OptionGroupName; Floci returns the snapshot unchanged, since the model requires only the identifier and declares no fault for a request with nothing to change. 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.

DB snapshot engines

CreateDBSnapshot takes a logical copy of a PostgreSQL, MySQL or MariaDB instance, and RestoreDBInstanceFromDBSnapshot loads it into the new instance. PostgreSQL uses pg_dumpall. MySQL and MariaDB use mysqldump (mariadb-dump) of every user schema, with routines, triggers and events, run as the master user, followed by every account other than root and the image's system accounts, recreated from SHOW CREATE USER and SHOW GRANTS so they keep their passwords. Roles are copied too, and created before any grant names them. The mysql system schema itself is not copied. The restore waits until the new server accepts the master user over TCP before loading the copy. SQL Server instances are refused with InvalidDBInstanceState. The dump runs in one transaction, so InnoDB tables are copied as of one moment; as with mysqldump --single-transaction elsewhere, a MyISAM or other non-transactional table written to during the snapshot may not be.

Cluster parameter groups

DescribeDBClusterParameterGroups includes DBClusterParameterGroupArn for managed default.* groups as well as customer-created groups, in both named and list responses. Managed default ARNs use the request's account, region, and partition with the cluster-pg:<group-name> resource form.

Boolean parameters

The following parameters accept true or false (case-insensitive). Other values, including empty strings, return InvalidParameterValue before changing resources.

Actions Parameters When omitted
CreateDBProxy RequireTLS, DebugLogging Defaults to false
ModifyDBProxy RequireTLS, DebugLogging Preserves the current value
ResetDBParameterGroup, ResetDBClusterParameterGroup ResetAllParameters Defaults to false; named parameter resets keep their existing behavior
CopyDBClusterSnapshot CopyTags Defaults to false; explicit request tags still apply
CreateEventSubscription Enabled Defaults to true
ModifyEventSubscription Enabled Preserves the current value
RestoreDBInstanceFromDBSnapshot MultiAZ, EnableIAMDatabaseAuthentication Defaults to false, regardless of the snapshot setting
RestoreDBClusterFromSnapshot, RestoreDBClusterToPointInTime EnableIAMDatabaseAuthentication Defaults to false, regardless of the source setting

Malformed reset flags leave saved parameter overrides unchanged. Malformed event-subscription flags leave the subscription and its topic, source type and event categories unchanged. Malformed restore flags are rejected before starting an instance or cluster restore.

Native EventBridge lifecycle notifications

Completed StopDBInstance, StartDBInstance, StopDBCluster and StartDBCluster operations publish aws.rds notifications on the resource account and Region's default EventBridge bus. Cluster operations also notify their member instances. Instance events use RDS DB Instance Event and IDs RDS-EVENT-0087 (stopped) and RDS-EVENT-0088 (started); cluster events use RDS DB Cluster Event and RDS-EVENT-0150 / 0151. The resource ARN appears in both resources and detail.SourceArn, alongside SourceType (DB_INSTANCE for instances, CLUSTER for clusters), SourceIdentifier, Date, Message, EventID and EventCategories: ["notification"], following the AWS event examples. The Aurora cluster example documents the cluster-specific source type.

Events are emitted after the backend and proxies finish the operation. Rejected or failed operations do not emit success notifications. Delivery is best effort, with no replay after a restart; other RDS lifecycle events are not yet emitted. Metadata-only mock mode emits the same notifications. EventBridge rules can route these events independently of the SNS subscription actions below.

Event notification subscriptions

The four subscription actions manage the resource itself. Nothing is published to the topic. A subscription is stored and reported back so a client can manage it. No RDS event reaches SNS through it, so an SNS subscriber sees nothing.

SourceIds is set at create and changed only through AddSourceIdentifierToSubscription and RemoveSourceIdentifierFromSubscription, since ModifyEventSubscription carries no SourceIds member. Adding an id twice is a no-op, because the model declares no fault that fits a duplicate.

SnsTopicArn is required and is not resolved against the SNS service. SourceType is checked against the model's valid values, and a request naming SourceIds must also name the SourceType they belong to, as the model requires. An omitted Enabled activates the subscription.

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_ADVERTISE_REQUESTED_PORT false true = Describe* reports the requested Port instead of the proxy port; connect via the proxy port
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_IAM_TOKEN_ENDPOINT_BINDING true Refuse a PostgreSQL IAM auth token generated for another hostname, port or region than the endpoint publishes, as RDS does; set false to accept such tokens. MySQL and MariaDB always refuse them
FLOCI_SERVICES_RDS_DEFAULT_POSTGRES_IMAGE postgres:16-alpine Docker image for PostgreSQL instances
FLOCI_SERVICES_RDS_EXPORT_STAGING_BUCKET floci-rds-export-staging S3 bucket where snapshot exports stage rows and Parquet; see Exporting snapshots to Amazon S3
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
FLOCI_SERVICES_RDS_AURORA_AUTO_PAUSE_ENABLED true Pause an Aurora Serverless v2 cluster whose MinCapacity is 0 after SecondsUntilAutoPause without connections; see Automatic pause and resume
FLOCI_SERVICES_RDS_AURORA_RESUME_DELAY_MILLIS 0 How long the first connection to a paused cluster is held while it resumes; Aurora takes about 15000

Docker Compose

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

CreateDBInstance, CreateDBCluster, RestoreDBInstanceFromDBSnapshot, RestoreDBClusterFromSnapshot and the two point in time restores honor a requested Port only within the configured RDS proxy range. A port outside that range causes Floci to assign the next free port and return it in the endpoint. A port inside the range that is already in use is rejected. This differs from AWS because Floci's local proxy must use a published host port; for example, requesting 5432 with the default 7001-7099 range returns a port in that range. Ports outside AWS's valid 1150-65535 interval are rejected.

Set FLOCI_SERVICES_RDS_ADVERTISE_REQUESTED_PORT=true to make Describe* report the requested Port instead (for example so Terraform's port does not show a diff). The proxy still listens in the proxy range, so connect to that port; a restore without Port reports the proxy port. With the flag on, IAM authentication tokens bind to the advertised port, while the managed master-user secret carries the connectable (proxy) port. A cluster member created without its own Port reports its cluster's requested port, as AWS does.

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"

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.

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.

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. SessionPinningFilters is accepted and stored on every engine family; AWS documents it as effective only for the MySQL engine family. 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. Proxy endpoints report the proxy's own host, so a client connects through one as through the proxy, and an IAM token signed for that host verifies there. The host is read from the proxy for each response, so when a restore gives the proxy a new host every endpoint reports it. TargetRole is recorded: Floci proxies have one target, so a READ_ONLY endpoint reaches the same target as the proxy rather than an Aurora reader. Each proxy's default endpoint (default, IsDefault true, READ_WRITE) is built from the proxy, has no ARN, and cannot be modified or deleted (InvalidDBProxyEndpointStateFault). Endpoint names are unique per account and Region, a proxy holds at most 20 endpoints (DBProxyEndpointQuotaExceededFault), and an endpoint with no VpcSecurityGroupIds gets its VPC's default security group.

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.

Floci persists and returns the scaling configuration but does not resize the backing Docker container: capacity between MinCapacity and MaxCapacity is not modeled. A MinCapacity of 0 does take effect, as described next.

Automatic pause and resume

A cluster whose MinCapacity is 0 pauses the way Aurora Serverless v2 does. Once nothing has used it for SecondsUntilAutoPause, Floci freezes its database container with docker pause, which keeps its data and its endpoint. The next connection resumes it: the client is held, not refused, until the database runs again, and is then served as usual. As on AWS, a connection attempt with wrong credentials also resumes the cluster.

  • What keeps a cluster awake. Every open connection through the cluster endpoint, the reader endpoint, an instance endpoint or an RDS Proxy, every RDS Data API call and every open Data API transaction. The idle clock starts when the last of them ends.
  • Which clusters pause. Aurora PostgreSQL and Aurora MySQL clusters with at least one instance, all of them db.serverless and available. As on AWS, a cluster with a provisioned instance, a cluster in a global database and a cluster registered with an RDS Proxy stay running. Floci runs a cluster's instances in one container, so they pause and resume together, like Aurora's writer and its tier 0 and 1 readers; a reader in tiers 2 to 15 does not pause on its own.
  • What you can observe. The cluster Status and each DBInstanceStatus stay available. DescribeEvents reports RDS-EVENT-0370 to 0374 for each instance, for example "Successfully paused the DB instance.". While the cluster is paused, ServerlessDatabaseCapacity reports 0 and ACUUtilization and CPUUtilization report 0 percent in the AWS/RDS namespace once a minute, by DBClusterIdentifier and by DBInstanceIdentifier. Floci publishes none of them while the cluster runs.
  • Resume delay. Aurora takes about 15 seconds to resume. Floci resumes at once unless FLOCI_SERVICES_RDS_AURORA_RESUME_DELAY_MILLIS is set; 15000 exercises client connect timeouts, retries and connection-pool validation against a realistic cold start.
  • Configuration changes. A ModifyDBCluster that raises MinCapacity above 0 or changes SecondsUntilAutoPause resumes a paused cluster and restarts its idle clock.
  • Commands Floci runs in the container. CreateDBClusterSnapshot and a master password change run inside the database container, so they resume a paused cluster first. Aurora takes snapshots from storage without resuming it.
  • Stopping, rebooting or deleting a cluster, restarting Floci and resetting its state never leave a container frozen. A cluster that was paused when Floci stopped comes back running.
  • FLOCI_SERVICES_RDS_AURORA_AUTO_PAUSE_ENABLED=false keeps every cluster running.

Not emulated: Data API requests to a paused cluster wait for the resume, as the Aurora user guide describes, and never fail with DatabaseResumingException; logical or binlog replication does not keep a cluster awake; and parameter group changes do not resume one.

VPC security groups

CreateDBInstance and ModifyDBInstance check each id in VpcSecurityGroupIds against EC2 before anything is stored or a container starts, and refuse the request the way RDS does:

  • An id that names no security group of the account and Region fails with InvalidParameterValue (Invalid security group , groupId= sg-..., groupName=.).
  • A group outside the VPC of the instance's DB subnet group fails with InvalidParameterCombination (The DB instance and EC2 security group are in different VPCs. ...).

A modify that also names a new DBSubnetGroupName checks the groups against that subnet group's VPC. Snapshot and point-in-time restores, read replicas, the green instance of a Blue/Green deployment and a CloudFormation update of VPCSecurityGroups are checked the same way. A request that names no groups is not checked.

A standalone instance whose request names no groups gets the default security group of its VPC, as RDS documents for CreateDBInstance and CreateDBInstanceReadReplica. A same-Region read replica otherwise takes its source's groups, but only in the source's VPC: in another VPC it gets that VPC's default group. A modify that moves an instance to another VPC without naming groups puts it on the new VPC's default group, since the old VPC's groups cannot go with it. A cluster member's groups are its cluster's, which Floci does not keep, so it keeps none. DescribeDBInstances reports the VPC's default group for an instance that keeps none, such as a cluster member or an instance stored before these defaults, and sg-00000000 only when its VPC is unknown. A CloudFormation update checks its groups against the VPC it leaves the instance in before it changes anything, and a rollback leaves the groups of an instance the update moved to another VPC, which it does not move back.

Modifying a DB instance

ModifyDBInstance applies DBInstanceClass and AllocatedStorage, and DescribeDBInstances reports the new values. Members the request leaves out keep their current value, so a partial modify does not reset anything.

AllocatedStorage follows the AWS rules for the member:

  • A size smaller than the current one fails with InvalidParameterCombination. RDS storage never shrinks.
  • On PostgreSQL, MySQL and MariaDB, an increase of less than 10% is rounded up to 10% greater rather than refused, which is what AWS does. SQL Server takes the size it is given.
  • The same size is not a change and is left alone.

Standalone container-backed instances support minor EngineVersion upgrades when the default image follows the requested version. Floci stops the proxy and database container, starts the new engine image on the same storage volume, and rebinds the existing endpoint. It reports available only after both the new backend and proxy have started. A failed restart reports failed and retains the storage volume.

Major upgrades and downgrades fail with InvalidParameterCombination before any settings change. PostgreSQL 10 and later use the leading component as the major version; older PostgreSQL releases, MySQL, and MariaDB use the first two components. Existing databases need a migration for a major upgrade, which Floci does not perform. AllowMajorVersionUpgrade does not bypass this limitation. Custom image overrides and SQL Server do not map EngineVersion to a new image, so their version changes are also refused. Cluster members must use cluster-level engine management. Repeating the current version is allowed alongside other changes without restarting the database.

A standalone instance created while Docker is unavailable may change its version before its first backend startup when its image follows the requested version. Its eventual container uses the updated version. Floci persists this never-started state, and protects the version before attempting to initialize the database, including when a later proxy startup fails. Existing databases remain protected against major changes after a reboot, storage reload, or lost container. Older records without this state are treated as existing databases.

In mock mode (FLOCI_SERVICES_RDS_MOCK=true), EngineVersion updates the instance metadata. A minor upgrade is accepted on its own. A different major version needs AllowMajorVersionUpgrade, without which the request fails with InvalidParameterCombination. Major versions are compared on the leading version component, so a MySQL 8.0 to 8.4 upgrade reads as a minor one here while AWS treats it as major.

A refused member fails the whole request: a modify that carries a new DBInstanceClass alongside a shrinking AllocatedStorage returns InvalidParameterCombination and leaves the class as it was, so a read-back never reports a value the request did not get.

Accepted changes apply immediately. AWS defers a class, storage or engine-version change to the preferred maintenance window unless ApplyImmediately is set, and reports it under PendingModifiedValues until then. Floci runs no maintenance window and does not model PendingModifiedValues, so it applies accepted changes as soon as the request lands whatever ApplyImmediately says.

For standalone, non-Aurora instances with instance-owned storage, CreateDBInstance and ModifyDBInstance retain the StorageType values gp2, gp3, io1 and io2. A modify that omits the member leaves it unchanged; a request naming another type is refused with StorageTypeNotSupported before the instance is created or changed. Describe and modification responses report the stored value, and valid-modification discovery lists these four supported types. Aurora and cluster-member instance overrides remain ignored because their storage belongs to the cluster. Explicit type overrides also work on snapshot restores, point-in-time copies and read replicas. Snapshots and their copies retain the type; Floci carries it into snapshot restores, point-in-time copies and read replicas. It also survives persistent, hybrid and WAL storage reloads. Legacy records without the member retain the existing gp2 fallback.

Storage type changes apply immediately to control-plane metadata; the backing container volume's performance is unchanged. Iops, StorageThroughput and MultiAZ changes remain unimplemented. Omitted create requests retain Floci's existing gp2 default, which differs from the current AWS create default. Floci's snapshot and point-in-time copies inherit the source type when the request omits it, rather than applying the AWS restore default. Floci does not enforce every engine-specific storage allocation, IOPS restriction or regional storage-type availability. Magnetic standard storage is refused.

Storage autoscaling threshold changes

For standalone instances with instance-owned storage, ModifyDBInstance checks an explicit MaxAllocatedStorage against the current allocation. The threshold must be at least 10% higher, except that a value equal to the current allocation retains the existing disable handling. For example, with 20 GiB allocated, maxima of 19 or 21 GiB are refused and 22 GiB meets this minimum. Explicit zero and negative maxima are also refused. Rejection occurs before any settings in the request change, including backup retention and allocation. An omitted maximum retains its stored value without rechecking historical state.

The check uses the current allocation even when the request also changes storage. AWS applies threshold changes immediately while storage changes can wait for maintenance. Floci's existing immediate storage-change behavior remains; this is not a live AWS combined-growth capture or a complete check of all combined-update constraints.

Aurora/cluster members and RDS Custom remain outside this check. Engine/class upper limits, IOPS ratios and create/restore/replica constraints remain separate. The chosen HTTP 400 InvalidParameterCombination follows the adjacent allocated-storage refusal precedent. The message follows the guide's example, Invalid max storage size for {engine_name}; neither is claimed as an independently captured, universal live AWS maximum-error response.

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.

Parameter groups

A MySQL or MariaDB database runs with its parameter group: an Aurora MySQL cluster with its DB cluster parameter group, with the writer instance's DB parameter group on top (so an instance-level value such as max_connections wins, as on AWS), and a standalone instance with its DB parameter group. Floci passes each override to the server when it starts the database container, so a value set in the group is the engine's value; creating a cluster's writer restarts the cluster's container when the writer's group changes anything. A later change to a group, or a new DBClusterParameterGroupName on ModifyDBCluster or DBParameterGroupName on ModifyDBInstance, takes effect the next time the container starts: RebootDBInstance on the writer or on a standalone instance, a stop and start, or a Floci restart. A cluster's members share one database, so rebooting the writer restarts it for every member, and a reader's own DB parameter group is not applied. time_zone is passed as --default-time-zone, and Aurora's binlog_format of OFF turns binary logging off. A parameter the server does not know, such as one only Aurora has, is skipped with a warning in the database log. A formula value such as {DBInstanceClassMemory*3/4} keeps the server's default, and so do port, bind_address, socket, datadir and skip_networking, which Floci needs to reach the database, and require_secure_transport and skip_grant_tables, which would lock out Floci's proxy (it talks to the server without TLS). When the server refuses a value and stops, the instance, or every member of the cluster, reports incompatible-parameters and Floci logs the server's error; correct the group and reboot to start it again. A PostgreSQL or Aurora PostgreSQL database takes one value from its groups, layered and applied the same way: rds.logical_replication of 1 starts the server with wal_level=logical, as on RDS. Its other parameter group values, and those of SQL Server, are not applied yet.

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 matching option group is returned in one page, with no Marker

Pagination

DescribeDBInstances, DescribeDBClusters, DescribeDBSubnetGroups, DescribeDBParameterGroups, DescribeDBParameters, DescribeDBClusterParameters, DescribeOrderableDBInstanceOptions and DescribeOptionGroups return all matching results without a Marker. These handlers do not yet split results by MaxRecords or resume from Marker. An absent marker ends pagination, including for an empty result; an empty marker string must not be used as a continuation token.

DescribeDBClusterParameterGroups supports MaxRecords pagination and returns a non-empty Marker only when another page is available.

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 dump of the source taken when the replica is created, the same mechanism CreateDBSnapshot and RestoreDBInstanceFromDBSnapshot use, so it holds the source's data as of that moment. Writes made to the source afterwards are not streamed to the replica. PostgreSQL, MySQL and MariaDB sources are accepted; other engines are refused with InvalidDBInstanceState. 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.

Blue/Green deployments

CreateBlueGreenDeployment takes a PostgreSQL, MySQL or MariaDB DB instance by ARN as Source and creates its green copy, named <source>-green-<suffix>. The green instance inherits the blue one's settings and tags, with TargetEngineVersion, TargetDBParameterGroupName, TargetDBInstanceClass, TargetAllocatedStorage and TargetStorageType applied. Without TargetDBParameterGroupName it keeps the blue parameter group when the engine version stays in the same family, and gets the default group of the new family on a major upgrade. Both instances report the link in DescribeDBInstances as a read replica pair. The green database is initialised from a dump of the blue one taken at creation, the mechanism snapshots use, so it holds the blue data as of that moment; writes made to blue afterwards are not streamed to it.

Creation finishes before the response, so the deployment is reported AVAILABLE straight away with its SwitchoverDetails and Tasks. As on AWS, a source needs automated backups on (InvalidDBInstanceState otherwise), a lower TargetEngineVersion is refused, and an instance can be in one deployment at a time. Floci refuses with SourceDatabaseNotSupportedFault an instance that belongs to a cluster, is a read replica or has read replicas, keeps its master password in Secrets Manager, or is a DB proxy target, and refuses a DB cluster source with SourceClusterNotSupportedFault. TargetIops, TargetStorageThroughput and UpgradeTargetStorageConfig are accepted and not applied, as CreateDBInstance treats IOPS.

SwitchoverBlueGreenDeployment requires the deployment to be AVAILABLE and both instances available. Green takes the blue identifier, ARN, endpoint and tags, so clients that connect to the blue endpoint reach the new database without a change. Blue is renamed <name>-old<n>, moves to the endpoint green had, and keeps running. The deployment ends SWITCHOVER_COMPLETED, with Source naming the old instance and Target the new production one. The switchover completes before the response; SwitchoverTimeout is checked against the 30 to 3600 second range and has nothing else to bound. The old instance is not made read only.

Before switchover, a deployment whose blue or green instance has been deleted, or whose green instance was promoted, reports INVALID_CONFIGURATION and can no longer be switched over. DeleteBlueGreenDeployment deletes the green instance too with DeleteTarget, which is refused after switchover; without it the green instance is kept as a standalone instance. The blue instance is never touched. A deployment is tagged through its arn:aws:rds:<region>:<account>:deployment:<identifier> ARN.

Engine catalogue

DescribeDBEngineVersions and DescribeOrderableDBInstanceOptions read one curated catalogue: a representative version for each major version Floci knows through its managed parameter and option groups (PostgreSQL 13 to 18, MySQL 8.0 and 8.4, MariaDB 10.11, 11.2 and 11.4, SQL Server Standard 15, Aurora PostgreSQL 15 to 17 and Aurora MySQL 8.0). It is not AWS's full version list. Each version reports the parameter group family the create path computes for it, its major version and its upgrade targets (the engine's later versions, with IsMajorVersionUpgrade set across a major version). Each engine's default is the version a create request that names none gets (instances, clusters and global clusters alike), so DefaultOnly agrees with what Floci builds; for Aurora MySQL that is 8.0.mysql_aurora.3.05.2. Each version also reports what Floci supports for it: SupportsReadReplica for PostgreSQL only, SupportsGlobalDatabases for the two Aurora engines, and SupportsParallelQuery and SupportsBabelfish as false. ExportableLogTypes and SupportedFeatureNames list the engine's documented log types and IAM role feature names. EngineVersion takes an exact version or a major version such as 16, and the documented filters (db-parameter-group-family, engine, engine-mode, engine-version, status) apply. Every version is available, so IncludeAll changes nothing.

DescribeEngineDefaultParameters and DescribeEngineDefaultClusterParameters accept a family from the catalogue (InvalidParameterValue otherwise) and return an empty parameter list, consistent with DescribeDBParameters on a default group, which lists only values set on the group. DescribeValidDBInstanceModifications reports the instance's storage type and the sizes ModifyDBInstance stores as asked: the current size, and from the smallest real increase up to the engine's maximum (16384 GiB for SQL Server, 65536 GiB otherwise). Storage only grows, and for PostgreSQL, MySQL and MariaDB an increase under 10% is rounded up to 10%, so at 40 GiB the second range starts at 44. An Aurora instance has no storage of its own to modify, so its list is empty. DescribeOrderableDBInstanceOptions matches EngineVersion exactly or as a major version prefix, so 8.0 finds the MySQL 8.0.36 rows.

Cluster endpoints

CreateDBClusterEndpoint adds an Aurora custom endpoint to an available cluster. As the Aurora user guide describes, its type is READER or ANY (case-insensitive, as the CLI sends it), it holds either a static list or an exclusion list of the cluster's instances but not both (InvalidParameterCombination), and a READER endpoint cannot list the writer. A member that is not an instance of the cluster is DBInstanceNotFound. The identifier follows the RDS identifier rules (at most 63 characters), is stored lower case and is unique in the Region (DBClusterEndpointAlreadyExistsFault); a cluster holds at most five custom endpoints (DBClusterEndpointQuotaExceededFault). The endpoint's ARN, arn:aws:rds:<region>:<account>:cluster-endpoint:<id>, works with the tagging actions.

DescribeDBClusterEndpoints lists each cluster's built-in WRITER and READER endpoints followed by its custom endpoints, narrowed by DBClusterIdentifier, DBClusterEndpointIdentifier and the filters db-cluster-endpoint-type, db-cluster-endpoint-custom-type, db-cluster-endpoint-id and db-cluster-endpoint-status. ModifyDBClusterEndpoint changes the type or replaces the member list (giving static members clears the exclusion list, and the other way round). Deleting a cluster deletes its custom endpoints, and a deleted instance drops out of the lists that name it.

A READER endpoint leaves out the cluster's current writer, so after a failover the promoted instance no longer shows among its members, as Aurora adjusts READER membership. Member names match the cluster's instances regardless of case and are stored as the cluster spells them.

Custom endpoints are modelled, not routed: a custom endpoint reports the cluster's own endpoint host (read from the cluster each time, so it follows a restart onto another proxy port), so it is reachable, but connections through it go where the cluster endpoint sends them rather than being spread across the chosen members.

Data API endpoint

EnableHttpEndpoint and DisableHttpEndpoint turn a cluster's Data API endpoint on and off by the cluster's ARN, and DescribeDBClusters reports it as HttpEndpointEnabled. CreateDBCluster and ModifyDBCluster take EnableHttpEndpoint too, as does the AWS::RDS::DBCluster CloudFormation property, so Terraform's enable_http_endpoint and CDK's enableDataApi read back what they set.

The Data API is offered for Aurora PostgreSQL and Aurora MySQL clusters, so turning it on for any other engine is InvalidParameterCombination (a create checks before the cluster exists); turning it off is always accepted. An ARN that names no cluster in the caller's account and Region is ResourceNotFoundFault, and a cluster that is not available is InvalidResourceStateFault. The flag is recorded and reported only: the Data API (rds-data) does not refuse a cluster with it off.

Log files

DescribeDBLogFiles and DownloadDBLogFilePortion read an instance's log from its database container (docker logs, the most recent 100,000 lines), cut into files the way RDS names them: PostgreSQL rotates hourly into error/postgresql.log.YYYY-MM-DD-HH (UTC), MySQL and MariaDB keep error/mysql-error.log, and SQL Server keeps log/ERROR. An Aurora member reads its cluster's container. LastWritten is the time Docker recorded for the file's last line, and Size the bytes of its lines.

DescribeDBLogFiles takes FilenameContains, FileLastWritten (files written at or after it) and FileSize (files larger than it), and pages by MaxRecords / Marker. DownloadDBLogFilePortion follows the API reference: without a Marker it returns the most recent NumberOfLines lines (the whole file, up to 10000 lines, without either), Marker 0 starts at the first line, and the returned Marker continues until AdditionalDataPending is false. A block stops at 1 MB, and a single line longer than that is cut at 1 MB, as the API reference says the block is truncated. Control characters XML cannot carry (a terminal colour code) come back as U+FFFD.

An instance that is not available, or whose database container cannot be found or started, is DBInstanceNotReady, and an unknown file name DBLogFileNotFoundFault. Negative FileSize, FileLastWritten or Marker values are InvalidParameterValue. In mock RDS mode there is no container, so an instance has no log files.

IAM role associations

AddRoleToDBCluster and AddRoleToDBInstance associate an IAM role with an available cluster or instance, and DescribeDBClusters / DescribeDBInstances report it in AssociatedRoles with status ACTIVE straight away. CreateDBCluster accepts AssociatedRoles too: a list that names a role twice, or has an entry without a RoleArn, refuses the create before any cluster exists, and the roles are associated in one step, so a create that fails leaves no cluster behind.

FeatureName (such as s3Import, s3Export or Lambda) is optional for a cluster and required for an instance. A role is associated at most once per cluster (DBClusterRoleAlreadyExists, which covers the role ARN only, so two roles may share a feature), and a role or a feature at most once per instance (DBInstanceRoleAlreadyExists, documented as "The specified RoleArn or FeatureName value is already associated"). RemoveRoleFromDBCluster removes the role, matching the feature name when one is given, and RemoveRoleFromDBInstance removes the role for the feature named; an association that does not exist is DBClusterRoleNotFound / DBInstanceRoleNotFound. A stopped cluster or instance refuses both (InvalidDBClusterStateFault / InvalidDBInstanceState).

A FeatureName must be one the engine lists in SupportedFeatureNames (DescribeDBEngineVersions), matched without regard to case; any other is InvalidParameterValue, and a CreateDBCluster naming one creates nothing. MySQL, MariaDB and Aurora MySQL list none, so their roles take no feature name.

Associations are recorded, not exercised: Floci does not check the role in IAM and does not hand the role's credentials to the database, so an aws_s3 import still needs credentials of its own. Deleting a cluster or instance drops its associations, and snapshots, restores and read replicas start without any.

Aurora managed password rotation

ModifyDBCluster supports RotateMasterUserPassword=true for an existing RDS-managed master-user secret. Set ApplyImmediately=true; requests without it, without an existing managed secret, with MasterUserPassword, or disabling ManageMasterUserPassword in the same call are rejected before credentials change.

The local operation completes synchronously: it changes the running database's password, publishes a new AWSCURRENT secret version, and updates the cluster and member proxy credentials. The preceding version becomes AWSPREVIOUS. If secret publication fails, Floci attempts to restore the previous database credential and secret version labels. A backend failure leaves the previous secret current. Metadata-only RDS mock mode updates the secret and stored credentials without starting a database. Scheduled RDS-owned rotation through Secrets Manager remains outside this ModifyDBCluster operation.

aws --endpoint-url http://localhost:4566 rds modify-db-cluster \
  --db-cluster-identifier example --rotate-master-user-password --apply-immediately

Use the managed secret's new current value for subsequent SQL connections. Existing database sessions may remain connected after rotation, as with a normal password change; verify with fresh connections.

Aurora managed password opt-out

When ModifyDBCluster disables ManageMasterUserPassword while the managed secret has cross-Region replicas, the request succeeds but retains the cluster password and its MasterUserSecret metadata, as Aurora does. Remove the secret's replicas and retry to release password management. Other requested cluster settings still apply.

Floci reserves the secret while changing backend credentials, without holding a shared Secrets Manager lock during backend I/O. Replication and deletion requests for that secret fail while release is in progress; unrelated secrets remain available. A failed backend password rotation retains the managed secret and stored credentials. If Secrets Manager support is unavailable, opt-out fails before changing cluster state. This does not provide a transaction across database backends and persistent storage.

PostgreSQL restore connections

Snapshot and point in time restores drop the target's non-template databases with DROP DATABASE ... WITH (FORCE) before replaying the dump. This terminates connections on the restore target, including preloaded workers such as pg_cron; the source is unchanged. Custom PostgreSQL images must support this syntax (PostgreSQL 13 or later). Prepared transactions and active logical replication slots or subscriptions can still prevent a drop.

Point in time restore

RestoreDBInstanceToPointInTime and RestoreDBClusterToPointInTime check the request as AWS does: exactly one of RestoreTime (RestoreToTime for a cluster) and UseLatestRestorableTime, and a time inside the source's restorable window, or InvalidRestoreFault. The window is what the describe calls report. An instance's runs from the later of its creation and the start of its backup retention period up to LatestRestorableTime on DescribeDBInstances; an instance with BackupRetentionPeriod 0 reports no LatestRestorableTime and is refused with PointInTimeRestoreNotEnabled. Floci does not model a cluster's backup retention, so a cluster's window runs from its creation (EarliestRestorableTime) to LatestRestorableTime on DescribeDBClusters.

An instance source is named by SourceDBInstanceIdentifier, SourceDbiResourceId or SourceDBInstanceAutomatedBackupsArn, a cluster source by SourceDBClusterIdentifier (identifier or ARN) or SourceDbClusterResourceId. A resource ID or backups ARN can also name a deleted source through the automated backup it kept; see Automated backups. A restored instance takes the source's engine, version, credentials, database name, storage and encryption, and its instance class unless the request names one; everything else is the request's or the default a new instance gets. A restored cluster takes the source's engine, version, credentials, database name and encryption, and has no instances until they are added with CreateDBInstance, as on AWS.

Floci keeps no transaction log, so it cannot rebuild a database as it was at an earlier time. The target is seeded from a pg_dumpall of the source taken when the request arrives, the mechanism read replicas use, so the restored data is the source's latest state whatever time in the window is asked for; this is also why LatestRestorableTime is always the current time. Only PostgreSQL sources are accepted.

Automated backups

A standalone instance with BackupRetentionPeriod above 0 has an active automated backup, which DescribeDBInstanceAutomatedBackups builds from the instance: its RestoreWindow is the instance's restorable window, and its ARN is auto-backup:ab- followed by the DbiResourceId after db-. Aurora instances are not listed, since their backups belong to the cluster.

DeleteDBInstance and DeleteDBCluster take DeleteAutomatedBackups. It defaults to true, which removes the backups with the resource, as on AWS. With false, a standalone instance with backups on leaves a retained backup, and a cluster leaves one that DescribeDBClusterAutomatedBackups lists. Its restore window ends at the deletion. Outside mock mode a PostgreSQL source's data is saved with the backup (a pg_dumpall, as for snapshots), so a point in time restore from it brings the data back; if that copy fails, the delete fails and nothing is deleted. A restore from a backup that holds no data, such as one kept in mock mode, fails outside mock mode. Floci does not expire retained backups: they stay until DeleteDBInstanceAutomatedBackup or DeleteDBClusterAutomatedBackup removes them, and a backup of a live resource cannot be deleted (InvalidDBInstanceAutomatedBackupState, InvalidDBClusterAutomatedBackupStateFault).

StartDBInstanceAutomatedBackupsReplication is called in the destination Region with the source's ARN. The source must be a live standalone instance with backups on, in another Region. The replica is listed in the destination Region as replicating, with the BackupRetentionPeriod asked for (7 days by default), and the source lists it under DBInstanceAutomatedBackupsReplications in DescribeDBInstances. Replication is metadata only: no data is copied between Regions, so a restore from a replica copies the live source. StopDBInstanceAutomatedBackupsReplication, or deleting the source, keeps the replica as retained; a stop with nothing replicating to the Region answers InvalidDBInstanceState.

Exporting snapshots to Amazon S3

StartExportTask exports a DB snapshot or a DB cluster snapshot to an S3 bucket in Floci as Apache Parquet, laid out as RDS lays it out, so a reader written against RDS exports (OpenSearch Data Prepper's rds source, Athena, Glue) reads Floci's. ExportTaskIdentifier, SourceArn, S3BucketName, IamRoleArn and KmsKeyId are required, S3Prefix and ExportOnly are optional.

A task reports STARTING while the snapshot is restored, IN_PROGRESS with a PercentProgress while its tables are written, then COMPLETE or FAILED with a FailureCause. CancelExportTask moves a running task to CANCELING; it stops before its next table and becomes CANCELED, and the data it already wrote stays in the bucket, as on RDS. A table the export skips is named in WarningMessage. A task still running when Floci stops is FAILED as soon as Floci starts again, or CANCELED if it was being canceled, and the container and volume it was using are removed then. A StartExportTask that arrives while Floci is resetting waits for the reset to finish, and is refused with Throttling if it lasts more than 30 seconds.

The snapshot is restored into a PostgreSQL container started from the snapshot's image, with a Docker volume of its own in every storage mode, and both are removed once the export ends, whether it completed, failed or was canceled. Each table's rows are streamed out of the restored database (for up to an hour per table) and staged, with the Parquet written from them, in the bucket named by FLOCI_SERVICES_RDS_EXPORT_STAGING_BUCKET (floci-rds-export-staging, created on first use); only the finished Parquet object is written to the export's bucket, so a failed table leaves nothing there. The Parquet is written by the floci-duck sidecar, the one Athena uses, so an export needs Docker for both. In mock mode a task completes without writing anything, unless its bucket is in another region (see below).

Each table goes under <S3Prefix>/<ExportTaskIdentifier>/<database>/<schema>.<table>/1/ as part-00000-<uuid>.gz.parquet, compressed with GZIP. Floci reads a table in one batch and one partition, so each table has one file; an empty table has none. The task's own description is written next to the databases as export_info_<ExportTaskIdentifier>.json, with a export_tables_info_<ExportTaskIdentifier>_from_1_to_<N>.json that lists each table it wrote with the type every column was exported as. A backslash, backquote, double quote or space in an object path becomes an underscore.

Column types follow the RDS PostgreSQL mapping: smallint is INT32 annotated INT(16), integer INT32, bigint INT64, real FLOAT, double precision DOUBLE, boolean BOOLEAN and bytea binary. Every other type is a UTF-8 string holding PostgreSQL's text output for the value: numeric, money, dates, times and intervals, json and jsonb, uuid, arrays, ranges, enums, domains and extension types such as pgvector's vector. Dates and times are written in ISO format, a timestamptz in UTC.

ExportOnly takes database, database.schema or database.schema.table entries made of letters, digits, $ and _, and refuses anything else with InvalidExportOnly, since RDS supports a partial export only for such names. Every database that accepts connections is exported when it is absent. As on RDS, temporary and unlogged tables, views and materialized views are not exported, a partitioned table is exported once through its parent, and a table with a / in its name, or a column name holding a space or one of , ; { } ( ) = \n \t, is skipped. Floci also skips a table whose database or schema name has a /, which would split its path in the bucket, and a table with two column names that differ only in case, such as "Foo" and "foo", which its Parquet writer, DuckDB, cannot keep apart; both are named in WarningMessage. A column of a type or domain of the user's own is exported as a string, whatever its name. A table that others inherit from (INHERITS) is exported with its own rows only, since each child is exported as a table of its own.

What differs from RDS:

  • The IAM role is not assumed and the KMS key encrypts nothing: both are recorded and reported back as given. The bucket must exist, or the request fails with InvalidS3BucketFault. A bucket in another region than the snapshot's is accepted and the task then ends FAILED, as on RDS.
  • Only PostgreSQL snapshots can be exported: the export reads a pg_dumpall, and a MySQL or MariaDB snapshot holds a mysqldump instead. Any other source is refused with InvalidExportSourceState, and so is a snapshot that is not available.
  • SourceArn must name a snapshot: exporting a live DB cluster (SourceType CLUSTER) is not supported.
  • TotalExtractedDataInGB is the size of the rows Floci read, in whole gigabytes, and is 0 for most local data sets.

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-aws-rds-{resourceId}-{volumeId}, with the instance's or cluster's resource id) 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

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 checks the master username and password at the proxy layer. Other database users authenticate against the backend engine. For PostgreSQL instances with IAM database authentication enabled, the database role's rds_iam membership also determines which authentication method it can use.

PostgreSQL authentication responses are buffered before they are flushed to the client, so the password challenge is not emitted as separate header and payload writes. This supports PgBouncer logins over plaintext and TLS while keeping the same password, IAM and database-role checks.

For PostgreSQL, the proxy logs in to the backend with whatever the backend asks for: trust, a cleartext or MD5 password, or SCRAM-SHA-256. With SCRAM, it checks the backend's server signature before it accepts the login, prepares the password with SASLprep as PostgreSQL does, and refuses a backend that switches to a cleartext or MD5 request, or starts a second exchange, once the first has begun. A backend login the proxy refuses reaches the client as FATAL 08006 Backend database authentication failed.

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.

Aurora members use their cluster's IAM database authentication setting and master username and password for backend connections. EnableIAMDatabaseAuthentication on CreateDBInstance does not override the cluster setting. A member request with MasterUsername or MasterUserPassword returns InvalidParameterCombination; configure those credentials on the cluster and omit them from the member request. Managed master secrets belong to the cluster; ManageMasterUserPassword on a member does not create a separate member secret. When a cluster record lacks a credential, the member retains its normalized default for that field.

ModifyDBInstance preserves the cluster-owned master password when MasterUserPassword is supplied for a member; other supported instance settings still apply. Change the cluster password with ModifyDBCluster.

Accepted cluster password changes update stored member credentials even when the cluster has no backend or runs in mock mode. An unchanged password does not update relays. Rotating an initialized data volume requires a running backend; changing stored metadata alone does not rotate that volume.

Changing EnableIAMDatabaseAuthentication with ModifyDBCluster updates existing Aurora members and applies to new connections through the cluster and member endpoints. Omitting the flag preserves the current setting. Existing connections are not disconnected.

A token can be signed with an access key or with temporary credentials: an assumed role's, or the execution role credentials Floci hands a Lambda function. A token signed with temporary credentials carries their session token in X-Amz-Security-Token, and it is accepted while that session is valid and only with the session token issued alongside the access key.

On RDS, a token is only good for the endpoint it was generated for: the hostname, port and region passed to generate-db-auth-token are the ones the instance (or cluster, or RDS Proxy) publishes. MySQL and MariaDB endpoints in Floci always refuse a token generated for another endpoint. PostgreSQL endpoints do the same by default; set FLOCI_SERVICES_RDS_IAM_TOKEN_ENDPOINT_BINDING=false to accept a token generated for another name, for clients that generate tokens for a container name or DNS alias the endpoint does not publish. Either way, the username must match the DBUser in the token exactly. Because clients on the host reach the same proxy over the loopback interface, a token generated for localhost or 127.0.0.1 on the published port is accepted as well. Clients on a Docker network connect by Floci's container name, so set FLOCI_SERVICES_RDS_ENDPOINT_HOST to that name (see Docker Compose) so it is what the endpoint publishes and tokens are generated for. With IAM enforcement turned on, the token's principal must also be allowed rds-db:connect on the database user, scoped the way AWS scopes it:

arn:aws:rds-db:<region>:<account-id>:dbuser:<DbiResourceId>/<db-user-name>

Aurora cluster endpoints and their member instance endpoints use the cluster's DbClusterResourceId, including after member reboot or runtime recovery, and connections through an RDS Proxy use the proxy's prx-… resource id. A token that fails any of these checks is refused with the engine's ordinary authentication failure; the reason is written to Floci's log.

On native PostgreSQL instance and cluster endpoints, the token names a database role (DBUser). The role must have its own LOGIN attribute and a direct or indirect grant of rds_iam, including when logging in as the master user. Standard RDS Proxy client IAM connections do not require that database IAM grant: the backend role still needs LOGIN, and the session remains bound to that role's identity. End-to-end DB Proxy IAM is not supported by the real database mode. Create an application role for a native database endpoint as the master user:

CREATE ROLE app_user LOGIN;
GRANT rds_iam TO app_user;

On native database endpoints with IAM authentication enabled, membership in rds_iam makes IAM take precedence over the role's password. Roles without that membership continue to use passwords. These database-role checks apply independently of Floci's IAM policy enforcement setting. Disabling IAM database authentication restores ordinary password authentication for new connections. Password attempts refused because of that membership report PAM authentication failed with SQLSTATE 28000.

The IAM session runs as the token's role: current_user and session_user both report it, and objects it creates belong to it. A missing role or a role without LOGIN is refused with an authentication failure. Native database endpoints also require rds_iam membership. Grant the application any additional database privileges it 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.

The parameters a PostgreSQL client sends when it connects (options such as -c search_path=app, application_name, and any other run-time parameter) apply to the session as they do on RDS. An IAM session for a role other than the master gets them once the session has been handed over to the token's role, applied with set_config() so PostgreSQL checks each one against that role's privileges, and a parameter PostgreSQL refuses fails the login with PostgreSQL's own error, as it would at startup. The role's own ALTER ROLE ... SET defaults load as they do at login: the role-wide ones, then those for the database. They are the values RESET returns to, and they apply with the authority of whoever stored them, so a superuser-only default set by an administrator binds the role even after RESET ALL. To get this, a role with defaults has its backend session opened a second time, with the defaults as startup options. A default PostgreSQL refuses is skipped with a WARNING, as at login. A role default is checked against the role's memberships, and a client_encoding default applies unless the client chose an encoding; both are set once the session is the role's, so RESET does not return to them. Defaults stored on the master role itself are not undone for these sessions. A session_authorization naming any other role is refused with permission denied to set session authorization before anything is applied, since PostgreSQL would authorize it against the master the proxy connected as. Because those sessions have already started, two things differ from RDS: options may carry only -c name=value and --name=value switches, and a parameter that can only be set at connection start is refused with cannot be set after connection start. And because the values are set with set_config() rather than at startup, RESET (and RESET ALL) takes such a parameter back to the server default, not to the value the client connected with: after -c search_path=app, RESET search_path gives "$user", public where RDS keeps app.

A logical replication connection (replication=database) can log in with an IAM token when the token's role may replicate: it is a member of rds_replication, directly or through another role, or has the REPLICATION attribute. Any other role is refused with FATAL: permission denied to start WAL sender. A physical replication connection (replication=true) is refused by the instance, as it is for a password login. On a logical replication connection, physical replication commands are refused, as on RDS, where rds_replication covers logical replication only: BASE_BACKUP, START_REPLICATION other than START_REPLICATION SLOT ... LOGICAL, CREATE_REPLICATION_SLOT other than a LOGICAL slot, READ_REPLICATION_SLOT, TIMELINE_HISTORY and UPLOAD_MANIFEST fail with ERROR: permission denied to use physical replication (SQLSTATE 42501) and the session stays open. PostgreSQL raises that error from PL/pgSQL, so it carries a CONTEXT line. Two things differ from RDS. RDS accepts these logins only once rds.iam_auth_for_replication and rds.logical_replication are both set to 1 in the parameter group; Floci accepts them whenever IAM database authentication is enabled. And rds_replication is an ordinary role here, so it lets a role start a replication connection but not call the SQL slot functions such as pg_create_logical_replication_slot(), which PostgreSQL allows only to a role with the REPLICATION attribute; create slots with CREATE_REPLICATION_SLOT over the replication connection, or give the role REPLICATION.

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 because the plugin is unavailable. 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.

On a connection that negotiates zstd compression, the proxy forwards command frames unchanged, including frames with an uncompressed payload. It does not rewrite this IAM user DDL, so the backend rejects the unsupported AWSAuthenticationPlugin on that connection.

For users created through the rewrite, SHOW CREATE USER reports the substituted plugin rather than AWSAuthenticationPlugin, so a Terraform or Pulumi refresh sees drift on auth_plugin. MySQL IAM token login is supported over TLS: the proxy can request a mysql_clear_password auth switch to validate the token, then authenticates to the container as the master user. Unlike RDS, that MySQL session stays the master user: CURRENT_USER() reports the master, and the IAM user's own grants do not apply. The PostgreSQL proxy instead hands the session over to the role named in the token.

Certificate authorities

DescribeCertificates lists the Region's RDS certificate authorities, rds-ca-rsa2048-g1, rds-ca-rsa4096-g1 and rds-ca-ecc384-g1, with the thumbprint and validity AWS reports. They are vendored from the certificate bundles AWS publishes for each Region of the aws partition by tools/aws/regen_rds_ca_certificates.py. As the user guide says, ap-south-1, ap-southeast-4, ca-west-1, eu-central-2, eu-south-2 and il-central-1 offer only rds-ca-rsa2048-g1, though their bundles carry all three. A Region with no vendored entry, such as a GovCloud, China or custom one, reports us-east-1's certificates under its own ARN.

  • CertificateIdentifier filters, without regard to case, and an unknown one is CertificateNotFound. MaxRecords (20 to 100) and Marker page the list. Filters is not taken, since the API reference says it isn't supported.
  • DefaultCertificateForNewLaunches is rds-ca-rsa2048-g1 until ModifyCertificates sets an override for the account and Region. The overriding certificate then reports CustomerOverride true and its CustomerOverrideValidTill. RemoveCustomerOverride puts RDS's default back. Sending both members, or neither, is InvalidParameterCombination. AWS doesn't document what it does here, so this behavior is a guess.
  • CreateDBInstance, RestoreDBInstanceFromDBSnapshot, RestoreDBInstanceToPointInTime, CreateDBInstanceReadReplica and ModifyDBInstance take CACertificateIdentifier. An instance given none gets the account's default when it is created. An unknown identifier is CertificateNotFound. A modify changes it at once, as Floci applies every modification immediately, and a blank value leaves it as it was. CertificateRotationRestart is accepted and has no effect.
  • Instances report CACertificateIdentifier and CertificateDetails (CAIdentifier, with the CA's ValidTill, as Floci keeps no per-instance server certificate). An instance stored before this was recorded reports rds-ca-rsa2048-g1, since an override applies only to instances created after it. AWS::RDS::DBInstance takes CACertificateIdentifier and resolves CertificateDetails.CAIdentifier and CertificateDetails.ValidTill in Fn::GetAtt.

The identifier is metadata: the auth proxy presents a certificate from Floci's own CA whatever the instance names, so clients trust Floci's CA (see TLS / SSL), not AWS's bundle. Multi-AZ DB clusters do not take CACertificateIdentifier yet.

TLS / SSL

The RDS auth proxy terminates TLS itself (the backend container stays plaintext). It presents a non-CA server certificate followed by Floci's shared root CA, so strict TLS clients can validate an end-entity certificate rather than being asked to accept a CA as a server. The server certificate's Subject Alternative Names cover every advertised DB instance, cluster, or RDS Proxy host: the Docker bridge IP, host.docker.internal, localhost, or whatever rds.endpointHost resolves to.

The shared CA is the same one used by ACM, IoT, and EKS. It is persisted at {storage.persistent-path}/tls/floci-root-ca.crt, with its owner-only private key in floci-root-ca.key. The server certificate is issued in memory on startup and when a new host appears, and renewed before expiry during TLS use; its SAN list is recorded in rds-ca.metadata.json. Renewal preserves the CA and SANs. If the CA itself expires, the proxy refuses new TLS use rather than silently changing client trust; restart to regenerate the unusable CA and trust its replacement. The shared CA certificate and key do not change during SAN growth or restarts. Missing or corrupt SAN metadata is rebuilt without replacing a valid CA. An invalid or unusable CA/key pair is replaced with a warning; only then must clients trust the replacement CA again.

The proxy also writes the shared root certificate to tls/rds-ca.crt, preserving existing PGSSLROOTCERT and MySQL --ssl-ca paths. This compatibility copy is refreshed when the proxy initializes, even if the old RDS certificate is expired or corrupt. The unused rds-ca.key is removed; the shared CA key and existing rds-ca.metadata.json SAN list are retained. The shared certificate is also available from GET /_floci/ca.pem.

The proxy logs the shared certificate path when it first issues a server certificate:

RDS proxy TLS: for sslmode=verify-full set PGSSLROOTCERT=./data/tls/floci-root-ca.crt

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

# PostgreSQL
PGSSLROOTCERT=./data/tls/floci-root-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/floci-root-ca.crt

IAM lifecycle resources and tags

With IAM enforcement enabled, RDS request-resource mappings cover the complete namespace generated from AWS's Service Authorization Reference and pinned botocore models. Parameter groups, subnet groups, DB instances and DB clusters use their named ARNs. Stored proxy and endpoint identities are resolved from request names, and target group lookups include the owning proxy. ARN-valued members, including RemoveFromGlobalCluster's DbClusterIdentifier, are checked as ARNs. Unfiltered describe requests continue to require a wildcard grant.

For modeled taggable RDS resources (including endpoints and proxies) and DocumentDB clusters, instances and snapshots sharing the RDS ARN namespace, supported aws:ResourceTag and RDS resource-specific tag conditions read stored tags from the exact target ARN's account, Region and partition. IAM and tagging share resource lookup dispatch. IAM reads neither create defaults nor migrate legacy records; named lookups use direct account-scoped keys, and generated proxy identities only search their owning account. Create-time request tags remain separate from existing-resource tags. Resource types without modeled storage retain the generated wildcard fallback when no stored identity exists.