# Exporting a Domain to Amazon Simple Storage Service
Amazon SimpleDB allows you to export domain data to Amazon S3 for migration and archival. The export process runs asynchronously in the background and does not affect the performance of your active database operations. Exported data is stored in standard JSON format.
The new Amazon SimpleDB export operations are only available through the SimpleDBv2 service in newer versions of the AWS SDKs and AWS CLI.
**Important**
Exported data cannot be restored back to Amazon SimpleDB. The export feature is designed for one-way data migration and archival. After you have exported your Amazon SimpleDB data to Amazon S3, you can't import the data again.
This section covers the following topics:
**Topics**
+ [Prerequisites and Permissions](ExportPrerequisites.md)
+ [Export a domain to Amazon S3](HowToExportDomainToS3.md)
+ [Export Considerations](ExportConsiderations.md)
+ [Track Export Status](TrackingExportStatus.md)
+ [List Exports in an Account](ListingExports.md)
+ [Log Amazon SimpleDB export calls with AWS CloudTrail](LoggingExportsCloudTrail.md)
+ [Best Practices for Domain Exports](ExportBestPractices.md)
# Prerequisites and Permissions
Before exporting a domain, you need to prepare your Amazon S3 bucket and configure the necessary permissions. This section describes the prerequisites for exporting domain data.
## Identify the Amazon S3 Bucket for Export
You must identify or create an Amazon S3 bucket to store the exported data. The bucket can be in the same AWS Region as your Amazon SimpleDB domain or in a different Region. For optimal performance, we recommend using a bucket in the same Region as your domain.
When setting up your Amazon S3 bucket, consider implementing the following security measures:
+ **Bucket policies** - Configure bucket policies to control access to exported data.
+ **Default server-side encryption** - Enable default encryption using Amazon S3 managed keys (SSE-S3) or KMS keys (SSE-KMS) to protect data at rest.
+ **Versioning** - Enable versioning to maintain multiple versions of exported data and protect against accidental deletion.
For more information about Amazon S3 buckets, see the following topics in the *Amazon S3 User Guide*:
+ [ Viewing bucket properties](https://docs.aws.amazon.com/AmazonS3/latest/userguide/view-bucket-properties.html)
+ [ Setting default server-side encryption behavior for Amazon S3 buckets](https://docs.aws.amazon.com/AmazonS3/latest/userguide/default-bucket-encryption.html)
+ [ Creating a bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html)
## Provide Access to the Amazon S3 Bucket
To export domain data, you need appropriate IAM permissions for both Amazon SimpleDB and Amazon S3 operations. The following sections provide example IAM policies for the export operations.
For more information about Amazon S3 access control, see [ Identity and access management in Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-control-overview.html) in the *Amazon S3 User Guide*.
### IAM Policy for StartDomainExport
The following IAM policy grants permission to start a domain export and write data to an Amazon S3 bucket:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowSimpleDBStartDomainExportAction",
"Effect": "Allow",
"Action": "sdb:StartDomainExport",
"Resource": "arn:aws:sdb:us-east-1:123456789012:domain/yourDomain"
},
{
"Sid": "AllowWritesToS3Bucket",
"Effect": "Allow",
"Action": [
"s3:ListObjects",
"s3:PutObject",
"s3:HeadBucket"
],
"Resource": "arn:aws:s3:::your-bucket/*"
}
]
}
```
You can use wildcard patterns in the Resource ARN to grant permissions for multiple domains:
+ All domains: `arn:aws::sdb:us-east-1:111122223333:domain/*`
+ Pattern match: `arn:aws::sdb:us-east-1:111122223333:domain/test*`
**Note**
The `s3:HeadBucket` permission is optional but recommended. Without it, AWS CloudTrail logs may show "Access Denied" entries when Amazon SimpleDB verifies bucket accessibility, even though the export succeeds.
### IAM Policy for GetExport
The following IAM policy grants permission to retrieve information about an export:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowSimpleDBGetExportAction",
"Effect": "Allow",
"Action": "sdb:GetExport",
"Resource": "arn:aws:sdb:us-east-1:123456789012:domain/yourDomain/export/fd59ec34-110b-419b-9395-81a1a0914c90"
}
]
}
```
You can use wildcard patterns to grant permissions for multiple exports:
+ All exports for a domain: `arn:aws::sdb:us-east-1:111122223333:domain/yourDomain/export/*`
+ All exports for all domains: `arn:aws::sdb:us-east-1:111122223333:domain/*`
### IAM Policy for ListExports
The following IAM policy grants permission to list exports in your account:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowSimpleDBListExportsAction",
"Effect": "Allow",
"Action": "sdb:ListExports",
"Resource": "*"
}
]
}
```
**Important**
To list all exports without a domain filter, the Resource must be set to `"*"` with no Deny policy. For filtered listing by domain, you can use domain-specific ARNs, but the least-restricted privilege is recommended for the ListExports operation.
# Export a domain to Amazon S3
After completing the prerequisites, you can start exporting a domain using the `start-domain-export` command. The following example shows a basic export operation:
```
aws simpledbv2 start-domain-export \
--domain-name 'myDomain' \
--s3-bucket 'my-export-bucket' \
--s3-bucket-owner '111122223333'
```
The command returns information about the export request:
```
{
"clientToken": "ad9ac782-954a-45d1-8d47-8ef843c0ffe2",
"exportArn": "arn:aws::sdb:us-east-1:111122223333:domain/myDomain/export/3eb4eaed-872b-4e08-b4b6-ff6999a83e01",
"requestedAt": "2025-07-04T09:51:56.064000+00:00"
}
```
The `exportArn` uniquely identifies the export and is used to track its status and retrieve information about the export.
# Export Considerations
## Exporting to a Different Region
You can export domain data to an Amazon S3 bucket in a different AWS Region. No additional parameters are required beyond specifying the bucket name and ensuring your IAM permissions allow cross-Region access. Standard Amazon S3 data transfer charges apply for cross-Region exports.
## Using Different Encryption Algorithms
You can specify the encryption algorithm for the exported data using the `--s3-sse-algorithm` parameter:
**Default encryption (AES256/SSE-S3):**
```
aws simpledbv2 start-domain-export \
--domain-name 'myDomain' \
--s3-bucket 'my-export-bucket' \
--s3-bucket-owner '111122223333' \
--s3-sse-algorithm AES256
```
**SSE-KMS with AWS managed key:**
```
aws simpledbv2 start-domain-export \
--domain-name 'myDomain' \
--s3-bucket 'my-export-bucket' \
--s3-bucket-owner '111122223333' \
--s3-sse-algorithm 'KMS'
```
**SSE-KMS with customer managed key:**
```
aws simpledbv2 start-domain-export \
--domain-name 'myDomain' \
--s3-bucket 'my-export-bucket' \
--s3-bucket-owner '111122223333' \
--s3-sse-algorithm 'KMS' \
--s3-sse-kms-key-id 'arn:aws::kms:us-east-1:111122223333:key/1ff46940-e71b-4cba-85a8-d5cd935e2e53'
```
## Using a Custom Amazon S3 Key Prefix
By default, exported data is written to the path `AWSSimpleDB///` in your Amazon S3 bucket. You can specify a custom prefix using the `--s3-key-prefix` parameter:
```
aws simpledbv2 start-domain-export \
--domain-name 'myDomain' \
--s3-bucket 'my-export-bucket' \
--s3-bucket-owner '111122223333' \
--s3-key-prefix 'exports/simpledb'
```
With this prefix, data is written to `exports/simpledb/AWSSimpleDB///`.
# Track Export Status
After starting an export, you can track its progress using the `get-export` command with the export ARN returned by `start-domain-export`:
```
aws simpledbv2 get-export \
--export-arn 'arn:aws::sdb:us-east-1:111122223333:domain/myDomain/export/3eb4eaed-872b-4e08-b4b6-ff6999a83e01'
```
The command returns detailed information about the export as shown in the following example:
```
{
"exportArn": "arn:aws::sdb:us-east-1:111122223333:domain/myDomain/export/3eb4eaed-872b-4e08-b4b6-ff6999a83e01",
"clientToken": "ad9ac782-954a-45d1-8d47-8ef843c0ffe2",
"exportStatus": "IN_PROGRESS",
"domainName": "myDomain",
"requestedAt": "2025-06-03T10:05:47.757000+00:00",
"s3Bucket": "my-export-bucket",
"s3BucketOwner": "111122223333",
"exportDataCutoffTime": "2025-06-03T10:05:47.757000+00:00"
}
```
## Export Status Values
The `exportStatus` field indicates the current state of the export:
PENDING
The export request has been received and is queued for processing.
IN\$1PROGRESS
The export is actively being processed and data is being written to Amazon S3.
SUCCEEDED
The export completed successfully and all data has been written to Amazon S3.
FAILED
The export encountered an error. The response includes `failureCode` and `failureMessage` fields with details about the failure.
## Amazon S3 File Structure During Export
As the export progresses, Amazon SimpleDB writes files to your Amazon S3 bucket in the following order:
1. An empty `_started` file is created first to verify that the bucket is writable.
1. Data files are written to the `data/` directory with names in the format `dataFile.json`.
1. When the export completes successfully, manifest files (`manifest-file.json` and `manifest-summary.json`) are written to the export directory.
## Understanding `exportDataCutoffTime`
The `exportDataCutoffTime` field indicates the timestamp used to determine which data is included in the export. It is important to understand that Amazon SimpleDB exports are not point-in-time snapshots.
+ All items inserted **before** this timestamp are included in the export.
+ Items inserted **after** this timestamp are not included in the export.
+ For existing items, updates or deletions that occur after the cutoff time may not be reflected in the exported data.
+ The timestamp represents when domain processing begins, not when the export request was received.
If you perform multiple exports over time, you may need to implement deduplication logic when processing the exported data to handle items that appear in multiple exports.
# List Exports in an Account
You can list all exports in your AWS account using the `list-exports` command:
```
aws simpledbv2 list-exports
```
The command returns a list of export summaries:
```
{
"exportSummaries": [
{
"exportArn": "arn:aws::sdb:us-east-1:111122223333:domain/myDomain/export/3677e7cd-ca7a-47e2-9d24-2b86115503a6",
"exportStatus": "SUCCEEDED",
"requestedAt": "2026-02-03T13:32:04.394000+00:00",
"domainName": "myDomain"
},
{
"exportArn": "arn:aws::sdb:us-east-1:111122223333:domain/myDomain/export/2890f3b6-a683-4277-adb6-c76a9b434b75",
"exportStatus": "FAILED",
"requestedAt": "2026-02-03T13:38:00.347000+00:00",
"domainName": "myDomain"
},
{
"exportArn": "arn:aws::sdb:us-east-1:111122223333:domain/myDomain/export/6f7ed325-e8cc-4ffe-aa56-b4f6fa8a0fc5",
"exportStatus": "SUCCEEDED",
"requestedAt": "2026-02-06T11:57:09.953000+00:00",
"domainName": "myDomain"
}
]
}
```
## Filtering and Pagination
You can filter the list of exports by domain name:
```
aws simpledbv2 list-exports \
--domain-name 'myDomain'
```
To limit the number of results returned, use the `--max-results` parameter:
```
aws simpledbv2 list-exports \
--max-results 10
```
If there are more results available, the response includes a `nextToken` field. Use this token in a subsequent request to retrieve the next page of results:
```
aws simpledbv2 list-exports \
--next-token 'AQICAHjER8iQpbgPvrZjCyvsE2xN8rcQnvjivIKJidDDXMn1vQ...'
```
## Data Retention
The `list-exports` command returns information about exports created within the past 3 months. Older export metadata is automatically removed from the system, although the exported data files remain in your Amazon S3 bucket until you delete them.
## Understanding Exported Data in Amazon S3
When an export completes successfully, Amazon SimpleDB creates a structured directory in your Amazon S3 bucket containing the exported data and metadata files.
### Directory Structure
The exported data is organized in the following directory structure:
```
AWSSimpleDB///
├── _started
├── data/
│ ├── dataFile_1_2.json
│ ├── dataFile_3_4.json
│ └── ...
├── manifest-file.json
└── manifest-summary.json
```
\$1started
An empty marker file created at the beginning of the export to verify bucket write access.
data/
Directory containing one or more JSON files with the exported domain data. File names include random partition identifiers.
manifest-file.json
Metadata file listing all data files with their MD5 checksums and item counts.
manifest-summary.json
Summary file containing export metadata and total item count.
### Data File Format
Each data file in the `data/` directory contains an array of JSON objects, where each object represents a Amazon SimpleDB item. The following example shows the structure:
```
[
{
"itemName": "employee1",
"attributes": [
{"name": "first_name", "values": ["John"]},
{"name": "last_name", "values": ["Doe"]},
{"name": "department", "values": ["IT"]},
{"name": "age", "values": ["30"]}
]
},
{
"itemName": "employee2",
"attributes": [
{"name": "first_name", "values": ["Jane"]},
{"name": "last_name", "values": ["Smith"]},
{"name": "department", "values": ["HR"]},
{"name": "reportees", "values": ["Jade", "Judith"]}
]
}
]
```
Each item object contains:
+ `itemName` – The unique identifier for the item in the domain
+ `attributes` – An array of attribute objects, each containing:
+ `name` – The attribute name
+ `values` – An array of values (supporting multi-value attributes)
For more information about the Amazon SimpleDB data model, see [Data Model](DataModel.md).
### Manifest Files
The manifest files provide metadata about the export and enable data integrity verification.
#### manifest-file.json
This file lists all data files in the export with their checksums:
```
[
{
"md5Checksum": "ccc3dIp/7887Xhl7+DaEBQ==",
"dataFileS3Key": "AWSSimpleDB/3eb4eaed-872b-4e08-b4b6-ff6999a83e01/myDomain/data/dataFile_1_2.json",
"dataFileItemCount": 500
},
{
"md5Checksum": "xyz9aKl/3456Pqr8+EbFCR==",
"dataFileS3Key": "AWSSimpleDB/3eb4eaed-872b-4e08-b4b6-ff6999a83e01/myDomain/data/dataFile_3_4.json",
"dataFileItemCount": 500
}
]
```
Use the MD5 checksums to verify the integrity of each data file after download.
#### manifest-summary.json
This file provides a summary of the entire export:
```
{
"version":"2025-11-01",
"exportArn":"arn:aws::sdb:us-east-1:111122223333:domain/myDomain/export/a49f3ffd-4b7e-4720-8f5d-f4536313aaf5",
"requestedAt":"2026-02-16T16:56:43.659Z",
"s3BucketName":"myBucket",
"s3ExportPrefix":"AWSSimpleDB/a49f3ffd-4b7e-4720-8f5d-f4536313aaf5/myDomain",
"domainName":"myDomain",
"itemsCount":4650,
"exportDataCutoffTime":"2026-02-16T16:58:35.009Z",
"s3SseAlgorithm":null,
"s3SseKmsKeyId":null,
"s3BucketOwner":"111122223333"
}
```
Use the `totalItemCount` to verify that all items were exported successfully.
# Log Amazon SimpleDB export calls with AWS CloudTrail
Amazon SimpleDB integrates with AWS CloudTrail to provide comprehensive logging of export-related API calls. This integration helps you track who performed export operations, when they occurred, and what parameters were used.
AWS CloudTrail is an AWS service that helps you audit your AWS account. AWS CloudTrail is turned on for your AWS account when you create it. For more information about AWS CloudTrail, see the [AWS CloudTrail User Guide](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/). All export-related Amazon SimpleDB actions are logged by AWS CloudTrail. AWS CloudTrail provides a record of actions related to an export taken by a user, role, or an AWS service in Amazon SimpleDB.
AWS CloudTrail captures export API calls for Amazon SimpleDB as events. An *event* represents a single request from any source and includes information about the requested action, the date and time of the action, request parameters, and so on.
The following example shows a AWS CloudTrail log entry that demonstrates the `StartDomainExport` action:
```
{
"eventVersion": "1.11",
"userIdentity": {
"type": "AssumedRole",
"principalId": "AIDACKCEVSQ6C2EXAMPLE",
"arn": "arn:aws::sts::111122223333:assumed-role/cloudtrail-test-role-iad/i-1234567890abcdef0",
"accountId": "111122223333",
"accessKeyId": "AKIAIOSFODNN7EXAMPLE",
"sessionContext": {
"sessionIssuer": {
"type": "Role",
"principalId": "AIDACKCEVSQ6C2EXAMPLE",
"arn": "arn:aws::iam::111122223333:role/cloudtrail-test-role-iad",
"accountId": "111122223333",
"userName": "cloudtrail-test-role-iad"
},
"attributes": {
"creationDate": "2025-07-10T08:39:45Z",
"mfaAuthenticated": "false"
}
}
},
"eventTime": "2025-07-10T09:15:13Z",
"eventSource": "sdb.amazonaws.com",
"eventName": "StartDomainExport",
"awsRegion": "us-east-1",
"sourceIPAddress": "192.0.2.1",
"userAgent": "aws-cli/2.13.5",
"requestParameters": {
"clientToken": "59d2024d-5ae0-4fda-baf7-880222f29b7b",
"domainName": "myProductionDomain",
"s3Bucket": "my-export-bucket"
},
"responseElements": {
"clientToken": "59d2024d-5ae0-4fda-baf7-880222f29b7b",
"exportArn": "arn:aws::sdb:us-east-1:111122223333:domain/myProductionDomain/export/45abe2ef-87ca-4a59-9f9a-c176d12c0bf9",
"requestedAt": "Jul 10, 2025, 9:15:13 AM"
},
"requestID": "ca2b69d4-3c2f-e8f8-be99-efe0d1f6675a",
"eventID": "777f9823-07ba-4b8c-aa87-20985ffce95f",
"readOnly": false,
"resources": [
{
"accountId": "111122223333",
"type": "AWS::SDB::Domain",
"ARN": "arn:aws::sdb:us-east-1:111122223333:domain/myProductionDomain"
},
{
"accountId": "111122223333",
"type": "AWS::SDB::Domain::DomainExport",
"ARN": "arn:aws::sdb:us-east-1:111122223333:domain/myProductionDomain/export/45abe2ef-87ca-4a59-9f9a-c176d12c0bf9"
}
],
"eventType": "AwsApiCall",
"managementEvent": true,
"recipientAccountId": "111122223333",
"eventCategory": "Management",
"tlsDetails": {
"tlsVersion": "TLSv1.3",
"cipherSuite": "TLS_AES_256_GCM_SHA384",
"clientProvidedHostHeader": "sdb.us-east-1.amazonaws.com"
}
}
```
Key elements in this AWS CloudTrail log entry include:
+ *eventName*: The API action that was called (StartDomainExport)
+ *eventTime*: When the API call occurred
+ *userIdentity*: Information about the user or role that made the call
+ *requestParameters*: The parameters passed to the API call
+ *responseElements*: Key information returned by the API call
# Best Practices for Domain Exports
Consider these best practices to ensure successful exports and efficient use of the export feature.
## Plan for Asynchronous Processing
Domain exports are designed for migration and archival use cases, not real-time data access. Exports run asynchronously and may take time to complete depending on the size of your domain. Check the export status regularly using the `get-export` command rather than expecting immediate completion.
## Consider Domain Lifecycle Management
Domain deletion is blocked while any export for that domain is in PENDING or IN\$1PROGRESS status. If you plan to delete a domain, ensure all exports have completed (SUCCEEDED or FAILED status) before attempting deletion. You can use the `list-exports` command with a domain filter to check for active exports.
## Understand Export Strategy
All exports are full, non-incremental snapshots of your domain data. Every export contains the complete dataset, not just changes since the last export. Plan your export frequency accordingly, considering both storage costs and the time required to process full exports.
## Stay Within Rate Quotas
Amazon SimpleDB enforces the following rate quotas for export operations:
+ 5 exports per domain within a rolling 24-hour window
+ 25 exports per AWS account within a rolling 24-hour window
Plan your export schedule to stay within these limits. If you need to export multiple domains, distribute the exports over time to avoid hitting the account-level quota.
## Manage Cost Considerations
Amazon SimpleDB does not charge for export operations, but Amazon S3 costs apply to the exported data:
+ **Storage costs** - You pay for storing the exported data in Amazon S3 according to standard Amazon S3 pricing.
+ **API call costs** - Amazon S3 charges for PUT requests made during the export process.
+ **Data transfer costs** - Standard Amazon S3 data transfer pricing applies, especially for cross-Region exports.
The JSON format adds metadata overhead, so exported data size is larger than the raw Amazon SimpleDB data size. A domain approaching the 10 GB limit may export to well over 10 GB in Amazon S3. Repeated full exports can accumulate storage costs quickly, so consider implementing a lifecycle policy to archive or delete old exports.
For more information about Amazon S3 pricing, see [Amazon S3 Pricing](https://aws.amazon.com/s3/pricing/).
## Follow Security Best Practices
Exported data in Amazon S3 should be protected using the same security measures you apply to other sensitive data:
+ Enable default encryption on your Amazon S3 bucket using SSE-S3 or SSE-KMS
+ Configure bucket policies to restrict access to authorized users and services
+ Enable Amazon S3 bucket versioning to protect against accidental deletion
+ Use Amazon S3 access logging to track access to exported data
+ Apply least-privilege IAM policies for users and roles that access exported data
For more information about Amazon S3 security, see [ Security best practices for Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/security-best-practices.html) in the *Amazon S3 User Guide*.
## Verify Data Integrity
After an export completes, verify the integrity and completeness of the exported data:
+ Check the `totalItemCount` in `manifest-summary.json` against the expected number of items in your domain
+ Verify the MD5 checksums in `manifest-file.json` for each data file after downloading
+ Confirm that the sum of `dataFileItemCount` values in `manifest-file.json` matches the `totalItemCount`
These verification steps ensure that the export completed successfully and that no data was corrupted during the export or transfer process.
## Handle Export Failures
If an export fails, Amazon SimpleDB does not automatically clean up partial data that may have been written to your Amazon S3 bucket. You are responsible for manually cleaning up any partial export data to avoid unnecessary storage costs.
When an export fails:
1. Use the `get-export` command to retrieve the `failureCode` and `failureMessage`
1. Address the underlying issue (such as insufficient permissions or bucket access problems)
1. Check your Amazon S3 bucket for partial export data and delete it if present
1. Start a new export after resolving the issue