scylladb-alternator

ScyllaDB Alternator (DynamoDB-Compatible API)

Alternator is ScyllaDB's DynamoDB-compatible API: JSON requests over HTTP/HTTPS, using the same wire protocol and (mostly) the same client SDKs as Amazon DynamoDB. The goal is that an application written for DynamoDB can run against ScyllaDB largely unmodified. It is not a separate database; Alternator tables are ordinary ScyllaDB tables underneath, each in its own keyspace, with the DynamoDB hash/sort key becoming the ScyllaDB partition/clustering key.

When to Use This Skill

• The user is migrating an existing DynamoDB application to ScyllaDB
• The user is using boto3, aws-sdk-java, or another AWS SDK client, with a custom endpoint_url pointed at a ScyllaDB cluster
• The user asks about alternator_port, alternator_write_isolation, or DynamoDB-style table creation against ScyllaDB
• The user needs to know what does or doesn't carry over from real DynamoDB behavior

For schema design guidance once data is in ScyllaDB (partition keys, clustering, anti-patterns), defer to the scylladb-data-modeling skill — Alternator tables are still subject to the same partition-key and hot-partition considerations underneath the DynamoDB-shaped API.

Enabling Alternator

Alternator is off by default. Two configuration options are required, and there is no default for the second one — starting ScyllaDB with alternator_port set but without alternator_write_isolation will fail with an explicit error:

alternator_port: 8000
alternator_write_isolation: only_rmw_uses_lwt   # or: always, forbid, unsafe

Equivalently, as command-line flags: --alternator-port=8000 --alternator-write-isolation=only_rmw_uses_lwt.

See references/write-isolation-policies.md for what each of the four policy values actually does and which to recommend.

For local testing (Docker):

docker run --name scylla -d -p 8000:8000 scylladb/scylla:latest \
  --alternator-port=8000 --alternator-write-isolation=always

By default this has no authentication enabled; any signed or unsigned request is honored. Do not leave a cluster this way outside of local testing — see references/connecting-and-load-balancing.md for real authentication and load-balancing setup.