DynamoDB の API を再現する ExtendDB 1.0 を試してみた

DynamoDB の API を再現する ExtendDB 1.0 を試してみた

AWS が公開した DynamoDB 互換アダプタ ExtendDB 1.0 を、dev イメージ、@extenddb/dev、PostgreSQL 構成で動かし、同じ操作を実際の DynamoDB にも流して応答を比べました。AWS CLI と SDK の基本操作は通り、違いは、テーブル作成直後の状態やエラーの扱いなどに見られました。
2026.11.19

はじめに

2026 年 11 月 18 日に ExtendDB 1.0 が公開されました。

https://aws.amazon.com/jp/about-aws/whats-new/2026/11/aws-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 ビルドです。

https://github.com/ExtendDB/extenddb

バックエンド 区分 バックエンド用イメージ この記事
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 を使いました。リポジトリはこのファイルをローカル開発専用と記しており、パスワードの既定値は開発用に公開された値です。

https://github.com/ExtendDB/extenddb/blob/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 と比較できなかった項目

表の「ドキュメントの記載」は、次の差異ドキュメントのものです。

https://github.com/ExtendDB/extenddb/blob/main/docs/differences-from-dynamodb.md

項目 ドキュメントの記載 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 の再現範囲を把握したうえで活用してください。

https://dev.classmethod.jp/articles/aws-emulator-local-try/

この記事をシェアする

AWSのお困り事はクラスメソッドへ

関連記事