配置

运行前确认：

• 源表已开启 DynamoDB Streams，视图类型为 NEW_IMAGE 或 NEW_AND_OLD_IMAGES。
• 目标表已创建，分区键和排序键（如有）的名称及类型与源表一致。

这项要求只涉及键属性。DynamoDB 的非键属性无须在建表时定义，ddb-migrate 会保留这些属性的类型和值。

配置文件

ddb-migrate.toml：

# ddb-migrate 先全量扫描 AWS DynamoDB 源表，再持续读取 DynamoDB Streams。

[source]
access_key_id = ""                        # AK/SK 都为空时使用 AWS 默认凭证链
secret_access_key = ""
region = "us-east-1"                     # 必填，不读取 AWS_REGION
table = "source_table"
checkpoint_enabled = true                 # 启用断点续传
checkpoint_file_path = "checkpoint.json"
scan_segments = 4                         # 全量 Scan 并行分段数

[target]
access_key_id = "username:password"        # Tair 使用“账号:密码”格式
secret_access_key = "dummy"               # 固定占位值
region = "us-east-1"                     # 自定义 endpoint 可省略，默认 us-east-1
endpoint_url = "http://your-endpoint:80"  # 自定义 endpoint 默认跳过 TLS 验证
table = "target_table"
workers = 4                                # 目标端并发写入 worker 数

示例列出全部字段。字符串字段写成空字符串与省略该字段的效果相同；布尔和整数项直接省略。具体结果见下表。[source] 和 [target] 的凭证相互独立。

source

迁移源端固定访问 AWS 官方 DynamoDB 和 DynamoDB Streams，不提供 endpoint_url。

配置项	作用	省略条件与结果
access_key_id、secret_access_key	源端 AWS 凭证	使用 AWS 默认凭证链时，两项同时省略或同时留空。使用固定 AK/SK 时两项都要填写；只填写一项会导致启动失败。
region	源表所在的 AWS Region	不能省略。即使运行环境设置了 AWS_REGION，仍需在 TOML 中填写。
table	源表名称	不能省略。
checkpoint_enabled	是否持久化全量和增量进度	可以省略，默认 false。关闭后中断不能续传，重启会重新执行全量 Scan。
checkpoint_file_path	checkpoint 文件路径	可以省略，默认 checkpoint.json。checkpoint_enabled = false 时不使用该文件。
scan_segments	全量 Scan 的并行分段数	可以省略，默认 4；小于或等于 0 时也使用 4。修改分段数后，未完成的旧 Scan checkpoint 不能继续使用，程序会重新扫描源表。

target

配置项	作用	省略条件与结果
access_key_id、secret_access_key	目标端凭证	AWS 目标端使用默认凭证链时，两项可以同时省略。Tair 目标端两项都要填写：access_key_id 使用“账号:密码”，secret_access_key 固定为 dummy。只填写一项会导致启动失败。
region	AWS 官方端点所在 Region，或自定义端点的签名 Region	endpoint_url 留空时不能省略。endpoint_url 非空时可以省略，默认使用 us-east-1。迁移到 Tair 时可以省略。
endpoint_url	目标端 DynamoDB API 地址	AWS 官方 DynamoDB 目标端可以省略，程序根据 region 选择官方端点。迁移到 Tair 时不能省略。
table	目标表名称	不能省略。
workers	目标端并发写入 worker 数	可以省略，默认 4；小于或等于 0 时也使用 4。

迁移到 Tair 时，目标端最少需要填写 access_key_id、secret_access_key、endpoint_url 和 table。region 和 workers 可以省略。

AWS 凭证来源

配置文件中的 AK/SK 都非空时，程序只使用这组固定凭证。两项同时省略或留空时，程序使用 AWS SDK for Go v2 默认凭证链。

运行环境	TOML 中的 AK/SK	运行环境配置
环境变量	两项同时省略或留空	设置 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY；临时凭证同时设置 AWS_SESSION_TOKEN。
Web Identity	两项同时省略或留空	由运行环境提供 Web Identity 配置，例如 EKS Pod 使用的 IAM 角色。
AWS Profile 或 IAM Identity Center	两项同时省略或留空	使用 ~/.aws/credentials 和 ~/.aws/config；通过 AWS_PROFILE 选择非默认 profile，并按所用方式完成登录。
ECS 任务角色	两项同时省略或留空	为 ECS Task 配置 IAM 角色。
EC2 实例角色	两项同时省略或留空	为 EC2 实例配置 IAM 角色，SDK 通过实例元数据服务取得临时凭证。

默认凭证链依次检查环境变量、Web Identity、AWS shared credentials/config、ECS 任务角色和 EC2 实例角色，并使用首先取得的凭证。因此，在已绑定实例角色的 EC2 上设置 AK/SK 环境变量后，环境变量会覆盖实例角色；设置 AWS_PROFILE 的同时存在 AK/SK 环境变量时，环境变量会覆盖 profile。

例如，在已绑定 IAM 角色的 EC2 上运行时，可以删除 [source] 中的 access_key_id 和 secret_access_key，保留 region 和 table。如果目标端是 Tair，[target] 中的 Tair 账号密码和 dummy 仍需填写。

使用命名 profile 的示例：

AWS_PROFILE=production ./ddb-migrate ddb-migrate.toml

如果默认凭证链没有找到凭证，程序会在首次访问 AWS API 时失败。完整加载顺序见 Configure the SDK - AWS SDK for Go v2。

启动

./ddb-migrate ddb-migrate.toml