Tuning AWS DynamoDB

A DynamoDB table’s performance depends on the backend that stores its items, the requests your application sends, and the capacity shared with other tables. Use this article to choose the right tuning surface, run a controlled comparison, and verify the native result. Start with the DynamoDB service profile. It describes the supported operations, numeric precision, transactions, indexes and streams for each backend. A larger database cannot add an operation that the mapping does not support.

Choose the setting and its scope

Backend	Capacity to size	Adapter setting	Important scope
Provisioned Azure Cosmos DB	Dedicated container autoscale maximum, in RU/s	Table-creation tuning tag	Capacity belongs to the physical container.
Serverless Azure Cosmos DB	Consumption capacity and service limits	Select the serverless backend	There is no dedicated autoscale RU band to set.
Google Cloud Firestore	Document operations, index work and storage	Optional blind-update setting	The setting changes eligible update validation and applies when the backend starts.
Google Cloud Spanner	Instance processing units and placement	`SPANNER_NUM_CHANNELS`	Instance capacity is shared by its databases and tables.
Google Cloud Bigtable	Cluster nodes, storage and row distribution	`BIGTABLE_NUM_CHANNELS`	Channels belong to the adapter; nodes belong to the shared cluster.
PostgreSQL	Instance CPU, memory, storage and connections	`T9_POSTGRES_POOL_SIZE`	Each adapter pool consumes part of the database’s total connection budget.

Three different mechanisms appear below:

Resource tuning tags set a supported target field for a resource created through the origin API.
Adapter configuration controls the process that translates requests, such as its connection pool.
Native infrastructure settings size a shared database or cluster through the system that owns that infrastructure.

Keep those scopes in the change record. Setting a table tag must not unexpectedly resize a shared Spanner instance or PostgreSQL database used by unrelated tables.

Try provisioned Cosmos DB locally

This example uses a local Cloud Adapter process and an Azure test environment. The process is local; its Cosmos DB resources and capacity are real Azure resources.

Install the CLI and inspect the mapping

If needed, install the Tensor9 CLI:

brew tap tensor9ine/tensor9
brew install tensor9
tensor9 --version

Inspect the mapping before creating the test table:

tensor9 explain \
  -origin aws::1.0.0::dynamodb::table \
  -target azure::1.0.0::cosmosdb::provisioned \
  -fmt Human

Prepare the Azure subscription, resource group, location and runtime identity described in Configuration Examples. The identity needs the target access required for both resource provisioning and item operations.

Start the DynamoDB adapter

Run the service in a terminal you can leave open:

tensor9 adapt svc run \
  --origin aws::1.0.0::dynamodb::table \
  --backend azure::1.0.0::cosmosdb::provisioned

This starts a local endpoint for DynamoDB table and item requests.

Point your test client at the printed endpoint

In a second terminal, copy the listening endpoint:

export T9_CLOUD_ADAPTER_ENDPOINT="<endpoint printed by tensor9>"
export AWS_ENDPOINT_URL_DYNAMODB="$T9_CLOUD_ADAPTER_ENDPOINT"
export AWS_REGION="us-east-1"

The service-specific endpoint directs DynamoDB calls from this process to the adapter. Keep the origin credentials appropriate to the adapter endpoint; the adapter’s Azure identity is separate.To configure a single client programmatically instead:

import os
import boto3

dynamodb = boto3.client(
    "dynamodb",
    endpoint_url=os.environ["T9_CLOUD_ADAPTER_ENDPOINT"],
    region_name="us-east-1",
)

Create, inspect and exercise a test table

Use the complete request in the next section. Wait for the table to become available, inspect its native Cosmos capacity, then run the point-write and update examples. Record the table name, native container identity, effective throughput and test time together.

Finish the experiment

Delete only the disposable data created for the experiment. Follow the deployment’s resource-ownership policy when removing containers and accounts. Stopping the local process does not stop Azure capacity charges or delete backend data.Press Control-C in the adapter terminal when finished.

Provisioned Cosmos DB: give a table its own capacity

For a table that owns a dedicated Cosmos container, send the backend selector and autoscale maximum in the DynamoDB CreateTable tags. Save this complete request as create-orders.json:

{
  "TableName": "tuning-orders",
  "AttributeDefinitions": [
    { "AttributeName": "tenant_id", "AttributeType": "S" },
    { "AttributeName": "order_id", "AttributeType": "S" }
  ],
  "KeySchema": [
    { "AttributeName": "tenant_id", "KeyType": "HASH" },
    { "AttributeName": "order_id", "KeyType": "RANGE" }
  ],
  "BillingMode": "PAY_PER_REQUEST",
  "Tags": [
    {
      "Key": "t9:backend",
      "Value": "azure::1.0.0::cosmosdb::provisioned"
    },
    {
      "Key": "t9:tuning:container.properties.options.autoscaleSettings.maxThroughput",
      "Value": "40000"
    },
    { "Key": "environment", "Value": "tuning-test" }
  ]
}

aws dynamodb create-table --cli-input-json file://create-orders.json
aws dynamodb wait table-exists --table-name tuning-orders
aws dynamodb describe-table --table-name tuning-orders

The backend selector chooses provisioned Cosmos DB. The tuning path sets the target container’s autoscale maximum to 40,000 RU/s. The value is a string in the AWS tag carrier and a numeric field in the target request. BillingMode: PAY_PER_REQUEST remains an origin-facing DynamoDB setting. It does not make the selected Cosmos account serverless. Likewise, changing DynamoDB provisioned read or write units through UpdateTable does not resize the Cosmos container. 40,000 RU/s is an example capacity budget. Choose the value from measurements of your own item sizes, queries, writes and indexes. The target field uses 1,000-RU/s increments and a minimum of 1,000 RU/s; the actual container’s storage, throughput history and account constraints can require a higher minimum.

The container must belong to this table for the example to provide a per-table capacity budget. Several logical tables sharing a pre-provisioned container share its throughput. Manage that shared container’s capacity with its infrastructure owner; do not treat a logical table tag as an isolated budget.

Inspect the native result

Set these values from the deployment’s actual Azure resource coordinates. An origin table name is not proof of a native container name:

export AZURE_RESOURCE_GROUP="rg-cloud-adapter-dev"
export COSMOS_ACCOUNT="acme-adapter-dev"
export COSMOS_DATABASE="cloud-adapter"
export COSMOS_CONTAINER="<native container for tuning-orders>"

az cosmosdb sql container throughput show \
  --resource-group "$AZURE_RESOURCE_GROUP" \
  --account-name "$COSMOS_ACCOUNT" \
  --database-name "$COSMOS_DATABASE" \
  --name "$COSMOS_CONTAINER" \
  --query resource.autoscaleSettings.maxThroughput \
  --output tsv

For this request, the observed maximum should be 40000. If it differs, keep the create response and the target inspection output and follow Understanding Behavior with Explain. A successful DescribeTable does not independently verify Azure capacity.

Size a second table independently

A small lookup table and a busy orders table need not have the same budget. In a second copy of create-orders.json, change the table name to tuning-reference and the maximum to 4000. Keep a dedicated target container for each table.

Table	Example maximum	Workload to test
`tuning-orders`	40,000 RU/s	Concurrent order writes, status updates and tenant queries
`tuning-reference`	4,000 RU/s	Small point reads with occasional updates

Run each workload alone, then run both together. Inspect both native containers. This checks table-specific sizing and exposes shared account, adapter or network constraints that separate RU budgets cannot remove. Treat global secondary indexes as additional capacity consumers. The provisioned Cosmos mapping uses Azure-managed index containers. Include index storage, index maintenance and index-query traffic in the budget, and use the provisioned Cosmos profile when choosing the table layout.

Compare a point operation with a conditional update

First write and read a small item:

aws dynamodb put-item \
  --table-name tuning-orders \
  --item '{"tenant_id":{"S":"tenant-001"},"order_id":{"S":"order-001"},"status":{"S":"new"},"version":{"N":"1"}}'

aws dynamodb get-item \
  --table-name tuning-orders \
  --key '{"tenant_id":{"S":"tenant-001"},"order_id":{"S":"order-001"}}' \
  --consistent-read

Then exercise a conditional write with a returned image:

aws dynamodb update-item \
  --table-name tuning-orders \
  --key '{"tenant_id":{"S":"tenant-001"},"order_id":{"S":"order-001"}}' \
  --update-expression 'SET #status = :status, #version = :next' \
  --condition-expression '#version = :expected' \
  --expression-attribute-names '{"#status":"status","#version":"version"}' \
  --expression-attribute-values '{":status":{"S":"paid"},":next":{"N":"2"},":expected":{"N":"1"}}' \
  --return-values ALL_NEW

The first conditional update should succeed. Repeating it should fail the version condition because the item now has version 2. That failure is an application concurrency result, not evidence of insufficient RU capacity. Measure unconditional writes, conditional writes, queries and returned images separately. They can perform different native work. Compare latency and request-unit use for the operations the application actually issues.

Diagnose throttling before increasing the maximum

Observation	Next experiment
High utilization and throttling spread across many partition keys	Increase the dedicated container budget in the system that owns its throughput, then repeat the same workload.
One tenant is slow while other tenants have spare capacity	Inspect hot-partition distribution. More total RU/s does not necessarily remove a concentrated partition bottleneck.
Native utilization is low but application latency rises with concurrency	Check adapter CPU, connection queueing and client retries before buying more capacity.
Writes get more expensive after adding indexes	Measure index maintenance and query benefit together.
Origin capacity metadata changes but native throughput does not	Inspect the Cosmos throughput resource. DynamoDB billing metadata is not the native resizing interface.

For an existing container, change throughput through its infrastructure owner and inspect the effective value afterward. Do not assume adding a tag later, repeating CreateTable, or calling UpdateTable is a capacity-update command. Keep the desired configuration synchronized with any native change so a later deployment does not restore an older value.

Serverless Cosmos DB: choose consumption capacity

Use the serverless backend when its consumption model fits the workload. The selector is:

{
  "Key": "t9:backend",
  "Value": "azure::1.0.0::cosmosdb::serverless"
}

This is a tag entry to use in a complete CreateTable request. Omit the provisioned-container autoscale tag. Serverless Cosmos does not have a dedicated autoscale band to reserve, and DynamoDB ProvisionedThroughput does not create one. Compare a quiet period followed by a representative burst with the same workload on provisioned Cosmos. Record successful operations, throttled requests, total retries, end-to-end latency and consumed request units. A low average request rate can hide a burst that exceeds the target’s limits. Choose provisioned Cosmos when the table needs the mapping’s managed global secondary indexes. Do not switch an existing table’s backend tag to move data or change account mode. Create the destination, migrate the data and validate queries and consumers before changing traffic. See Cosmos serverless behavior.

Firestore: tune the update shape

Firestore bills native document work and storage. The adapter’s request shape matters because a write that needs the old item can perform more work than an unconditional write. DynamoDB provisioned capacity settings do not reserve a Firestore read/write budget.

Start with the normal validation behavior

Keep FIRESTORE_ALLOW_OVERSIZED_BLIND_UPDATES absent or set it to the string "false" in the selected service’s configuration. The adapter enforces the resulting DynamoDB item’s 400-KiB limit. Unconditional puts and deletes without return values or Streams can already avoid an item read; eligible top-level REMOVE-only updates can also do so. For a Firestore-backed test table with the same key schema as tuning-orders, compare:

aws dynamodb update-item \
  --table-name tuning-orders \
  --key '{"tenant_id":{"S":"tenant-001"},"order_id":{"S":"order-001"}}' \
  --update-expression 'REMOVE transient_note' \
  --return-values NONE

with a SET update:

aws dynamodb update-item \
  --table-name tuning-orders \
  --key '{"tenant_id":{"S":"tenant-001"},"order_id":{"S":"order-001"}}' \
  --update-expression 'SET #status = :status' \
  --expression-attribute-names '{"#status":"status"}' \
  --expression-attribute-values '{":status":{"S":"packed"}}' \
  --return-values NONE

Use the same initial item in each test. Compare native document reads and writes as well as application latency. A single terminal invocation is a correctness check; repeat the operation under the application’s normal concurrency for a performance comparison. This adapter-configuration fragment enables eligible SET/REMOVE requests to use a masked Firestore write without reading the item first:

{
  "config": {
    "FIRESTORE_ALLOW_OVERSIZED_BLIND_UPDATES": "true"
  }
}

Merge the field into the selected Firestore adapter’s configuration and restart that backend with the updated configuration. This is a process setting, not a CreateTable tag or a process environment variable. Do not add an origin-to-backend declaration merely to repeat the installation’s normal mapping; Configuration Files explains the compact configuration and service-specific settings. The optimized request must meet all these conditions:

Only top-level literal SET and/or REMOVE actions.
No condition expression and ReturnValues=NONE.
Streams disabled.
No changes to the configured TTL attribute, primary key or secondary-index keys.
No local secondary indexes that require checking the combined item and projected index-entry size.

Other request shapes retain their guarded behavior. Enabling this setting does not make arithmetic updates, nested changes or conditional writes into blind writes. The tradeoff is explicit: an eligible patch can grow an item beyond DynamoDB’s 400-KiB limit. Firestore’s native document and index limits still apply. Later validated writes can reject that item. Before restoring strict mode, inspect and shrink oversized items; setting the option back to "false" does not rewrite existing data. Run the same SET workload with the setting off and on. Include a condition-expression case and a returned-image case in both runs to verify that application behavior remains correct. See the Firestore profile for the detailed request restrictions.

Spanner: separate channels from instance capacity

Spanner instance processing units are shared infrastructure capacity. The adapter’s gRPC channels are a separate concurrency control. A table’s DynamoDB RCU/WCU settings do not allocate processing units to that table. The adapter defaults to 32 channels. A configuration fragment for a comparison at 16 channels is:

{
  "config": {
    "SPANNER_NUM_CHANNELS": "16"
  }
}

Apply this field to the selected Spanner adapter configuration and restart the process. Compare 16 with 32 channels at the same instance size, workload and client concurrency. Each process has its own client resources, so include adapter replica count in the experiment.

Batch independent work

For a Spanner-backed test table with the example key schema, save this as batch-orders.json:

{
  "tuning-orders": [
    {
      "PutRequest": {
        "Item": {
          "tenant_id": { "S": "tenant-001" },
          "order_id": { "S": "batch-001" },
          "status": { "S": "new" }
        }
      }
    },
    {
      "PutRequest": {
        "Item": {
          "tenant_id": { "S": "tenant-002" },
          "order_id": { "S": "batch-002" },
          "status": { "S": "new" }
        }
      }
    }
  ]
}

aws dynamodb batch-write-item --request-items file://batch-orders.json

Inspect UnprocessedItems and retry only the remaining work using the application’s retry policy. Batching can amortize native work across independent puts and deletes. It does not provide cross-item atomicity, express conditional writes or replace TransactWriteItems. Include time spent waiting to assemble a batch in end-to-end latency.

Decide when to add processing units

Increase client concurrency gradually while measuring Spanner service utilization and application p95/p99 latency. Add instance capacity when service utilization is the bottleneck. If utilization is low, investigate channels, client queueing, network placement and the operation’s commit path first. Ordinary reads on this mapping are strong even when ConsistentRead=false. Changing that flag does not buy a cheaper consistency mode. Conditional and complex updates can read the item before committing, so a benchmark of simple assignments does not predict their latency. Choose regional or multi-region placement for the failure coverage you need, then measure the application’s actual locations. Connection tuning cannot eliminate cross-region latency. See Spanner behavior and transactions.

Bigtable: distinguish a hot row from a full cluster

Bigtable capacity belongs to the cluster. The adapter uses a connection pool and a single-cluster-routing app profile so its strong-read and conditional-write behavior has a consistent target. The pool defaults to 64 channels and accepts values from 1 through 64. For a smaller workload, compare this configuration with the default:

{
  "config": {
    "BIGTABLE_NUM_CHANNELS": "16"
  }
}

Restart the selected backend after changing the setting. Hold the cluster size and workload constant during the channel comparison. More channels consume process resources; fewer can queue requests before Bigtable receives them. Use two workload cases:

Case	Example keys	What it reveals
Independent items	Many tenants and order IDs	Whether throughput grows with useful concurrency and distributed row access
Contended item	Many clients updating the same tenant/order key	Conflict and retry cost on one row

Measure unconditional puts separately from conditional or returned-image updates. Guarded read-modify-write can repeat when another client changes the row. Adding cluster nodes cannot split a single item’s contention across machines. Use cluster utilization, hottest-node utilization and native service latency to decide whether to add nodes. Adding clusters does not itself enable transparent failover in the adapter’s single-cluster route. The Bigtable profile also identifies the transaction, index, stream and TTL differences that capacity tuning cannot change.

PostgreSQL: budget the shared connection pool

The PostgreSQL backend is available through Cloud SQL, Scaleway Managed PostgreSQL, and PostgreSQL operated with the deployment. They share the DynamoDB adapter’s PostgreSQL request behavior; their database provisioning and operations differ. Provision the database dependency before starting the adapter, and keep its connection coordinates and credentials in their appropriate configuration and secret stores. The compact installation file needs extra service configuration for this dependency, not a redundant declaration of every automatically derived service mapping.

Increase the pool only within the database budget

T9_POSTGRES_POOL_SIZE is a process environment setting. Its default is 8 connections per pool. To compare a 16-connection pool on the Cloud SQL backend:

T9_POSTGRES_POOL_SIZE=16 tensor9 adapt svc run \
  --origin aws::1.0.0::dynamodb::table \
  --backend google::1.0.0::cloudsql::postgresql

Use the database dependency and identity already configured for that backend. The command changes the pool limit; it does not provision or resize Cloud SQL. Calculate the total budget before increasing it:

Consumer	Example allocation
Four adapter processes, one 16-connection pool each	Up to 64 connections
Other applications using the database	20 connections
Administrative and monitoring headroom	16 connections
Planned total	100 connections

This example assumes one pool per process. If a process opens several backend pools, count each one. Include temporary overlap during rolling replacements and connection refresh. Compare the total with the database’s actual connection limit and memory budget.

Match the remedy to the bottleneck

If requests wait for a pool slot while database CPU and storage have headroom, try a modest pool increase.
If database CPU or storage latency is saturated, a larger pool can make tail latency worse. Size the database or reduce work per request.
If many requests contend on the same item, inspect lock waits and retry rates. More connections do not remove the conflict.
If table or index creation overlaps a load spike, include that schema work in capacity planning.

DynamoDB tables become physical PostgreSQL relations. This mapping has a 500-table guardrail per namespace; increasing the database size does not remove it. DynamoDB UpdateTable capacity changes also do not resize the PostgreSQL instance. Back up table metadata, items, index state and stream state together. A throughput improvement is not sufficient if the recovery procedure cannot restore a consistent application view.

Run a repeatable comparison

For every backend, keep one experiment record with the mapping, target identity, resource ownership, requested setting, effective setting and workload. Include the application-visible outcome and the native observation.

Keep fixed	Measure
Initial data, item sizes and key distribution	Successful operations per second
Read/write/query mix and condition expressions	End-to-end p50, p95 and p99 latency
Return values, indexes, streams and TTL	Errors, conflicts, throttling and retries
Client location, adapter replicas and SDK configuration	Adapter CPU, memory and queueing
Warm-up and measurement duration	Native capacity use, storage work and billed units

Change one setting at a time. Repeat the baseline after the tuned run to check whether a warm cache, a background operation or a different load level explains the result. Record the warm-up separately rather than dropping slow startup behavior without explanation. Use request explanations and diagnostic response headers to inspect representative requests. Preserve the explanation reference alongside the measurements. For throughput runs, keep the diagnostic mode and sampling policy consistent so the instrumentation is not another changing variable.

Change and rollback checklist

Identify the owner: table container, shared database, or adapter process.
Save the previous requested and effective settings.
Check whether the change requires a process restart, a native infrastructure operation, or a new destination and data migration.
Apply the change through the owning configuration and wait for readiness.
Verify both the origin request behavior and native target settings.
Compare the same workload and restore the earlier configuration if the result is worse.

Rollback has data consequences in some cases. Disabling Firestore’s relaxed-size updates does not shrink items. Moving between Cosmos account modes or changing backends does not move data. Reducing capacity also does not necessarily remove storage or throughput-history constraints on the native resource. Continue with Tuning Examples, Configuration Examples, and the AWS Service Catalog for related mappings.

Tensor9 Cloud Adapter

How It Works

Getting Started

Configuration

Deployment

Making Trade-offs

Operations

Tuning

Debugging

Testing

Amazon Web Services

Google Cloud

Microsoft Azure

Reference

Guides

Tuning AWS DynamoDB

Choose the setting and its scope

Try provisioned Cosmos DB locally

Provisioned Cosmos DB: give a table its own capacity

Inspect the native result

Size a second table independently

Compare a point operation with a conditional update

Diagnose throttling before increasing the maximum

Serverless Cosmos DB: choose consumption capacity

Firestore: tune the update shape

Start with the normal validation behavior

Opt in to blind SET updates where the size tradeoff fits

Spanner: separate channels from instance capacity

Batch independent work

Decide when to add processing units

Bigtable: distinguish a hot row from a full cluster

PostgreSQL: budget the shared connection pool

Increase the pool only within the database budget

Match the remedy to the bottleneck

Run a repeatable comparison

Change and rollback checklist

​Choose the setting and its scope

​Try provisioned Cosmos DB locally

​Provisioned Cosmos DB: give a table its own capacity

​Inspect the native result

​Size a second table independently

​Compare a point operation with a conditional update

​Diagnose throttling before increasing the maximum

​Serverless Cosmos DB: choose consumption capacity

​Firestore: tune the update shape

​Start with the normal validation behavior

​Opt in to blind SET updates where the size tradeoff fits

​Spanner: separate channels from instance capacity

​Batch independent work

​Decide when to add processing units

​Bigtable: distinguish a hot row from a full cluster

​PostgreSQL: budget the shared connection pool

​Increase the pool only within the database budget

​Match the remedy to the bottleneck

​Run a repeatable comparison

​Change and rollback checklist

Choose the setting and its scope

Try provisioned Cosmos DB locally

Provisioned Cosmos DB: give a table its own capacity

Inspect the native result

Size a second table independently

Compare a point operation with a conditional update

Diagnose throttling before increasing the maximum

Serverless Cosmos DB: choose consumption capacity

Firestore: tune the update shape

Start with the normal validation behavior

Opt in to blind SET updates where the size tradeoff fits

Spanner: separate channels from instance capacity

Batch independent work

Decide when to add processing units

Bigtable: distinguish a hot row from a full cluster

PostgreSQL: budget the shared connection pool

Increase the pool only within the database budget

Match the remedy to the bottleneck

Run a repeatable comparison

Change and rollback checklist