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.serverlessand 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
Statusand eachDBInstanceStatusstayavailable.DescribeEventsreports RDS-EVENT-0370 to 0374 for each instance, for example "Successfully paused the DB instance.". While the cluster is paused,ServerlessDatabaseCapacityreports 0 andACUUtilizationandCPUUtilizationreport 0 percent in theAWS/RDSnamespace once a minute, byDBClusterIdentifierand byDBInstanceIdentifier. 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_MILLISis set;15000exercises client connect timeouts, retries and connection-pool validation against a realistic cold start. - Configuration changes. A
ModifyDBClusterthat raisesMinCapacityabove 0 or changesSecondsUntilAutoPauseresumes a paused cluster and restarts its idle clock. - Commands Floci runs in the container.
CreateDBClusterSnapshotand 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=falsekeeps 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 endsFAILED, as on RDS. - Only PostgreSQL snapshots can be exported: the export reads a
pg_dumpall, and a MySQL or MariaDB snapshot holds amysqldumpinstead. Any other source is refused withInvalidExportSourceState, and so is a snapshot that is notavailable. SourceArnmust name a snapshot: exporting a live DB cluster (SourceTypeCLUSTER) is not supported.TotalExtractedDataInGBis 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:
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:
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:
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.
CertificateIdentifierfilters, without regard to case, and an unknown one isCertificateNotFound.MaxRecords(20 to 100) andMarkerpage the list.Filtersis not taken, since the API reference says it isn't supported.DefaultCertificateForNewLaunchesisrds-ca-rsa2048-g1untilModifyCertificatessets an override for the account and Region. The overriding certificate then reportsCustomerOverridetrue and itsCustomerOverrideValidTill.RemoveCustomerOverrideputs RDS's default back. Sending both members, or neither, isInvalidParameterCombination. AWS doesn't document what it does here, so this behavior is a guess.CreateDBInstance,RestoreDBInstanceFromDBSnapshot,RestoreDBInstanceToPointInTime,CreateDBInstanceReadReplicaandModifyDBInstancetakeCACertificateIdentifier. An instance given none gets the account's default when it is created. An unknown identifier isCertificateNotFound. A modify changes it at once, as Floci applies every modification immediately, and a blank value leaves it as it was.CertificateRotationRestartis accepted and has no effect.- Instances report
CACertificateIdentifierandCertificateDetails(CAIdentifier, with the CA'sValidTill, as Floci keeps no per-instance server certificate). An instance stored before this was recorded reportsrds-ca-rsa2048-g1, since an override applies only to instances created after it.AWS::RDS::DBInstancetakesCACertificateIdentifierand resolvesCertificateDetails.CAIdentifierandCertificateDetails.ValidTillinFn::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:
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.