
DynamoDB の API を再現する ExtendDB 1.0 を試してみた
はじめに
2026 年 11 月 18 日に ExtendDB 1.0 が公開されました。
ExtendDB は、DynamoDB の API を再現したサーバーで、PostgreSQL や SQLite など利用者が用意したデータベースの上で動きます。アプリケーションからは、AWS SDK や AWS CLI の endpoint 設定で接続します。
この記事では、dev イメージ、@extenddb/dev、PostgreSQL 構成を動かし、同じ操作を実際の DynamoDB にも流して応答を比べました。
バックエンドと区分
1.0 のバックエンドは 4 種類あり、それぞれ Stable、Beta、Experimental のいずれかに区分されています。dev イメージと @extenddb/dev は、dev モードの SQLite ビルドです。
| バックエンド | 区分 | バックエンド用イメージ | この記事 |
|---|---|---|---|
| PostgreSQL | Stable | extenddb-postgres | 動かした |
| SQLite | Stable(単一ノード) | なし(ソースからビルド) | 動かした(dev イメージ、npm) |
| MongoDB | Beta | extenddb-mongodb | 動かしていない |
| Cassandra | Experimental | extenddb-cassandra | 動かしていない |
検証環境
検証は arm64 の Linux ホストで行いました。
| 項目 | 内容 |
|---|---|
| ホスト | Linux(arm64) |
| Docker / Compose | 29.9.3 / v5.7.0 |
| AWS CLI | 2.41.0 |
| ExtendDB | 1.0.0(dev イメージ 148MB、postgres イメージ 389MB) |
| Node.js | 22.23.3(node:22 コンテナ内。@extenddb/linux-arm64 が入った) |
| @extenddb/dev / @aws-sdk/client-dynamodb | 1.0.0 / 3.1172.0 |
| 実際の DynamoDB | us-east-1、オンデマンド |
dev イメージ
SQLite 上で動く単一コンテナです。外部データベースと extenddb init による初期化は不要で、起動すれば AWS CLI から使えます。
起動と基本操作
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 秒後に docker ps で healthy を確認しました。ホスト側の公開先は 127.0.0.1 に限っています。dev モードは平文 HTTP で、AWS が公開しているサンプルキーで署名すれば全テーブルを操作できるためです。
AWS CLI の認証には、AWS のドキュメントに載っているサンプルキーを使います。
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
オンデマンドで 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}'
テーブルが ACTIVE になるのを待ってから put-item で項目を書き込み、強い整合性の 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"
}
}
}
テストの期待値を決める材料として、失敗の応答も確かめました。同じキーへ attribute_not_exists(pk) の条件付きで 2 回書くと、2 回目が次のエラーになりました。
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
トランザクションの失敗も確かめました。先に別のトランザクションで tx#1 の項目を 2 件書いておきました(sk が a の項目は v が 1)。その後、tx#2 の Put と、tx#1 の sk が a の項目に対する ConditionCheck(条件は v = 99)を 1 つのトランザクションで送りました。2 件目の ConditionCheck が失敗し、全体が取り消されました。取り消し理由は操作の順に並び、1 件目の Put は 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]
保存モード
データベースは /var/lib/extenddb/extenddb.sqlite に置かれます。前節の起動コマンドでは、-v で名前付きボリュームを /var/lib/extenddb にマウントしています。ボリュームを指定しない場合と、次のように :memory: を指定した場合も試しました。
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
各条件でテーブルと項目を作り、コンテナを操作した後に list-tables と get-item でデータが残っているか確かめました。
| 起動条件 | コンテナへの操作 | 操作後 |
|---|---|---|
| 名前付きボリューム | 削除して同じボリュームで再作成 | 残った |
| ボリューム指定なし | docker restart | 残った |
| ボリューム指定なし | docker rm -fv で削除して再作成 | 消えた |
| :memory: | docker restart | 消えた |
手元のデータをコンテナの作り直し後も残したいときは名前付きボリュームを渡し、CI で毎回空の状態から始めたいときは :memory: を指定します。
サンプルキーの無効化
共有のビルドマシンのように他のマシンから接続できる環境では、公開済みのサンプルキーを無効化し、自前のキーを渡します。無効化のスイッチ(環境変数 EXTENDDB_DEV_DISABLE_EXAMPLE_CREDENTIAL)は、自前のキーと一緒に指定します。ホストの環境変数 EXTENDDB_DEV_ACCESS_KEY_ID と EXTENDDB_DEV_SECRET_ACCESS_KEY に自前のキーを設定してから、次のコマンドを実行しました。
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
| 条件 | 結果 |
|---|---|
| サンプルキーで署名 | UnrecognizedClientException |
| 自前キーで署名 | 成功(list-tables が空の一覧を返した) |
| スイッチだけを指定し、自前キーなしで起動 | 起動せず終了(代わりのキーが未設定) |
| スイッチなしで自前キーだけを追加 | サンプルキーも自前キーも通る |
@extenddb/dev
Node.js から 1 回の関数呼び出しで、DynamoDB 互換のサーバーを起動するパッケージです。
start() の使い方
npm install @extenddb/dev @aws-sdk/client-dynamodb
README のクイックスタートです。
// 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();
README と同じ呼び出しでテストを書き、ListTables のほか CreateTable、PutItem、GetItem を実行しました。start() は 334 ms、stop() は 9 ms で解決しました(いずれも 1 回の実行の値です)。server.credentials の accessKeyId は dev イメージと同じサンプルキーでした。
保存先とポートは、次のように指定します。
await start({ storage: "file", dbPath });
await start({ memory: true, port: 18099 });
dbPath には SQLite ファイルのパスを渡します。ファイルを置くディレクトリは、事前に作っておきました。file モードでは、stop() の後に同じ dbPath で再度起動するとテーブルが残っていました。memory モードでは残りませんでした。
テストスイートへの組み込み
README にある Vitest の例を、認証情報の取り出しを分けて書き直したものです。この例そのものは実行していません。
Vitest の globalSetup の例(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 構成
本番用イメージ extenddb-postgres は ExtendDB だけを含み、PostgreSQL は別のサービスとして動かします。ここでは、リポジトリのタグ v1.0.0 にある docker-compose.yml を使いました。リポジトリはこのファイルをローカル開発専用と記しており、パスワードの既定値は開発用に公開された値です。
起動
docker-compose.yml のあるディレクトリで実行します。compose の既定のイメージ名は extenddb-postgres:dev です。公開イメージを使うため、環境変数 EXTENDDB_IMAGE でイメージを指定します。
EXTENDDB_IMAGE=extenddb/extenddb-postgres:1.0.0 docker compose up -d
compose は extenddb のポートを 127.0.0.1 にだけ公開します。extenddb-bootstrap サービスが extenddb init を実行し、その後に extenddb サービスが起動します。postgres と extenddb の両サービスが healthy になりました。
curl -sk https://127.0.0.1:18443/health
{"components":{},"status":"healthy"}
アクセスキーの作成と接続
dev イメージと違い、サンプルキーでは認証が通りません。IAM ユーザーとアクセスキーを作り、TLS の自己署名証明書を CA バンドルとして AWS CLI に信頼させます。管理操作は、コンテナ内の extenddb manage を docker compose exec で呼び出します。管理者のパスワードには、compose の既定値を使いました。--password でパスワードを渡したため、manage を実行するたびに警告が出ました。パスワードがプロセス一覧やシェル履歴から見えるので、環境変数 EXTENDDB_PASSWORD を使うように、という内容です。
export EXTENDDB_IMAGE=extenddb/extenddb-postgres:1.0.0
ADMIN_PW='<docker-compose.yml の EXTENDDB_ADMIN_PASSWORD の既定値>'
# 自己署名証明書を取り出す
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" "$@"; }
# アカウント ID(12 桁)を取得する
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
create-access-key の出力は、access_key_id と secret_access_key を持つ JSON です。
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
使い終わったら、/tmp/pg-verify.key.out と /tmp/extenddb-cert.pem を削除し、AWS_CA_BUNDLE と 2 つのキーの環境変数を unset します。
| 接続方法 | 結果 |
|---|---|
| 自前キー、CA バンドルなし | 自己署名証明書の検証エラー(CERTIFICATE_VERIFY_FAILED) |
| サンプルキー、CA バンドルあり | UnrecognizedClientException |
| 自前キー、CA バンドルあり | 成功(list-tables が空の一覧を返した) |
SQLite との比較
スクリプトを 2 本用意しました。1 本は基本操作の 24 コマンド、もう 1 本は TTL、項目サイズ、Streams など差が出やすい操作です。この 2 本を、dev イメージ(SQLite)と PostgreSQL 構成の両方へ流しました。時刻、ID、キー順を無視して応答を比べました。ARN に入る 12 桁のアカウント ID はインストールごとに採番されるため、一致の対象にしていません。ARN を除く応答は一致しました。GSI とストリーム付きテーブルが ACTIVE になるまでの時間は、SQLite が 1,410 ms、PostgreSQL が 1,987 ms でした。
DynamoDB との応答比較
同じ操作を、ExtendDB(SQLite)と実際の DynamoDB へ流しました。実際の DynamoDB は us-east-1 のオンデマンドで、テーブルは 2 本、各操作は 1 回です。
一致した操作
基本操作の 24 コマンドのうち 22 コマンドが、実際の DynamoDB と同じ応答でした。残りの 2 コマンドは、次の「異なった操作」の表にある create-table と 26 件を書き込む batch-write-item です。条件付き書き込みの失敗と、トランザクションの取り消し理由 [None, ConditionalCheckFailed] が同じでした。予約語を使った scan のエラー、存在しないテーブルへの get-item、キー型の不一致、update-item の結果も同じでした。
差が出やすい操作のスクリプトでは、次の操作が一致しました。約 401KB の項目は拒否され、約 390KB の項目は成功しました(ConsumedCapacity は 391.0)。GSI(射影 ALL)付きテーブルの ConsumedCapacity は、put-item が 2.0、強い整合性の get-item が 1.0、query が 0.5 でした。GSI への強い整合性読み取りは拒否され、PartiQL の INSERT、SELECT、UPDATE、DELETE は通りました。Streams(StreamViewType は NEW_AND_OLD_IMAGES)は、レコード 8 件(INSERT 4 件、MODIFY 2 件、REMOVE 2 件)が両方で一致しました。
異なった操作
同じ条件で比べられた操作のうち、応答が異なったものです。
| 操作 | ExtendDB(SQLite) | 実際の DynamoDB |
|---|---|---|
| オンデマンドのテーブル作成直後の応答 | GSI の IndexStatus が ACTIVE。BillingModeSummary に LastUpdateToPayPerRequestDateTime がある | GSI の IndexStatus が CREATING。BillingModeSummary は BillingMode のみ |
| 26 件を書き込む batch-write-item | ValidationException。メッセージは requestItems のマップ全体を示し、長さ 25 以下と 1 以上の 2 つの制約を挙げる | ValidationException。メッセージは RequestItems.extenddb-verify-t1.member を示し、長さ 25 以下の制約を挙げる |
| タグキーが重複した create-table | InternalServerError(CLI が 3 回再試行して終了) | ValidationException(Duplicate Tag Keys provided as input) |
| GSI とストリーム付きテーブルが ACTIVE になるまでの時間 | 1,410 ms | 16,409 ms |
| TTL を有効化した直後の無効化 | 成功 | ValidationException(Time to live has been modified multiple times within a fixed interval) |
| 存在しないテーブルの delete-table | ResourceNotFoundException(Requested resource not found) | ResourceNotFoundException(テーブル名付きで Requested resource not found) |
ACTIVE までの時間は、create-table を呼んでから、describe-table(毎回 CLI を起動)と 0.25 秒の待機を繰り返し、ACTIVE を確認するまでの時間です。測定は各 1 回です。
次の点を確かめるテストは、今回の操作では ExtendDB と実際の DynamoDB で結果が分かれました。
- 重複したタグキーの create-table のエラー種別
- 26 件の batch-write-item と存在しないテーブルの delete-table のエラーメッセージ
- TTL を続けて切り替えたときの挙動
- 作成直後の GSI の状態
実際の DynamoDB と比較できなかった項目
表の「ドキュメントの記載」は、次の差異ドキュメントのものです。
| 項目 | ドキュメントの記載 | ExtendDB の応答 | 実際の DynamoDB |
|---|---|---|---|
| TTL の属性名に空白を含める | 属性名は [a-zA-Z0-9._-]+ に制限 |
ValidationException(TimeToLiveSpecification.AttributeName contains invalid characters) | 直前の無効化が拒否され、ttl で有効のままだったため、TimeToLive is active on a different AttributeName で拒否された。同じ条件で比べられなかった |
| ListGlobalTables | Global tables は未実装 | UnknownOperationException | 送っていない |
まとめ
ExtendDB 1.0 の dev イメージは AWS CLI から、@extenddb/dev は SDK v3 から、外部データベースなしで使えました。今回流した操作の多くは実際の DynamoDB と同じ応答で、PostgreSQL 構成の応答も SQLite と同じでした。
2026 年 11 月 11 日には、AWS のローカル用エミュレータ AWS Emulator も発表されています。AWS Emulator では再現できず、より DynamoDB に近いローカルのテスト環境が必要な場合は、ExtendDB の再現範囲を把握したうえで活用してください。









