Skip to content

Compatibility

fdyno accepts AWS SDK and CLI requests over the DynamoDB JSON protocol. This page describes implemented behavior, narrower API semantics, and features that are not included. An action route alone does not imply complete DynamoDB parity. Test the exact requests your application uses.

The detailed code-and-test trace for this page is in the capability evidence memo.

Supported scope

A capability is classified as:

  • Supported: the operation performs its database effect and has black-box test coverage through a DynamoDB client.
  • Partial: the request target exists, but fdyno implements a narrower language, different semantics, or metadata only.
  • Unsupported: fdyno does not perform the advertised AWS workflow. Some such targets validate the request and return a configured error rather than UnknownOperationException.

Supported operations use AWS JSON request and response shapes, SigV4-authenticated SDK access, DynamoDB attribute values, validation errors, conditions, and tested pagination behavior. This does not include AWS infrastructure such as accounts, IAM, KMS, Regions, S3, Kinesis, CloudWatch, or Application Auto Scaling.

The same endpoint works with boto3, the AWS CLI, and AWS SDKs. Configure an endpoint, Region, and credentials as shown in the Quickstart; fdyno verifies the SigV4 signature even for local requests.

Implemented workflows

Tables and secondary indexes

Workflow Actions and behavior
Table lifecycle CreateTable, DescribeTable, UpdateTable, DeleteTable, and ListTables
Table settings Billing-mode and throughput metadata, table class, deletion protection, and stream configuration
Secondary indexes GSI and LSI creation, projections (ALL, KEYS_ONLY, INCLUDE), index Query/Scan, and GSI add/delete through UpdateTable
Online GSI creation Existing items are backfilled in bounded transactions; live writes maintain an index while it is being created

GSI and LSI entries commit with the base item. They cannot lag a successful write. This is stronger than DynamoDB's GSI consistency; see Differences from DynamoDB.

Items, expressions, queries, and scans

Workflow Actions and behavior
Item access GetItem, PutItem, UpdateItem, and DeleteItem, including conditions, return-value modes, and return values on condition failure
Expressions Condition, filter, projection, and update expressions; nested map/list paths; expression names and values
Update forms SET, REMOVE, ADD, and DELETE, including if_not_exists, list_append, and arithmetic
Read access patterns Query with sort-key operators and forward/reverse order; Scan with parallel segments
Result control Limit, ExclusiveStartKey / LastEvaluatedKey, filters, projections, Select, and consumed-capacity response shapes
Legacy request forms Expected, AttributeUpdates, KeyConditions, QueryFilter, ScanFilter, and AttributesToGet

All DynamoDB attribute types are encoded, including nested maps/lists and string, number, and binary sets. Numeric values remain decimal strings, and numeric key order is implemented without converting the full value through float64.

The tested parenthesized SET arithmetic form is one balanced pair around a path and numeric placeholder, such as SET c = (c - :v); this is not general nested-function or chained-expression support. See the selected conformance coverage.

Batch and transactional work

Workflow Actions and behavior
Batch reads and writes BatchGetItem and BatchWriteItem, including multi-table requests and unprocessed-result shapes
Transactional reads TransactGetItems, with projection and consumed-capacity responses
Transactional writes TransactWriteItems with Put, Update, Delete, and ConditionCheck, cancellation reasons, and condition-failure items
Retry deduplication A ClientRequestToken is persisted atomically with TransactWriteItems; replay and mismatch behavior survives process restart and works across fdyno instances

TransactWriteItems is the supported way to make writes to multiple items or tables atomic. BatchWriteItem is non-transactional, as it is in DynamoDB; callers must retry entries returned in UnprocessedItems.

A minimal transactional write uses the normal boto3 client:

client.transact_write_items(
    ClientRequestToken="order-018f6b8d",
    TransactItems=[
        {
            "Put": {
                "TableName": "Orders",
                "Item": {
                    "pk": {"S": "order-42"},
                    "status": {"S": "created"},
                },
                "ConditionExpression": "attribute_not_exists(pk)",
            }
        }
    ],
)

Persist the token before the first submission and reuse it for retries. See Reliable writes & idempotency.

PartiQL

ExecuteStatement, BatchExecuteStatement, and ExecuteTransaction are available for the implemented PartiQL subset:

  • SELECT, INSERT, UPDATE, and DELETE;
  • positional ? parameters;
  • key and non-key WHERE conditions, nested paths, projections, and pagination;
  • transactional statement execution and batch per-statement errors.

This is a purpose-built parser, not the complete PartiQL specification. Treat syntax outside the forms exercised by fdyno's PartiQL tests as partial, and test the exact statements your application uses.

For example, against the table created in the Quickstart:

aws dynamodb execute-statement \
  --endpoint-url http://127.0.0.1:8000 \
  --statement 'SELECT * FROM "quickstart-users" WHERE "id" = ?' \
  --parameters '[{"S":"user-1"}]'

Streams, TTL, and local backup

Workflow Status Behavior
DynamoDB Streams Supported with topology differences ListStreams, DescribeStream, GetShardIterator, and GetRecords; all stream view and iterator types; records commit with item mutations
TTL configuration and expiry Partial UpdateTimeToLive and DescribeTimeToLive; GetItem, BatchGetItem, Query, and Scan hide expired items; a bounded sweeper runs by default at 1m. On stream-enabled tables, GetItem can trigger an atomic expiry delete with a REMOVE record; otherwise cleanup awaits the sweeper.
On-demand backup Supported with scale boundary CreateBackup, ListBackups, DescribeBackup, DeleteBackup, and RestoreTableFromBackup; backups are consistent snapshots stored in FoundationDB
PITR API Unsupported, explicit DescribeContinuousBackups reports disabled; enablement and restore return unavailable errors rather than substituting current state for history

A backup stored in the same FoundationDB cluster is useful for table-level copy and restore, but it is not an independent disaster-recovery copy. Use FoundationDB-native backup tooling for cluster disaster recovery. See Backup & restore and Durability & recovery.

Metadata workflows

Tags (TagResource, UntagResource, ListTagsOfResource) are persisted and supported. Resource-policy documents can be put, read, deleted, and revision-checked, but they are not enforced for authorization; therefore resource policies are partial as a security capability.

DescribeEndpoints is available for SDK endpoint discovery. DescribeLimits and consumed-capacity fields provide compatible response shapes, not an enforced AWS capacity model. Ten selected ExtendDB cases check only CapacityUnits presence and absence of granular read/write fields for four single-item actions at TOTAL/ INDEXES and batch Get/Write at TOTAL. They do not validate numeric charges, index accounting, other APIs, or other AWS Regions.

Differences from DynamoDB

Area fdyno behavior Effect for callers
Read consistency Reads use current FoundationDB snapshots even when ConsistentRead is omitted. Applications do not observe DynamoDB-style eventually consistent base-table reads.
GSI consistency Writes to a registered index commit atomically with the base item. ConsistentRead=true on a GSI remains invalid for DynamoDB request compatibility. An ACTIVE index has no asynchronous post-write propagation wait; a new GSI still needs backfill and must reach ACTIVE before use.
Capacity Provisioned/on-demand values are metadata; fdyno reports capacity but does not enforce request units or throttle. Do not use throttling or consumed-capacity totals as admission control, billing, or scaling signals.
Transactions Data, index entries, stream records, and transaction idempotency state share FoundationDB transactions. Atomic workflows are supported, but must fit DynamoDB request limits and FoundationDB's transaction limits.
TTL GetItem, BatchGetItem, Query, and Scan filter expired items; the bounded sweeper starts by default and can be disabled explicitly. TransactGetItems and reviewed PartiQL reads do not apply the same filter. Test each read API; monitor the sweeper and do not rely on physical deletion time for correctness.
PITR DescribeContinuousBackups reports DISABLED; enablement and restore return unavailable errors. Historical recovery is unsupported. Use tested on-demand or FoundationDB-native backups.
Streams The default is one static shard per table; an opt-in fixed shard count hash-partitions by partition key. There is no dynamic split or parent/child lineage. Consumers that require DynamoDB shard-lineage processing need adaptation.
Authentication SigV4 signatures are checked against configured static credentials. There is no account, IAM, STS, ABAC, or policy authorizer. Put fdyno behind a trusted network/authentication boundary; a valid key can access every table.
Resource ARNs Resources use a local, single-tenant ARN convention. Cross-account authorization and account-isolation error behavior are not reproduced.
Encryption fdyno has no DynamoDB SSESpecification / KMS implementation. Configure encryption in FoundationDB and the surrounding infrastructure.

For the formal consistency boundary, including page-by-page reads, see Consistency model.

Metadata-only and unsupported integrations

A successful metadata update is not proof that an external AWS integration exists. The following targets are limited:

API area Classification fdyno behavior
Kinesis streaming destination Partial Destination ARN, status, and precision metadata are stored; no records are delivered to Kinesis.
Contributor Insights Partial Enable/disable and mode metadata are stored; no access-pattern analysis or rules are generated.
Replica auto scaling Partial Describe/update return a single-region table description; no scaling policy is applied.
Global tables Unsupported List returns no memberships; create/update/describe paths validate and then return not-configured or not-found errors.
S3 export/import Unsupported List returns no jobs; export/import validate requests and then return a not-configured error. No S3 data transfer occurs.
Resource-policy authorization Unsupported Policy documents are stored, but requests are never allowed or denied from those documents.
IAM, STS, ABAC, cross-account isolation Unsupported There is no identity or account model beyond the configured SigV4 key/secret map.
KMS-backed server-side encryption Unsupported Encryption is delegated to the FoundationDB deployment.
Dynamic stream shard splitting Unsupported Each enabled generation stores one fixed shard count in table metadata.
Historical PITR Unsupported No historical change replay exists behind RestoreTableToPointInTime.
DAX, AWS management console, CloudWatch integrations Unsupported These AWS product surfaces are outside fdyno.

Request and storage limits

These are request or storage boundaries, not performance claims:

Boundary Current behavior
Item size Items larger than 400 KiB are rejected.
Key size Partition-key values are limited to 2,048 bytes and sort-key values to 1,024 bytes.
Nested value A leaf may be at level 32. A value at level 33 is rejected before mutation evaluation, including in ExpressionAttributeValues.
Expression string The raw text of a single tested expression is accepted at 4,096 bytes and rejected at 4,097; expanded aliases do not count. Exact over-limit suffixes differ by expression label in the recorded us-east-1 case, not proven uniform across Regions.
Query/Scan page A response page is bounded at approximately 1 MiB before pagination.
Batch request BatchGetItem accepts at most 100 keys; BatchWriteItem accepts at most 25 writes.
Transaction request Transaction APIs accept at most 100 actions; TransactWriteItems rejects a put payload over 4 MiB.
HTTP body Raw and decompressed request bodies are capped at 16 MiB.
FoundationDB transaction A single atomic operation must also fit FoundationDB's transaction limits after index and stream writes are included. Oversized transactional work is rejected; non-atomic batch writes may be split and report unprocessed work.

The implementation constants and conformance cases behind each value are listed in the evidence memo.

A value with a leaf beyond nesting level 32 is rejected before mutation evaluation, including in ExpressionAttributeValues. Exact error text can differ across AWS Regions; fdyno's accepted boundary is described above.

Conformance coverage

The selected Alternator, nubo-db, and ExtendDB suites send black-box requests to a running fdyno server. They exercise supported cases with explicit skips, deselections, and expected failures. Passing that selection does not mean every upstream test or AWS behavior is included. Read Conformance testing for the selected-case inventory and Limits for request-specific boundaries. The private evidence memo maps implemented behavior to code and representative tests.