Light, fluffy, and always free - The AWS Local Emulator alternative
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 PostgreSQL snapshot 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.
Supported Management Actions
| Action | Description |
|---|---|
CreateDBInstance |
Start a new database instance |
DescribeDBInstances |
List instances and their connection info — the list form includes DocumentDB and Neptune instances and takes an engine filter |
DeleteDBInstance |
Stop and remove an instance |
ModifyDBInstance |
Update instance settings |
RebootDBInstance |
Restart a database instance |
StopDBInstance |
Stop a standalone instance temporarily: an optional DBSnapshotIdentifier first, then its container goes away while the record, endpoint and volume stay |
StartDBInstance |
Start a stopped instance on the volume it kept, same endpoint |
StopDBCluster |
Stop a cluster and its member instances |
StartDBCluster |
Start a stopped cluster and its members |
RebootDBCluster |
Restart a cluster's database and its members' proxies |
CreateDBInstanceReadReplica |
Create a read replica of a PostgreSQL instance, initialised from a copy of the source; see Read replicas |
PromoteReadReplica |
Detach a read replica into a standalone instance and turn automated backups on |
SwitchoverReadReplica |
Refused with InvalidDBInstanceState: AWS supports switchover only for Oracle and SQL Server replicas, neither of which is emulated |
PromoteReadReplicaDBCluster |
Refused with InvalidDBClusterStateFault: no cluster is created as a replica of an instance |
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 |
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 |
DescribeDBClusterSnapshotAttributes |
Return the restore attribute of a cluster snapshot |
ModifyDBClusterSnapshotAttribute |
Add or remove restore values (account ids or all) on a cluster snapshot |
StartExportTask |
Start an export task for a DB snapshot or DB cluster snapshot; 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 |
AddTagsToResource |
Add tags to a DB resource |
ListTagsForResource |
List tags for a DB resource |
RemoveTagsFromResource |
Remove tags from a DB resource |
CreateDBInstance stores StorageEncrypted, KmsKeyId, BackupRetentionPeriod,
PreferredBackupWindow, PreferredMaintenanceWindow and CopyTagsToSnapshot, and
DescribeDBInstances returns them; ModifyDBInstance changes the backup settings and
the windows. The same checks as on AWS apply (KmsKeyId needs StorageEncrypted,
windows are at least 30 minutes and may not overlap). KmsKeyId is accepted as a key ARN,
key id, alias ARN or alias name, resolved against the KMS store in the request's region and
returned as the key ARN; a key that does not exist or is not enabled is
KMSKeyNotAccessibleFault. Where AWS picks a random window,
Floci uses 04:00-06:00 and mon:00:00-mon:03:00 (or, when the window given on create overlaps the
usual default, a 30-minute window starting where the given one ends); a window given on modify is
checked against the instance's other window. Modifications apply immediately —
PendingModifiedValues is not modeled.
!!! note "Stopping and starting"
`StopDBInstance` and `StopDBCluster` follow the user guide: the response reports `stopping`
(`StopDBCluster` for the cluster and its members), the stored status settles to `stopped`,
and `StartDBInstance` / `StartDBCluster` report `starting` and settle to `available`. While
stopped, the identifier, endpoint (same port), parameter and option groups and the Docker
volume all stay, so the data comes back on start; the container itself is removed and the
endpoint refuses connections. `StopDBInstance` refuses a cluster member (use `StopDBCluster`),
a read replica or an instance that has one, and anything not `available`, with
`InvalidDBInstanceState`; `ModifyDBInstance` on a stopped instance is refused the same way.
`DeleteDBInstance` works on a stopped instance. A stopped instance or cluster stays stopped
across an emulator restart. Not modeled: the automatic restart after seven days, and the
Multi-AZ SQL Server restriction.
!!! note "DB snapshot tagging and lifecycle"
`CreateDBSnapshot` accepts `Tags`, and `TagResource`/`UntagResource`/`ListTagsForResource`
work against a snapshot's ARN like they do for other tagged resource types.
`DescribeDBSnapshotAttributes`/`ModifyDBSnapshotAttribute` are modeled as plain in-memory
state (no real cross-account sharing). Available manual snapshots can be deleted, copied by
identifier or ARN, and modified. Copies retain the source data and can copy source tags or add
request tags. Snapshots are region-scoped like DB instances and clusters: `DBSnapshotArn` reflects
the request's signed region, and a snapshot is only visible to `Describe`/`Tag` calls signed
for that same region. Cluster snapshots follow the same lifecycle: `CreateDBClusterSnapshot`
dumps the cluster's database, `RestoreDBClusterFromSnapshot` loads it into a new cluster, and
`Copy`, `Delete` and the `restore` attribute behave as they do for instance snapshots, under
`arn:aws:rds:<region>:<account>:cluster-snapshot:<name>`. RDS reserved instances aren't
modeled (there's no reserved-instance API), so tagging doesn't apply to them.
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.
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_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_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.
When Docker publishes RDS proxy ports dynamically, set FLOCI_SERVICES_RDS_ENDPOINT_HOST to the
hostname used by clients. Floci inspects its own container through the Docker socket and returns the
corresponding published port from DescribeDBInstances and DescribeDBClusters. Leave the setting
unset to retain the auto-detected endpoint host and configured proxy port.
services:
floci:
image: floci/floci:latest
ports:
- "4566:4566"
- "7001-7099:7001-7099" # RDS proxy ports
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
FLOCI_SERVICES_DOCKER_NETWORK: my-project_default
FLOCI_SERVICES_RDS_PROXY_BASE_PORT: "7001"
Without a reachable Docker daemon
A DB instance or cluster record is metadata. Its identifier, ARN, endpoint address and tags come
from Floci's configuration, not from Docker. When no daemon is reachable, because Floci runs inside
Docker with no socket mounted or the daemon on the host is stopped, CreateDBInstance and
CreateDBCluster still succeed and the resource reaches available. DescribeDBInstances,
ModifyDBInstance, the tagging APIs and DeleteDBInstance all work on that record, and Floci logs
a warning naming the missing daemon.
Nothing listens behind the endpoint in that state. The backing container is retried by every
operation that needs the live database, so it starts as soon as a daemon becomes reachable. Until
then, RDS Data API calls fail with a modelled InternalServerErrorException that names the missing
daemon. A daemon that is reachable but cannot start the container still fails CreateDBInstance
outright, since that is a real error rather than a degraded mode.
Mock mode (CI / tests)
Set FLOCI_SERVICES_RDS_MOCK=true when you only need the management API shape: clusters and
instances are registered as available immediately, with no Docker container or auth proxy behind
them. Each resource still gets a unique endpoint port, but nothing listens on it.
# docker-compose.yml — CI / test environment
services:
floci:
image: floci/floci:latest
environment:
FLOCI_SERVICES_RDS_MOCK: "true"
!!! note "Switching modes over persisted state"
With a persistent storage mode, changing FLOCI_SERVICES_RDS_MOCK between restarts is
best-effort, as with the other mock-capable services: resources created in real mode and
deleted under mock leave their containers and volumes behind, and resources created in mock
mode are restored with fresh, empty containers when loaded in real mode.
!!! warning "DB proxy endpoint routing"
DB proxy control-plane resources and target registration are modeled, but Floci's current
single-host TCP relay cannot expose multiple same-engine DB proxies as distinct AWS-style bare
hostnames on the same engine-default port. The standard Docker Compose mapping also exposes
only the `7001-7099` instance/cluster proxy range, not `1433`, `3306`, or `5432`. Use mock mode
for DB proxy provisioning workflows until a dedicated endpoint-routing design is implemented.
!!! note "DB proxy control-plane settings"
Proxy and target-group settings are persisted and round-trip through the RDS Query API and
CloudFormation. Pool sizing, borrow timeout, idle timeout, TLS, init-query, and session-pinning
settings are currently control-plane metadata; the TCP relay does not yet implement those data-plane
behaviors. `DefaultAuthScheme=IAM_AUTH` is supported for control-plane workflows, but a real-mode
proxy using that scheme cannot register a target until backend IAM authentication is implemented.
Requests to `RegisterDBProxyTargets`, `DeregisterDBProxyTargets`, and
`DescribeDBProxyTargets` use the `default` target group when `TargetGroupName` is omitted,
matching the RDS API contract.
`CreateDBProxy`/`AWS::RDS::DBProxy` accept `EndpointNetworkType` (`IPV4`, `IPV6`, or `DUAL`) and
`TargetConnectionNetworkType` (`IPV4` or `IPV6`) and round-trip them like the other proxy
settings above; the TCP relay itself still only listens on IPv4, so a non-`IPV4` value is
accepted as control-plane metadata rather than making the relay dual-stack. A non-`IPV4` value
is rejected with `InvalidParameterValue` unless the proxy's VPC and every subnet in
`VpcSubnetIds` already carry an associated IPv6 CIDR block, matching AWS's own network
prerequisites for RDS Proxy.
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.
Modifying a DB instance
ModifyDBInstance applies DBInstanceClass, AllocatedStorage and EngineVersion, 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.
EngineVersion accepts a minor upgrade 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.
Two deviations are worth knowing:
- Changes apply immediately. AWS defers a class, storage or engine-version change to the
preferred maintenance window unless
ApplyImmediatelyis set, and reports it underPendingModifiedValuesuntil then. Floci runs no maintenance window and does not modelPendingModifiedValues, so it applies the change as soon as the request lands whateverApplyImmediatelysays. Without this a deferred change would never be applied at all, and every read-back would report the same drift. - The backing container is not re-imaged. An engine-version change is recorded on the instance and reported on read, but the container started at create time keeps running the image it was started with. This is control-plane compatibility, like Aurora Serverless v2 scaling above.
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. PostgreSQL and SQL Server databases do not take parameter
group values 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 group is returned in one page, as with every other RDS list action |
Read replicas
CreateDBInstanceReadReplica creates a standalone instance with its own container and endpoint.
As on AWS it inherits the source's engine, version, credentials and database name and, unless the
request overrides them, the instance class, storage and minor version upgrade setting. A replica
in the source's region also inherits the source's parameter group, option group, subnet group and
security groups; a replica in another region (source given by ARN, --region set to the
destination) gets that region's defaults. IAM authentication and CopyTagsToSnapshot are off
unless requested. The replica starts with BackupRetentionPeriod 0. Both ends report the link
the way DescribeDBInstances does: the replica carries ReadReplicaSourceDBInstanceIdentifier
and a StatusInfos entry of type read replication, the source lists it under
ReadReplicaDBInstanceIdentifiers; within a region the link is the identifier, across regions
it is the ARN. A DBSubnetGroupName with a source given by plain identifier is refused with
DBSubnetGroupNotAllowedFault, as on AWS.
The replica's database is initialised from a pg_dumpall of the source taken when the replica is
created, the same mechanism RestoreDBInstanceFromDBSnapshot uses, so it holds the source's data
as of that moment. Writes made to the source afterwards are not streamed to the replica. Because
the copy is dump based, only PostgreSQL sources are accepted; MySQL and MariaDB sources are refused
with InvalidDBInstanceState, as CreateDBSnapshot refuses them. A source with automated backups
off (BackupRetentionPeriod 0) is refused with the same error AWS uses.
PromoteReadReplica clears the link on both ends, sets the requested BackupRetentionPeriod
(one day when omitted) and PreferredBackupWindow, and reboots the instance as AWS does, so open
connections drop while the container, endpoint and data stay. Deleting a source promotes its
same-region replicas; a cross-region replica keeps its link with the replication status
terminated until it is promoted or deleted, which is what AWS does for PostgreSQL. Deleting a
replica drops it from its source's list.
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 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 or SourceDbiResourceId, a cluster
source by SourceDBClusterIdentifier (identifier or ARN) or SourceDbClusterResourceId. Restoring
from retained automated backups (SourceDBInstanceAutomatedBackupsArn, used for a deleted instance)
is not supported, since Floci keeps no automated backups, and answers
DBInstanceAutomatedBackupNotFound. 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. As with
CreateDBSnapshot, only PostgreSQL sources are accepted.
Exporting snapshots to Amazon S3
StartExportTask, DescribeExportTasks and CancelExportTask manage RDS snapshot export tasks.
ExportTaskIdentifier, SourceArn, S3BucketName, IamRoleArn and KmsKeyId are required,
S3Prefix and ExportOnly are optional.
A task reports STARTING, then 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. 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.
Floci does not write snapshot data to S3 yet. In mock mode a task completes
without writing anything, unless its bucket is in another region (see below). Outside mock mode a task is accepted and then ends FAILED with the
FailureCause Floci does not write snapshot data to S3 yet: export tasks complete only in mock mode (FLOCI_SERVICES_RDS_MOCK=true).
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.
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, since Floci's snapshots hold PostgreSQL data only.
Any other source is refused with
InvalidExportSourceState, and so is a snapshot that is notavailable. SourceArnmust name a snapshot: exporting a live DB cluster (SourceTypeCLUSTER) is not supported.
Global clusters
CreateGlobalCluster creates an Aurora global database (aurora-mysql or aurora-postgresql),
either empty or with an existing Aurora cluster as its primary through SourceDBClusterIdentifier
(an ARN, or an identifier in the request's region), in which case engine, version, database name
and encryption come from that cluster and may not be given, as on AWS. The record is account wide:
its ARN has no region and DescribeGlobalClusters lists it from any region.
CreateDBCluster with GlobalClusterIdentifier joins a cluster: the first one becomes the
primary, every later one a secondary. A secondary must be in a region that holds neither the
primary nor another secondary, may not carry its own master credentials or database name (it takes
the primary's), and its database is initialised from a pg_dumpall of the primary the way a read
replica is, so only aurora-postgresql primaries accept secondaries; writes after that are not
streamed. DescribeGlobalClusters reports every member with IsWriter and, on the primary, the
secondaries under Readers; DescribeDBClusters reports GlobalClusterIdentifier on members.
SwitchoverGlobalCluster, and FailoverGlobalCluster with or without AllowDataLoss, promote
the named secondary and demote the current primary to a secondary, the topology AWS keeps for a
switchover and restores after a managed failover once the old primary region is healthy again.
The response is the completed state; AWS answers with a pending FailoverState because the
operation runs asynchronously there. RemoveFromGlobalCluster detaches a member into a standalone
cluster; the primary can only be removed once every secondary is gone, and deleting the primary
cluster while secondaries remain is refused the same way. DeleteGlobalCluster needs an empty
global cluster with deletion protection off.
FailoverDBCluster moves the writer role inside a DB cluster to the named reader instance, or to
the first reader when none is named; a cluster with no reader has nothing to fail over to and is
refused. DescribeDBClusters reports the role as IsClusterWriter, and deleting the writer
promotes a remaining member, as Aurora does on its own.
Persistence
Each DB instance and cluster gets its own named Docker volume (floci-rds-{volumeId}) created
automatically. No configuration is required.
| Scenario | Volume behavior |
|---|---|
memory mode (default) |
Volume is removed automatically when the instance is deleted |
persistent / hybrid / wal |
Volume is retained after delete — data survives for manual recovery |
# CI — ephemeral, volumes cleaned up on each delete
FLOCI_STORAGE_MODE=memory
# Local dev — retain DB data across Floci restarts
FLOCI_STORAGE_MODE=hybrid
# Local dev — also remove volumes immediately on delete
FLOCI_STORAGE_MODE=hybrid
FLOCI_STORAGE_PRUNE_VOLUMES_ON_DELETE=true
To use a host bind mount instead of a named volume (advanced), set an absolute path:
FLOCI_STORAGE_HOST_PERSISTENT_PATH=/absolute/host/path/data
!!! note "Docker Desktop on macOS" Named volumes work correctly on Docker Desktop for macOS. Bind mounts to paths inside the Floci container are not supported — use named volumes (the default).
Authentication
The RDS auth proxy 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.
IAM database authentication is also supported. Set --enable-iam-database-authentication at instance creation time and use aws rds generate-db-auth-token to obtain a token.
Aurora members use their cluster's IAM database authentication setting and master
username and password for backend connections. EnableIAMDatabaseAuthentication
on CreateDBInstance does not override the cluster setting. A member request with
MasterUsername or MasterUserPassword returns InvalidParameterCombination;
configure those credentials on the cluster and omit them from the member request.
Managed master secrets belong to the cluster; ManageMasterUserPassword on a member
does not create a separate member secret. When a cluster record lacks a credential,
the member retains its normalized default for that field.
ModifyDBInstance preserves the cluster-owned master password when
MasterUserPassword is supplied for a member; other supported instance settings
still apply. Change the cluster password with ModifyDBCluster.
Accepted cluster password changes update stored member credentials even when the cluster has no backend or runs in mock mode. An unchanged password does not update relays. Rotating an initialized data volume requires a running backend; changing stored metadata alone does not rotate that volume.
Changing EnableIAMDatabaseAuthentication with ModifyDBCluster updates existing
Aurora members and applies to new connections through the cluster and member
endpoints. Omitting the flag preserves the current setting. Existing connections
are not disconnected.
A token can be signed with an access key or with temporary credentials: an assumed role's, or the execution role credentials Floci hands a Lambda function. A token signed with temporary credentials carries their session token in X-Amz-Security-Token, and it is accepted while that session is valid and only with the session token issued alongside the access key.
On RDS, a token is only good for the endpoint it was generated for: the hostname, port and region passed to generate-db-auth-token are the ones the instance (or cluster, or RDS Proxy) publishes. MySQL and MariaDB endpoints in Floci always refuse a token generated for another endpoint. PostgreSQL endpoints do the same by default; set FLOCI_SERVICES_RDS_IAM_TOKEN_ENDPOINT_BINDING=false to accept a token generated for another name, for clients that generate tokens for a container name or DNS alias the endpoint does not publish. Either way, the username must match the DBUser in the token exactly. Because clients on the host reach the same proxy over the loopback interface, a token generated for localhost or 127.0.0.1 on the published port is accepted as well. Clients on a Docker network connect by Floci's container name, so set FLOCI_SERVICES_RDS_ENDPOINT_HOST to that name (see Docker Compose) so it is what the endpoint publishes and tokens are generated for. With IAM enforcement turned on, the token's principal must also be allowed rds-db:connect on the database user, scoped the way AWS scopes it:
arn:aws:rds-db:<region>:<account-id>:dbuser:<DbiResourceId>/<db-user-name>
Aurora cluster endpoints and their member instance endpoints use the cluster's DbClusterResourceId, including after member reboot or runtime recovery, and connections through an RDS Proxy use the proxy's prx-… resource id. A token that fails any of these checks is refused with the engine's ordinary authentication failure; the reason is written to Floci's log.
On native PostgreSQL instance and cluster endpoints, the token names a database
role (DBUser). The role must have its own LOGIN attribute and a direct or indirect grant of rds_iam, including when
logging in as the master user. Standard RDS Proxy client IAM connections do not
require that database IAM grant: the backend role still needs LOGIN, and the
session remains bound to that role's identity. End-to-end DB Proxy IAM is not
supported by the real database mode. Create an application role for a native
database endpoint as the master user:
CREATE ROLE app_user LOGIN;
GRANT rds_iam TO app_user;
On native database endpoints with IAM authentication enabled, membership in
rds_iam makes IAM take
precedence over the role's password. Roles without that membership continue to use
passwords. These database-role checks apply independently of Floci's IAM policy
enforcement setting. Disabling IAM database authentication restores ordinary
password authentication for new connections. Password attempts refused because of that membership report
PAM authentication failed with SQLSTATE 28000.
The IAM session runs as the token's role: current_user and session_user both
report it, and objects it creates belong to it. A missing role or a role without
LOGIN is refused with an authentication failure. Native database endpoints also
require rds_iam membership. Grant the application any additional database
privileges it needs.
Underneath, the proxy reaches the container as the master user and hands the session over to the token's role, so an IAM session that talks its way back to the master role, via RESET SESSION AUTHORIZATION and its variants, is terminated with FATAL: permission denied to set session authorization rather than being allowed to regain superuser. SET ROLE is untouched: PostgreSQL still permission-checks it against the token's role, exactly as on RDS. One difference from RDS: the proxy learns of the switch from PostgreSQL's own report, so when several statements are batched into a single query after the switch, their results are returned before the session is closed.
The parameters a PostgreSQL client sends when it connects (options such as -c search_path=app, application_name, and any other run-time parameter) apply to the session as they do on RDS. An IAM session for a role other than the master gets them once the session has been handed over to the token's role, applied with set_config() so PostgreSQL checks each one against that role's privileges, and a parameter PostgreSQL refuses fails the login with PostgreSQL's own error, as it would at startup. The role's own ALTER ROLE ... SET defaults load as they do at login: the role-wide ones, then those for the database. They are the values RESET returns to, and they apply with the authority of whoever stored them, so a superuser-only default set by an administrator binds the role even after RESET ALL. To get this, a role with defaults has its backend session opened a second time, with the defaults as startup options. A default PostgreSQL refuses is skipped with a WARNING, as at login. A role default is checked against the role's memberships, and a client_encoding default applies unless the client chose an encoding; both are set once the session is the role's, so RESET does not return to them. Defaults stored on the master role itself are not undone for these sessions. A session_authorization naming any other role is refused with permission denied to set session authorization before anything is applied, since PostgreSQL would authorize it against the master the proxy connected as. Because those sessions have already started, three things differ from RDS: options may carry only -c name=value and --name=value switches, a parameter that can only be set at connection start is refused with cannot be set after connection start, and replication connections are refused. 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.
On MySQL, AWSAuthenticationPlugin is proprietary to RDS and ships in no public MySQL build, so
CREATE USER ... IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS' would fail against the container
with ERROR 1524 (HY000): Plugin 'AWSAuthenticationPlugin' is not loaded. The proxy rewrites that
clause to IDENTIFIED WITH mysql_native_password AS '*000...0', an authentication string no
password hashes to. The account is therefore created, can be granted to and can be dropped, but
holds no password of its own, which is what an IAM DB user is: an account whose credentials come
from IAM rather than from MySQL. This is the MySQL counterpart of the empty rds_iam role Floci
pre-creates for PostgreSQL.
Two limits follow from that. SHOW CREATE USER reports the substituted plugin rather than
AWSAuthenticationPlugin, so a Terraform or Pulumi refresh sees drift on auth_plugin. And
connecting with a token is not yet emulated for MySQL: unlike PostgreSQL, which receives the
password in cleartext, MySQL sends a scramble, so the proxy would have to drive the
mysql_clear_password auth switch that real RDS triggers before it could see a token to validate.
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:
RDS proxy TLS: for sslmode=verify-full set PGSSLROOTCERT=./data/tls/floci-root-ca.crt
Because the SAN matches the address you actually connect to, verify-full (the same level
Aurora enforces in AWS) works locally too, without falling back to sslmode=disable just to
exercise the same connection-string settings you use in production:
# PostgreSQL
PGSSLROOTCERT=./data/tls/floci-root-ca.crt psql "host=localhost port=7001 user=admin sslmode=verify-full"
# MySQL / MariaDB
mysql -h 127.0.0.1 -P 7002 -u root -psecret123 \
--ssl-mode=VERIFY_IDENTITY --ssl-ca=./data/tls/floci-root-ca.crt