
I Tried Out ExtendDB 1.0, Which Replicates the DynamoDB API
This page has been translated by machine translation. View original
Introduction
ExtendDB 1.0 was released on November 18, 2026.
ExtendDB is a server that reproduces the DynamoDB API and runs on top of a database that you provide, such as PostgreSQL or SQLite. Applications connect to it through the endpoint setting of the AWS SDK or AWS CLI.
In this article, I ran the dev image, @extenddb/dev, and the PostgreSQL configuration, and sent the same operations to the real DynamoDB to compare the responses.
Backends and Tiers
Version 1.0 has 4 backends, each classified as Stable, Beta, or Experimental. The dev image and @extenddb/dev are SQLite builds in dev mode.
| Backend | Tier | Backend image | This article |
|---|---|---|---|
| PostgreSQL | Stable | extenddb-postgres | Ran it |
| SQLite | Stable (single node) | None (build from source) | Ran it (dev image, npm) |
| MongoDB | Beta | extenddb-mongodb | Did not run it |
| Cassandra | Experimental | extenddb-cassandra | Did not run it |
Test Environment
I ran the tests on an arm64 Linux host.
| Item | Details |
|---|---|
| Host | Linux (arm64) |
| Docker / Compose | 29.9.3 / v5.7.0 |
| AWS CLI | 2.41.0 |
| ExtendDB | 1.0.0 (dev image 148MB, postgres image 389MB) |
| Node.js | 22.23.3 (inside a node:22 container; @extenddb/linux-arm64 was installed) |
| @extenddb/dev / @aws-sdk/client-dynamodb | 1.0.0 / 3.1172.0 |
| Real DynamoDB | us-east-1, on-demand |
dev Image
A single container running on SQLite. It needs neither an external database nor initialization with extenddb init; once started, you can use it from the AWS CLI.
Startup and Basic Operations
docker run -d --name extenddb-verify-dev -p 127.0.0.1:18080:18080 -v extenddb-verify:/var/lib/extenddb extenddb/extenddb-dev:1.0.0
5 seconds after startup, I confirmed healthy with docker ps. I limited the published address on the host side to 127.0.0.1. This is because dev mode uses plain HTTP, and anyone who signs with the sample keys published by AWS can operate on all tables.
For AWS CLI authentication, I use the sample keys listed in the AWS documentation.
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
I created an on-demand table with a GSI.
aws dynamodb --region us-east-1 --endpoint-url http://127.0.0.1:18080 create-table --table-name extenddb-verify-t1 \
--attribute-definitions AttributeName=pk,AttributeType=S AttributeName=sk,AttributeType=S AttributeName=gsi1pk,AttributeType=S \
--key-schema AttributeName=pk,KeyType=HASH AttributeName=sk,KeyType=RANGE \
--billing-mode PAY_PER_REQUEST \
--global-secondary-indexes 'IndexName=gsi1,KeySchema=[{AttributeName=gsi1pk,KeyType=HASH}],Projection={ProjectionType=ALL}'
After waiting for the table to become ACTIVE, I wrote an item with put-item and read it back with a strongly consistent get-item.
aws dynamodb --region us-east-1 --endpoint-url http://127.0.0.1:18080 wait table-exists --table-name extenddb-verify-t1
aws dynamodb --region us-east-1 --endpoint-url http://127.0.0.1:18080 put-item --table-name extenddb-verify-t1 --item '{"pk":{"S":"user#1"},"sk":{"S":"profile"},"name":{"S":"alice"},"age":{"N":"30"},"gsi1pk":{"S":"team#a"}}'
aws dynamodb --region us-east-1 --endpoint-url http://127.0.0.1:18080 get-item --table-name extenddb-verify-t1 --consistent-read --key '{"pk":{"S":"user#1"},"sk":{"S":"profile"}}'
{
"Item": {
"age": {
"N": "30"
},
"gsi1pk": {
"S": "team#a"
},
"name": {
"S": "alice"
},
"pk": {
"S": "user#1"
},
"sk": {
"S": "profile"
}
}
}
As material for deciding the expected values in tests, I also checked failure responses. When I wrote to the same key twice with the condition attribute_not_exists(pk), the second write produced the following error.
aws dynamodb --region us-east-1 --endpoint-url http://127.0.0.1:18080 put-item --table-name extenddb-verify-t1 \
--condition-expression 'attribute_not_exists(pk)' \
--item '{"pk":{"S":"lock#1"},"sk":{"S":"x"},"owner":{"S":"a"}}'
aws dynamodb --region us-east-1 --endpoint-url http://127.0.0.1:18080 put-item --table-name extenddb-verify-t1 \
--condition-expression 'attribute_not_exists(pk)' \
--return-values-on-condition-check-failure ALL_OLD \
--item '{"pk":{"S":"lock#1"},"sk":{"S":"x"},"owner":{"S":"b"}}'
aws: [ERROR]: An error occurred (ConditionalCheckFailedException) when calling the PutItem operation: The conditional request failed
I also checked a transaction failure. First, in a separate transaction, I wrote 2 items for tx#1 (the item whose sk is a has v = 1). Then I sent, in a single transaction, a Put for tx#2 and a ConditionCheck on the tx#1 item whose sk is a (condition: v = 99). The second ConditionCheck failed, and the whole transaction was cancelled. The cancellation reasons are listed in operation order, and the first Put is None.
aws dynamodb --region us-east-1 --endpoint-url http://127.0.0.1:18080 transact-write-items --transact-items '[
{"Put":{"TableName":"extenddb-verify-t1","Item":{"pk":{"S":"tx#1"},"sk":{"S":"a"},"v":{"N":"1"}}}},
{"Put":{"TableName":"extenddb-verify-t1","Item":{"pk":{"S":"tx#1"},"sk":{"S":"b"},"v":{"N":"2"}}}}]'
aws dynamodb --region us-east-1 --endpoint-url http://127.0.0.1:18080 transact-write-items --transact-items '[
{"Put":{"TableName":"extenddb-verify-t1","Item":{"pk":{"S":"tx#2"},"sk":{"S":"a"},"v":{"N":"1"}}}},
{"ConditionCheck":{"TableName":"extenddb-verify-t1","Key":{"pk":{"S":"tx#1"},"sk":{"S":"a"}},"ConditionExpression":"v = :bad","ExpressionAttributeValues":{":bad":{"N":"99"}}}}]'
aws: [ERROR]: An error occurred (TransactionCanceledException) when calling the TransactWriteItems operation: Transaction cancelled, please refer cancellation reasons for specific reasons [None, ConditionalCheckFailed]
Storage Modes
The database is placed at /var/lib/extenddb/extenddb.sqlite. In the startup command in the previous section, -v mounts a named volume at /var/lib/extenddb. I also tried the case without a volume and the case where :memory: is specified as follows.
docker run -d --name extenddb-verify-persist -p 127.0.0.1:18082:18080 -e EXTENDDB__STORAGE__SQLITE__PATH=:memory: extenddb/extenddb-dev:1.0.0
For each condition, I created a table and an item, operated on the container, and then checked with list-tables and get-item whether the data remained.
| Startup condition | Operation on the container | After the operation |
|---|---|---|
| Named volume | Delete and recreate with the same volume | Remained |
| No volume specified | docker restart | Remained |
| No volume specified | Delete with docker rm -fv and recreate | Gone |
| :memory: | docker restart | Gone |
When you want your local data to survive recreating the container, pass a named volume; when you want CI to start from an empty state every time, specify :memory:.
Disabling the Sample Keys
In environments that can be reached from other machines, such as a shared build machine, disable the published sample keys and provide your own keys. The switch to disable them (the environment variable EXTENDDB_DEV_DISABLE_EXAMPLE_CREDENTIAL) must be specified together with your own keys. I set my own keys in the host environment variables EXTENDDB_DEV_ACCESS_KEY_ID and EXTENDDB_DEV_SECRET_ACCESS_KEY, and then ran the following command.
docker run -d --name extenddb-verify-auth -p 127.0.0.1:18081:18080 \
-e EXTENDDB_DEV_DISABLE_EXAMPLE_CREDENTIAL=1 \
-e EXTENDDB_DEV_ACCESS_KEY_ID \
-e EXTENDDB_DEV_SECRET_ACCESS_KEY \
extenddb/extenddb-dev:1.0.0
| Condition | Result |
|---|---|
| Signed with the sample keys | UnrecognizedClientException |
| Signed with my own keys | Success (list-tables returned an empty list) |
| Specify only the switch and start without my own keys | Exited without starting (no replacement keys set) |
| Add only my own keys without the switch | Both the sample keys and my own keys are accepted |
@extenddb/dev
A package that starts a DynamoDB-compatible server from Node.js with a single function call.
Using start()
npm install @extenddb/dev @aws-sdk/client-dynamodb
The README quickstart.
// quickstart.mjs -- run with: node quickstart.mjs
import { start } from "@extenddb/dev";
import { DynamoDBClient, ListTablesCommand } from "@aws-sdk/client-dynamodb";
const server = await start({ memory: true });
// server.credentials -> { accessKeyId, secretAccessKey }
// server.region -> "us-east-1"
const client = new DynamoDBClient({
endpoint: server.endpoint,
region: server.region,
credentials: server.credentials,
});
await client.send(new ListTablesCommand({}));
await server.stop();
I wrote a test using the same calls as the README and ran CreateTable, PutItem, and GetItem in addition to ListTables. start() resolved in 334 ms and stop() in 9 ms (both values are from a single run). The accessKeyId in server.credentials was the same sample key as in the dev image.
You specify the storage location and port as follows.
await start({ storage: "file", dbPath });
await start({ memory: true, port: 18099 });
Pass the path of a SQLite file as dbPath. I created the directory that holds the file in advance. In file mode, when I started again with the same dbPath after stop(), the table remained. In memory mode, it did not.
Integrating into a Test Suite
This is the README's Vitest example, rewritten with the credential extraction separated out. I did not run this example itself.
Vitest globalSetup example (partially rewritten from the README)
// globalSetup.mjs
import { start } from "@extenddb/dev";
export default async function () {
const server = await start({ memory: true });
const { accessKeyId, secretAccessKey } = server.credentials;
process.env.DDB_ENDPOINT = server.endpoint;
process.env.AWS_ACCESS_KEY_ID = accessKeyId;
process.env.AWS_SECRET_ACCESS_KEY = secretAccessKey;
process.env.AWS_REGION = server.region;
return () => server.stop();
}
PostgreSQL Configuration
The production image extenddb-postgres contains only ExtendDB, and PostgreSQL runs as a separate service. Here I used the docker-compose.yml at the repository tag v1.0.0. The repository states that this file is for local development only, and the default passwords are values published for development.
Startup
Run it in the directory containing docker-compose.yml. The default image name in compose is extenddb-postgres:dev. To use the published image, specify the image with the environment variable EXTENDDB_IMAGE.
EXTENDDB_IMAGE=extenddb/extenddb-postgres:1.0.0 docker compose up -d
Compose publishes the extenddb port only on 127.0.0.1. The extenddb-bootstrap service runs extenddb init, and after that the extenddb service starts. Both the postgres and extenddb services became healthy.
curl -sk https://127.0.0.1:18443/health
{"components":{},"status":"healthy"}
Creating an Access Key and Connecting
Unlike the dev image, authentication does not succeed with the sample keys. You create an IAM user and an access key, and make the AWS CLI trust the TLS self-signed certificate as a CA bundle. Management operations are done by calling extenddb manage inside the container with docker compose exec. For the admin password, I used the compose default. Because I passed the password with --password, a warning appeared every time I ran manage. It said to use the environment variable EXTENDDB_PASSWORD instead, since the password is visible from the process list and shell history.
export EXTENDDB_IMAGE=extenddb/extenddb-postgres:1.0.0
ADMIN_PW='<docker-compose.yml の EXTENDDB_ADMIN_PASSWORD の既定値>'
# Extract the self-signed certificate
docker compose exec -T extenddb cat /var/lib/extenddb/.extenddb/tls/cert.pem > /tmp/extenddb-cert.pem
M() { docker compose exec -T extenddb extenddb manage --user admin --password "$ADMIN_PW" "$@"; }
# Get the account ID (12 digits)
ACCT=$(M list-accounts 2>/dev/null | grep -oE '[0-9]{12}' | head -1)
M create-user --account-id "$ACCT" --user-name verifyuser
M put-user-policy --account-id "$ACCT" --user-name verifyuser --policy-name full-access \
--policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Action":"dynamodb:*","Resource":"*"}]}'
M create-access-key --account-id "$ACCT" --user-name verifyuser > /tmp/pg-verify.key.out
The output of create-access-key is JSON containing access_key_id and secret_access_key.
export AWS_ACCESS_KEY_ID=$(jq -r .access_key_id /tmp/pg-verify.key.out)
export AWS_SECRET_ACCESS_KEY=$(jq -r .secret_access_key /tmp/pg-verify.key.out)
export AWS_CA_BUNDLE=/tmp/extenddb-cert.pem
aws dynamodb list-tables --region us-east-1 --endpoint-url https://127.0.0.1:18443
When you are done, delete /tmp/pg-verify.key.out and /tmp/extenddb-cert.pem, and unset AWS_CA_BUNDLE and the two key environment variables.
| Connection method | Result |
|---|---|
| Own keys, no CA bundle | Self-signed certificate verification error (CERTIFICATE_VERIFY_FAILED) |
| Sample keys, with CA bundle | UnrecognizedClientException |
| Own keys, with CA bundle | Success (list-tables returned an empty list) |
Comparison with SQLite
I prepared 2 scripts. One has 24 commands for basic operations, and the other has operations where differences are likely to appear, such as TTL, item size, and Streams. I ran both scripts against both the dev image (SQLite) and the PostgreSQL configuration. I compared the responses while ignoring timestamps, IDs, and key order. The 12-digit account ID that appears in ARNs is assigned per installation, so I excluded it from the matching. The responses other than ARNs matched. The time until a table with a GSI and a stream became ACTIVE was 1,410 ms on SQLite and 1,987 ms on PostgreSQL.
Response Comparison with DynamoDB
I sent the same operations to ExtendDB (SQLite) and the real DynamoDB. The real DynamoDB was on-demand in us-east-1, with 2 tables, and each operation was run once.
Operations That Matched
Of the 24 basic-operation commands, 22 returned the same responses as the real DynamoDB. The remaining 2 commands are create-table and the batch-write-item that writes 26 items, both in the "Operations That Differed" table below. The failure of a conditional write and the transaction cancellation reasons [None, ConditionalCheckFailed] were the same. The error for a scan using a reserved word, get-item on a nonexistent table, a key type mismatch, and the result of update-item were also the same.
In the script of operations where differences are likely to appear, the following operations matched. An item of about 401KB was rejected, and an item of about 390KB succeeded (ConsumedCapacity was 391.0). For a table with a GSI (projection ALL), ConsumedCapacity was 2.0 for put-item, 1.0 for a strongly consistent get-item, and 0.5 for query. A strongly consistent read on the GSI was rejected, and PartiQL INSERT, SELECT, UPDATE, and DELETE went through. For Streams (StreamViewType was NEW_AND_OLD_IMAGES), 8 records (4 INSERT, 2 MODIFY, 2 REMOVE) matched on both sides.
Operations That Differed
Among the operations that could be compared under the same conditions, these are the ones whose responses differed.
| Operation | ExtendDB (SQLite) | Real DynamoDB |
|---|---|---|
| Response right after creating an on-demand table | The GSI's IndexStatus is ACTIVE. BillingModeSummary has LastUpdateToPayPerRequestDateTime | The GSI's IndexStatus is CREATING. BillingModeSummary has only BillingMode |
| batch-write-item writing 26 items | ValidationException. The message points to the whole requestItems map and lists 2 constraints: length at most 25 and at least 1 | ValidationException. The message points to RequestItems.extenddb-verify-t1.member and lists the constraint of length at most 25 |
| create-table with duplicate tag keys | InternalServerError (the CLI retried 3 times and exited) | ValidationException (Duplicate Tag Keys provided as input) |
| Time until a table with a GSI and a stream becomes ACTIVE | 1,410 ms | 16,409 ms |
| Disabling TTL right after enabling it | Succeeded | ValidationException (Time to live has been modified multiple times within a fixed interval) |
| delete-table on a nonexistent table | ResourceNotFoundException (Requested resource not found) | ResourceNotFoundException (Requested resource not found, with the table name) |
The time until ACTIVE is the time from calling create-table until ACTIVE is confirmed by repeating describe-table (launching the CLI each time) and a 0.25-second wait. Each was measured once.
For the operations in this run, tests that check the following points would have produced different results on ExtendDB and the real DynamoDB.
- The error type of create-table with duplicate tag keys
- The error messages of the 26-item batch-write-item and of delete-table on a nonexistent table
- The behavior when switching TTL in succession
- The state of a GSI right after creation
Items That Could Not Be Compared with the Real DynamoDB
The "Documentation" column in the table is from the following differences document.
| Item | Documentation | ExtendDB response | Real DynamoDB |
|---|---|---|---|
| A TTL attribute name containing a space | Attribute names are restricted to [a-zA-Z0-9._-]+ |
ValidationException (TimeToLiveSpecification.AttributeName contains invalid characters) | The preceding disable was rejected and TTL remained enabled on ttl, so it was rejected with TimeToLive is active on a different AttributeName. Could not be compared under the same conditions |
| ListGlobalTables | Global tables are not implemented | UnknownOperationException | Not sent |
Summary
The ExtendDB 1.0 dev image could be used from the AWS CLI, and @extenddb/dev from SDK v3, without an external database. Most of the operations I ran returned the same responses as the real DynamoDB, and the responses of the PostgreSQL configuration were the same as those of SQLite.
On November 11, 2026, AWS Emulator, a local emulator from AWS, was also announced. If AWS Emulator cannot reproduce what you need and you need a local test environment closer to DynamoDB, please make use of ExtendDB after understanding the scope of what it reproduces.
