PolarDB:Compatibility and Limits

How it works

1. Code scanning: The tool recursively scans your project directories and parses source files. Go and Python are supported.

2. API analysis: The tool extracts all DynamoDB API calls, parameter names, constants, and expression structures based on the official AWS SDK specifications.

3. Report generation: The tool removes all business data values and generates a structured report listing the APIs, parameters, and their usage frequency in your project.

Use this report to check your API usage against the limits in this topic.

Install and run the tool

Prerequisites

Before you begin, ensure that you have:

• Python 3.9.6 or later

• The project directory containing your Go or Python source files

Steps

1. Download polardb_ddb_code_digest.tar.gz to your application environment.

2. Unzip the file and go to the unzipped directory.

3. (Optional) Create a virtual environment to isolate project dependencies:

   python3 -m venv venv && source venv/bin/activate

4. Install the project dependencies:

   pip3 install -r requirements.txt

5. Scan your source files:

   • Python project: ``bash python3 main.py --dir <path/to/dir> --lang python > scan_output.log ``

   • Go project: ``bash python3 main.py --dir <path/to/dir> --lang go > scan_output.log ``

Deprecated parameters

PolarDB follows the current DynamoDB API specification. Deprecated parameters are not supported. Replace them with their modern equivalents before migrating.

Consistency

PolarDB does not support per-request strong consistency reads (ConsistentRead=true). The consistency level is configured at the DynamoDB endpoint and applies to all requests on that endpoint.

Billing and capacity parameters

All DynamoDB billing and capacity parameters are ignored or not returned. This includes:

• Request parameters ignored: ReturnConsumedCapacity

• Response fields not returned: ConsumedCapacity, ItemCollectionMetrics

• Statistics parameters not supported: ReturnItemCollectionMetrics

Index projections

When specifying NonKeyAttributes for a secondary index, the projected fields cannot include the table's primary key (partition key or sort key) or the index's own primary key.

Atomicity in batch operations

In PolarDB, batch operations are atomic: all operations in a single request either succeed or fail together.

• `BatchWriteItem`: UnprocessedItems in the response is always empty because partial failures do not occur.

• `BatchGetItem`: UnprocessedKeys in the response is always empty for the same reason.

Primary key conflicts in batch and transactional operations

PolarDB and native DynamoDB handle primary key conflicts differently:

Transaction failure behavior

When a TransactWriteItems transaction is canceled because a condition check fails, PolarDB and native DynamoDB behave differently.

Native DynamoDB attempts all operations and then returns the status of each one:

TransactionCanceledException: Transaction cancelled, please refer cancellation reasons for specific reasons [ConditionalCheckFailed, None, ConditionalCheckFailed]

PolarDB aborts immediately at the first failed operation and returns a single error:

ConditionalCheckFailedException: The conditional request failed

Update your error handling logic to account for this difference if your application inspects per-operation failure details.

UpdateItem: removing a non-existent nested attribute

When using REMOVE a.b to remove a nested attribute where the parent attribute a does not exist:

• Native DynamoDB: returns an error.

• PolarDB: silently succeeds and performs no operation.

Query and Scan: ScannedCount and Count

In PolarDB, ScannedCount and Count in the response always have the same value. PolarDB does not differentiate between the number of items scanned before and after a FilterExpression is applied. Native DynamoDB returns different values when a filter reduces the result set.

Error messages

Error messages for some operations may differ from those returned by native DynamoDB.

CreateTable

DescribeTable

ListTables

UpdateTable

DeleteTable

PutItem

UpdateItem

GetItem

DeleteItem

BatchWriteItem

BatchGetItem

Query

Scan

TransactWriteItems

TransactGetItems

DescribeTimeToLive

UpdateTimeToLive