DynamoDBテーブルを別のアカウントやリージョンにコピーする方法
DynamoDBには、AWS CLIにもコンソールにも「テーブルをコピー」コマンドがありません。すべてのコピーは2つの半分から成ります:ソースからデータを取り出すことと、宛先のテーブルにロードすることです。AWSはその両方を行う4つの方法を用意しており、それぞれ何を引き継ぐかが異なります。
DynamoDBテーブルを別のアカウントやリージョンにコピーするには?
ネイティブのcopy-tableコマンドはありません。状況に合うAWSの経路を選びます:小さな単発コピーや既存のターゲットにはScan + BatchWriteItemのスクリプト、大きなテーブルにはS3へのエクスポートからのインポート(必要ならサブセットに絞り込み可能)、インデックスとキャパシティ設定をデータと一緒にリストアしたいならAWS Backupのコピー+リストア、継続的なライブレプリケーションにはグローバルテーブルです。リストアやインポートはいずれも新しいテーブルを作成します。
| 状況 | 最適なアプローチ |
|---|---|
| 小さなテーブル、単発、または既存のターゲット | Scan + BatchWriteItemスクリプト |
| 大きなテーブル、スナップショットを許容できる | S3エクスポート → インポート(新テーブル作成) |
| リストアを伴うクロスアカウント / クロスリージョン | AWS Backupのコピー+リストア |
| 継続的なライブレプリケーション(単発コピーではない) | グローバルテーブル |
普遍的に「正しい」アプローチはありません。テーブルのサイズ、必要なのがポイントインタイムのスナップショットかライブデータか、宛先が新規テーブルか既存テーブルかによって決まります。読み取りの半分を自分で書きたくなければ、DynoTableがソースデータをエクスポートしてくれます(後述)。
アプローチ1:Scan + BatchWriteItem(スクリプト)
最もローテクな経路:ソースからScanですべてのアイテムを読み、BatchWriteItemで宛先に書き込みます。スクリプトが両側の認証情報を持っている(またはターゲットアカウントのロールを引き受ける)限り、クロスアカウントでもクロスリージョンでも機能し、既存のテーブルに書き込める唯一の経路でもあります。先に同じキースキーマでターゲットを作成してください。
import {DynamoDBClient, ScanCommand, BatchWriteItemCommand} from '@aws-sdk/client-dynamodb';
const src = new DynamoDBClient({region: 'us-east-1'});
const dst = new DynamoDBClient({region: 'eu-west-1'}); // target account's credentials
const SOURCE = 'SourceTable';
const TARGET = 'TargetTable';
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
async function writeChunk(items) {
let requests = items.map((Item) => ({PutRequest: {Item}}));
for (let attempt = 0; requests.length > 0; attempt++) {
if (attempt === 8) throw new Error(`${requests.length} items still unprocessed`);
if (attempt > 0) await sleep(Math.min(100 * 2 ** attempt, 5000));
const out = await dst.send(new BatchWriteItemCommand({RequestItems: {[TARGET]: requests}}));
requests = out.UnprocessedItems?.[TARGET] ?? [];
}
}
let ExclusiveStartKey;
let copied = 0;
do {
const page = await src.send(new ScanCommand({TableName: SOURCE, ExclusiveStartKey}));
const items = page.Items ?? [];
for (let i = 0; i < items.length; i += 25) await writeChunk(items.slice(i, i + 25));
copied += items.length;
ExclusiveStartKey = page.LastEvaluatedKey;
} while (ExclusiveStartKey);
console.log(`copied ${copied} items`);低レベルクライアントはすべてのアイテムを型付きのワイヤ形式のまま保つので、数値もセットもそのままターゲットに届きます。スクリプトが処理していることとその理由:
BatchWriteItemは1回の呼び出しにつき25アイテムまたは16MBが上限です。そのためスクリプトは分割し、1回の呼び出しが未処理のアイテムを返したら指数バックオフでリトライします (APIリファレンス)。- 書き込みは書き込みキャパシティを消費します。 プロビジョンドのターゲットでは、スロットリングされた書き込みが
UnprocessedItemsとして返るか、バッチ内に1件も成功しなければProvisionedThroughputExceededExceptionとして返ります(SDKがそれをリトライします)。オンデマンドはより多くを吸収しますが、それでも各パーティションの上限は1,000 WCU / 3,000 RCUです。始める前に、書き込み負荷を宛先のキャパシティに対して見積もってください。 Scanはテーブル全体を読み取り、すべてのアイテムを計測します。古典的なQuery-vs-Scanのコストで、LastEvaluatedKeyでページをたどります。ページネーションを参照してください。- アトミックではありません。 スキャンの実行中に書き込まれたアイテムは取りこぼされる可能性があります。稼働中のテーブルを一貫した状態でコピーするには、S3エクスポートからスナップショットを取るか(アプローチ2)、Scanのドキュメントにあるとおり、スキャンの前にStreamsを有効にし、
ConsistentRead: trueでスキャンしてから、ストリームの変更をターゲットに再生します。一貫性のあるスキャンは読み取りが2倍かかります。ストリームレコードの保持期間は24時間なので、スキャンと再生はその時間内に終えなければなりません。大きなテーブルでは、代わりにS3エクスポートのスナップショットを使ってください(DynamoDB Streams)。
小さなテーブルや、コピー中に変換やフィルタが必要な場合に最適です。読み取りの半分がDynoTableのDynamoDB-JSONエクスポートとしてすでに存在するなら、スクリプトは分割して書き込むループだけに縮みます。
アプローチ2:S3にエクスポートし、新しいテーブルにインポートする
大きなテーブルには、DynamoDBのマネージドなS3へのエクスポートとS3からのインポートの組み合わせが、キャパシティをまったく叩かずに済みます。
エクスポートはテーブルをS3バケットにスナップショットします (仕組み):
- ソーステーブルでポイントインタイムリカバリ(PITR)の有効化が必要です。
- 読み取りキャパシティを消費せず、テーブルのパフォーマンスに影響しません。ライブテーブルではなく継続的なバックアップから読み取ります。
- 出力はDynamoDB JSONまたはAmazon Ion形式です。(S3に着地するのは、型タグごとすべて含んだDynamoDB-JSONワイヤフォーマットです。)
- 別のアカウントが所有する、別のリージョンにあるS3バケットにも書き込めます。エクスポートの呼び出しは引き続きテーブルのアカウントから行います。別のアカウントのバケットには
--s3-bucket-owner <bucket-account-id>を加え、バケット所有者は、エクスポートするロールがs3:PutObject、s3:PutObjectAcl、s3:AbortMultipartUploadを呼び出せるバケットポリシーを追加します (エクスポートのリクエスト)。 - フルと増分のエクスポートをサポートします(増分エクスポートGA、2023年9月)。
- オプションでフィルタを受け付けます:1つのパーティションキー値に対するキー条件、フィルタ式、プロジェクションです (フィルタ付きエクスポート)。 DynamoDBが読み取るデータを減らすのはキー条件だけで、フィルタ式は読み取りの後に適用されます。
アカウント111122223333からアカウント444455556666へのコピーなら、最も簡単な構成はターゲットアカウントにバケットを置くことです:ソースアカウントがそこにエクスポートし、ターゲットは自分のバケットからインポートします。以下はソースアカウントの認証情報で実行します:
aws dynamodb export-table-to-point-in-time \
--table-arn arn:aws:dynamodb:us-east-1:111122223333:table/SourceTable \
--s3-bucket my-migration-bucket --s3-prefix copy \
--s3-bucket-owner 444455556666 \
--export-format DYNAMODB_JSON \
--filter-specification '{"KeyConditionExpression": "PK = :t",
"ExpressionAttributeValues": {":t": {"S": "TENANT#42"}}}' # omit for the whole table古いAWS CLIは--filter-specificationをUnknown optionsで拒否します。これが出たらCLIを更新してください。
インポートはそのS3データから新しいテーブルを構築します (仕組み):
- まっさらな新規テーブルにのみインポートします。既存のテーブルにはインポートできません。
- 新しいテーブルの書き込みキャパシティを消費しません。
- CSV、DynamoDB JSON、Amazon Ionを受け付けます(オプションでGZIP/ZSTD圧縮)。
- ソースのS3バケットは別のアカウントや別のリージョンにあっても構いません。インポートするアカウントが所有していないバケットなら、
--s3-bucket-sourceにS3BucketOwner=<bucket-account-id>を加え、バケット所有者がインポートするロールにs3:GetObjectとs3:ListBucketを許可します。 - インポート時にグローバルセカンダリインデックスを定義でき、インポート完了と同時にクエリ可能になります。ローカルセカンダリインデックスはサポートされません。LSIを持つソースには、Backupリストア(アプローチ3)か、LSI付きで作成したターゲットへのscan+writeが必要です。
インポートはエクスポートのデータフォルダs3://<bucket>/<prefix>/AWSDynamoDB/<export-id>/data/を指定します。エクスポートIDはエクスポートARNの最後の部分です
(インポートのリクエスト)。ターゲットアカウントの認証情報で実行します。バケットはそのアカウント自身のものなので、所有者パラメータは不要です:
aws dynamodb import-table --region eu-west-1 \
--s3-bucket-source S3Bucket=my-migration-bucket,S3KeyPrefix=copy/AWSDynamoDB/<export-id>/data/ \
--input-format DYNAMODB_JSON --input-compression-type GZIP \
--table-creation-parameters '{"TableName": "TargetTable",
"KeySchema": [{"AttributeName": "PK", "KeyType": "HASH"}, {"AttributeName": "SK", "KeyType": "RANGE"}],
"AttributeDefinitions": [{"AttributeName": "PK", "AttributeType": "S"}, {"AttributeName": "SK", "AttributeType": "S"}],
"BillingMode": "PAY_PER_REQUEST"}'ポイントインタイムのスナップショット(ライブデータではなく)が許容できる、大規模なクロスアカウント/クロスリージョン移行には、これが最もクリーンな経路です。
アプローチ3:AWS Backupのコピー+リストア
すでにAWS Backupを使っているなら、リカバリポイントをアカウントとリージョンをまたいでコピーできます (クロスアカウント移行ガイド):
- 両方のアカウントでAWS Backup → Settingsを開き、Advanced features for Amazon DynamoDB backupsを有効にして、Cross-account backupをオンにします。これらがないとコピーのステップが使えません。
- ソーステーブルをバックアップボールトにバックアップします。
- バックアップをターゲットのアカウント/リージョンのボールトにコピーします。そのボールトはデフォルトのボールトであってはならず、そのアクセスポリシーがソースアカウントからの
backup:CopyIntoBackupVaultを許可していなければコピーは拒否されます (クロスアカウントバックアップ)。 - ターゲットで新しいテーブルにリストアします。
主な制約:
クロスアカウントコピーには、両方のアカウントが同じAWS Organizationに属している必要があります。そうでなければ、バケットがどのアカウントのものでもよいS3エクスポート/インポートの経路を使ってください。
リストアは常に新しいテーブルを作成します。既存のテーブルの上にリストアすることはできません。
フルリストアは、バックアップ時点で記録されたソースのGSI、LSI、課金モード、プロビジョンドキャパシティを保持します (リストアの仕組み)。リストアの時間とコストを節約するためにインデックスを除外することはできますが、リストア時に新しいインデックスを追加することはできません。GSIは後から追加します。オンラインでバックフィルされます (GSI vs LSI)。プロビジョンドのテーブルでは、
CreateブロックにProvisionedThroughputも指定してください:aws dynamodb update-table --table-name TargetTable \ --attribute-definitions AttributeName=GSI1PK,AttributeType=S AttributeName=SK,AttributeType=S \ --global-secondary-index-updates '[{"Create": {"IndexName": "GSI1", "KeySchema": [{"AttributeName": "GSI1PK", "KeyType": "HASH"}, {"AttributeName": "SK", "KeyType": "RANGE"}], "Projection": {"ProjectionType": "ALL"}}}]'暗号化。 AWS Backupはコピーを宛先ボールトのキーで再暗号化します。ソーステーブルがカスタマーマネージドKMSキーを使っている場合は、そのキーをターゲットアカウントと共有してください (クロスアカウントバックアップ)。リストア時に、ターゲットで新しいテーブルの暗号化キーを選びます。
アプローチ4:グローバルテーブル(単発コピーではなくライブレプリケーション)
グローバルテーブルはテーブルをリージョン間で、オプションでアカウント間でも (マルチアカウントGA、2026年2月) 継続的にレプリケートします。どのレプリカも読み取りと書き込みを提供し(マルチアクティブ)、非同期のラストライターウィンズのレプリケーションで動きます (グローバルテーブルのドキュメント)。
宛先リージョンを無期限に同期させておきたいとき(DR、低レイテンシのローカル読み取り)に使い、クリーンな単発移行には使いません。既存のテーブルにリージョンを追加すると、DynamoDBが既存データを新しいレプリカにバックフィルします。
エクスポートの半分:DynoTableでデータを取り出す
手書きのスキャンループは、小さな移行の中で最もエラーを起こしやすい部分です(ページの取りこぼし、数値精度の破損、型タグの早すぎる除去)。DynoTableはその半分をエクスポートダイアログ(⌘⇧E)でこなします:
- ロスレス: フィルター完全一致を、値: DynamoDB-JSONを指定してJSONまたはNDJSONでエクスポートします。これは型で包まれたワイヤ形式で、プレーンJSONが壊してしまう大きな数値(> 2⁵³)を保持します。宛先がDynamoDBでないならCSVも使えます。フォーマットの詳細はCSVへのエクスポートを参照してください。
- スコープ指定: ファイルへのエクスポートはクエリに一致するすべてのアイテムをディスクにストリームするので、「
TENANT#42のアイテムだけをステージングにコピー」はフィルタで済みます。S3を宛先にした場合は、同じクエリからマネージドエクスポートのフィルタを組み立てます(アプローチ2)。 - 大きなテーブル: エクスポートはデタッチしてバックグラウンドで実行され、1行ずつディスクにストリームされます。数ギガバイトの取り出しも、タブの切り替えやアプリのリロードを生き延びます。
- ロード後の検証: ソースを開き、続いてターゲットを開き(別のアカウントやリージョンならプロファイルを切り替えます)、それぞれを最後まで実行で最後までスキャンして、グリッドが報告するアイテム数を比較します。そのうえで、検証スクリプトを書かずにサンプルレコードを抜き取り確認できます。テーブルの概要に出るカウントは比較に使わないでください。それは
DescribeTableの推定値で、更新はおよそ6時間ごとです(テーブルのサイズとアイテム数)。
DynoTableはロードもこなせます。そのテーブルデータのインポートは、DynamoDB-JSONまたはNDJSONファイルを既存の宛先テーブルにそのまま書き込みます(有料プラン、元に戻せません)。大きなテーブルや、インデックス付きで到着しなければならないテーブルには、AWSツーリング(書き込みスクリプト、S3インポート、Backupリストア。上のアプローチ1〜3)を使ってください。
運用上の落とし穴(すべてのアプローチ共通)
- GSIの再作成はタダではありません。 scan+writeのコピーはインデックスを運びません。ターゲットで定義し、それらは個別にバックフィルされます(そして課金されます)。宛先のGSI vs LSIレイアウトは前もって計画してください。LSIはテーブル作成時にしか作成できません (LSIのドキュメント)。
- scan+writeやS3インポートではキャパシティモードは引き継がれません。 新しいテーブルは、あなたが設定したモードで始まります(Backupリストアは、上書きしない限りソースのモードを保持します)。scan+writeのコピーの前に書き込み負荷を見積もってください。代表的なアイテムをアイテムサイズ計算ツールで測り、アイテム数を掛けてWCUの概算を出します。
- TTL、ストリーム、オートスケーリング、タグはテーブル設定であってデータではありません。 どのコピー方法もそれらすべてを運びはしません。ソースから
describe-table、describe-time-to-live、list-tags-of-resourceで読み取り、update-time-to-live、update-table --stream-specification、tag-resource、application-autoscaling register-scalable-target/put-scaling-policyで適用してください。 - DynamoDB JSON ≠ プレーンJSON。 エクスポートとスキャンは型タグ付きのDynamoDB-JSONを出力します。途中で変換するなら、DynamoDB JSONコンバータがマーシャリングを引き受けます。
- カットオーバー前に検証を。
DescribeTableのカウントは最大6時間古いので、作りたてのターゲットが正当にゼロを報告することもあります。正確に数えるにはaws dynamodb scan --table-name TargetTable --select COUNTを使う(テーブル全体を読み取ります)か、インポートのImportedItemCountと比較し、そのうえで両側のレコードを抜き取り確認してください。
よくある質問
DynamoDBテーブルをコピーするAWS CLIコマンドはありますか?いいえ。ネイティブのcopy-tableコマンドはありません。scan + batch-write-itemを組み合わせるか、マネージドのエクスポート/インポートかAWS Backupの機能を使います。
DynamoDBテーブルを別のアカウントにコピーするには? 3つの選択肢があります:両アカウントの認証情報を持つscan+writeスクリプト、S3エクスポート/インポート(バケットはクロスアカウント可)、またはAWS Backupのコピー+リストア(両アカウントが同じAWS Organizationに属している必要があります)。
DynamoDBテーブルを別のリージョンにコピーするには? S3エクスポート/インポートとAWS Backupはどちらもクロスリージョンをサポートします。単発のコピーではなく継続的なクロスリージョン同期には、ターゲットリージョンにグローバルテーブルのレプリカを追加します。
テーブルをコピーするとインデックスもコピーされますか? AWS BackupのリストアはGSIとLSIを保持します。S3インポートでは新しいテーブルにGSI(LSIは不可)を定義できます。scan+writeスクリプトは何もコピーしないので、ターゲットで自分でインデックスを作成し、それらは個別にバックフィルされます。
既存のDynamoDBテーブルにインポートできますか?いいえ。DynamoDBのS3インポートもAWS Backupのリストアも、新しいテーブルを作成します。既存のテーブルにマージするには、scan+writeスクリプトを使ってください。
テーブルの一部だけをコピーできますか?はい。マネージドのS3エクスポートはフィルタ(--filter-specification)を受け付けるので、フィルタ付きエクスポートに続けてインポートすれば、サブセットを新しいテーブルにコピーできます。Backupリストアはテーブル全体のみです。サブセットを既存のテーブルにマージするには、DynoTableからフィルタの一致分をDynamoDB-JSONでエクスポートするか、フィルタ付きスキャンをスクリプトにして、そのサブセットをターゲットに書き込みます。
GUIはカットオーバーの確認を楽にします:移動するアイテムをちょうどそのままエクスポートし、コピー後にソースとターゲットを開いてそれぞれを最後までスキャンし、アイテム数といくつかのサンプルレコードを比較し、スキャンスクリプトを書かずにアドホックなチェックを実行できます。DynoTableをダウンロードして、アカウントとリージョンをまたぐ移行のエクスポートと検証の半分を実行してください。