Compatibility and limitations

更新时间:
复制 MD 格式

PolarDB for PostgreSQL and are highly compatible with the main Amazon DynamoDB APIs. Before using this feature or migrating data, be sure to carefully review this section to understand the scope of compatibility, limitations, and behavioral differences. This ensures your service can run smoothly and reliably.

Compatibility assessment tools

To help you efficiently assess the compatibility of your projects with PolarDB, PolarDB provides two assessment tools. You can choose either one based on your development environment:

  • (Recommended) AI-powered assessment skill (dynamodb-compat-checker):

    • Skill package: dynamodb-compat-checker.zip

    • An intelligent analysis skill built on AI coding agents. The AI directly reads and understands your project source code to produce a complete compatibility assessment and migration recommendation report.

  • Local static code analysis tool (polardb_ddb_code_digest):

    • Analysis tool: polardb_ddb_code_digest.tar.gz

    • A traditional local static scanning tool that extracts API usage based on keywords and syntax rules, generating an API usage report for you to evaluate against this document.

Tool selection guidance

We recommend using the AI-powered assessment skill first. If your development environment includes an AI coding assistant that supports skills (agent skills), such as Qoder, Claude Code, or Codex, we recommend using dynamodb-compat-checker directly. Its advantages include:

  • Unrestricted language coverage: It does not rely on preset language parsers and can analyze projects written in any language, including Go, Python, Java, and JavaScript/TypeScript, as well as any version of the AWS SDK (including high-level wrappers such as DocumentClient and Enhanced Client).

  • Better understanding, more accurate results: The AI can trace wrapper classes, indirect calls, and parameter construction logic in your project, identifying usage patterns that static keyword matching would miss. This effectively reduces false positives and false negatives.

  • Directly actionable conclusions: In addition to listing the APIs and parameters used, the skill automatically cross-references the PolarDB compatibility matrix and provides migration conclusions, items that require action, behavioral difference alerts, and migration recommendations. You do not need to manually evaluate each item against this document.

If your environment does not have an AI coding assistant available, consider using the local static code analysis tool polardb_ddb_code_digest. Note that the static tool has certain limitations: limited language coverage (currently only Go and Python), and it relies on static keyword matching, which may produce false positives or false negatives for wrapped calls and dynamic semantics. Its output is an API usage list only, and you still need to evaluate it against the limitation lists in this document.

(Recommended) AI-powered assessment skill: dynamodb-compat-checker

How it works

  1. Code scan: After loading this skill, the AI coding assistant directly reads and understands your project source code, locating DynamoDB client creation patterns and all API call sites (including wrapper classes and indirect calls), regardless of programming language or SDK version.

  2. Compatibility comparison: The scanned APIs, parameters, and return fields are compared item by item against the PolarDB compatibility matrix to identify unsupported items, deprecated parameters, and behavioral differences.

  3. Report generation: A structured compatibility assessment report dynamodb_api_analysis_[project_name].md is automatically generated, containing migration conclusions, items that require action, behavioral difference alerts, and migration recommendations. The report records only metadata such as API names and parameter names, and does not contain any business data values.

Usage instructions

  1. Download the AI-powered assessment skill package.

  2. Extract the package and place the dynamodb-compat-checker directory into the skill directory of your AI coding assistant (the exact path depends on the product, for example, the project-level skill directory .qoder/skills/ or .claude/skills/).

  3. Open the project to be assessed in your AI coding assistant and send an instruction, for example:

    Please scan the DynamoDB API usage in the current project and generate a compatibility assessment report with PolarDB.
  4. After the assessment is complete, view the generated report dynamodb_api_analysis_[project_name].md in the project root directory.

Local static code analysis tool: polardb_ddb_code_digest

How it works

image
  1. Code scan: The tool recursively scans the specified project directory to identify and parse source files. It currently supports Go and Python.

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

  3. Report generation: The tool sanitizes the collected information by removing all business data values, aggregates the statistics, and generates a structured API usage report. This report clearly lists the APIs and parameters used by your project and their call frequencies.

You can use this report to assess your project's compatibility against the limitation lists in this document.

Usage instructions

  1. Download the local static code analysis tool to your application environment.

  2. Extract the package, navigate to the extracted directory, and run the following commands to install the project dependencies.

    1. Ensure you have Python 3.9.6 or later installed.

    2. (Optional) To isolate project dependencies and prevent conflicts with global packages, create and activate a virtual environment.

      python3 -m venv venv && source venv/bin/activate
    3. Install the project dependencies.

      pip3 install -r requirements.txt
  3. Scan the source files:

    • For a directory of Python source files: python3 main.py --dir <path/to/dir> --lang python > scan_output.log

    • For a directory of Go source files: python3 main.py --dir <path/to/dir> --lang go > scan_output.log

Limitations and behavioral differences

This section outlines the main functional and behavioral differences between PolarDB and native DynamoDB.

General limitations

  • Deprecated parameters: PolarDB adheres to recent API specifications. It ignores or returns an error for deprecated parameters from older versions, such as AttributeUpdates, Expected, or AttributesToGet. Ensure your application uses the corresponding newer parameters, such as UpdateExpression, ConditionExpression, or ProjectionExpression.

  • Error messages: Error messages for some operations may differ from those of native DynamoDB.

  • Statistics and billing parameters: PolarDB accepts request parameters such as ReturnConsumedCapacity, but because PolarDB uses a different billing mode from DynamoDB, these parameters are automatically ignored. The returned ConsumedCapacity field does not fully align with AWS DynamoDB capacity unit semantics. It reflects only the actual read and write behavior on the PolarDB side and is not used for billing purposes.

  • Index projection: When you specify projected attributes (NonKeyAttributes) for a secondary index, the projected fields cannot include the table's primary key (partition key and sort key) or the index's own primary key.

API-specific behavioral differences

  • UpdateItem

    • When using REMOVE a.b to remove a nested attribute whose parent attribute a does not exist, native DynamoDB returns an error. In contrast, PolarDB silently ignores the operation.

  • BatchWriteItem

    • Atomicity: A batch write in PolarDB is an atomic operation. This means all operations within a request either succeed or fail together. As a result, the UnprocessedItems field in the response is always empty.

    • Primary key conflict: Native DynamoDB does not allow PutItem and DeleteItem operations on the same primary key in a single request. PolarDB, however, currently allows such operations.

  • BatchGetItem

    • Atomicity: Similar to a batch write, a batch read is an atomic operation. Consequently, the UnprocessedKeys field in the response is always empty.

    • Duplicate primary key: Native DynamoDB does not allow a request to include duplicate primary keys. PolarDB allows duplicate primary keys and returns one item for each.

  • Query/Scan

    • In the response, ScannedCount is always equal to Count. PolarDB does not distinguish between the number of items before and after applying a filter (FilterExpression).

  • TransactGetItems/TransactWriteItems

    • Native DynamoDB does not allow multiple operations on the same primary key within a single transaction. However, PolarDB currently permits such operations.

    • A TransactionCanceledException can currently have only two reasons: ConditionalCheckFailed and TransactionConflict. The reasons ItemCollectionSizeLimitExceeded, ProvisionedThroughputExceeded, and ThrottlingError do not occur in PolarDB. Instead of including ValidationError as a reason in a TransactionCanceledException, PolarDB throws a CommonError.

Commands and parameters

Note
  • Supported column:

    • Yes: The parameter is supported.

    • No: The parameter is not supported.

  • Notes column: Provides additional information about unsupported parameters or those with special behavior.

CreateTable

API

Parameter type

Parameter

Required

Supported

Remarks

CreateTable

Request parameters

AttributeDefinitions

Yes

Yes

-

KeySchema

Yes

Yes

-

TableName

Yes

Yes

-

BillingMode

No

No

Ignored if specified.

DeletionProtectionEnabled

No

Yes

-

GlobalSecondaryIndexes

No

Yes

-

LocalSecondaryIndexes

No

Yes

-

OnDemandThroughput

No

No

Ignored if specified.

ProvisionedThroughput

No

Yes

-

ResourcePolicy

No

No

Ignored if specified.

SSESpecification

No

No

Ignored if specified.

Note

Use Transparent Data Encryption (TDE) for encryption.

StreamSpecification

No

No

Ignored if specified.

Note

Use subscription management for stream replication.

TableClass

No

No

Ignored if specified.

Tags

No

No

Ignored if specified.

WarmThroughput

No

No

Ignored if specified.

Response parameters

TableDescription

-

Yes

-

DescribeTable

API

Type

Parameter

Required

Supported

Notes

DescribeTable

Request

TableName

Yes

Yes

-

Response

Table

-

Yes

-

ListTables

API

Type

Parameter

Required

Supported

Notes

ListTables

Request parameters

ExclusiveStartTableName

No

Yes

Limit

No

Yes

Response parameters

LastEvaluatedTableName

Yes

TableNames

Yes

UpdateTable

API

Type

Parameter

Required

Supported

Description

UpdateTable

request parameters

TableName

Yes

Yes

-

AttributeDefinitions

No

Yes

-

BillingMode

No

No

This parameter is ignored.

DeletionProtectionEnabled

No

Yes

-

GlobalSecondaryIndexUpdates

No

Yes

Perform this operation during off-peak hours.

GlobalTableWitnessUpdates

No

No

Including this parameter in the request returns an error.

MultiRegionConsistency

No

No

Including this parameter in the request returns an error.

OnDemandThroughput

No

No

This parameter is ignored.

ProvisionedThroughput

No

No

This parameter is ignored.

ReplicaUpdates

No

No

Including this parameter in the request returns an error.

SSESpecification

No

No

This parameter is ignored.

Note

For encryption, use Set transparent data encryption (TDE).

StreamSpecification

No

No

This parameter is ignored.

Note

For stream replication, use subscription management.

TableClass

No

No

This parameter is ignored.

WarmThroughput

No

No

This parameter is ignored.

response parameters

TableDescription

-

Yes

-

DeleteTable

API

Type

Parameter

Required

Supported

Notes

DeleteTable

request parameters

TableName

Yes

Yes

-

response parameters

TableDescription

-

Yes

-

PutItem

API

Type

Parameter

Required

Supported

Description

PutItem

request parameters

Item

Yes

Yes

-

TableName

Yes

Yes

-

ConditionalOperator

No

No

Deprecated. Use ConditionExpression instead.

ConditionExpression

No

Yes

-

Expected

No

No

Deprecated. Use ConditionExpression instead.

ExpressionAttributeNames

No

Yes

-

ExpressionAttributeValues

No

Yes

-

ReturnConsumedCapacity

No

Yes

Ignored.

ReturnItemCollectionMetrics

No

Yes

-

ReturnValues

No

Yes

-

ReturnValuesOnConditionCheckFailure

No

Yes

-

response parameters

Attributes

-

Yes

-

ConsumedCapacity

-

No

Not returned.

ItemCollectionMetrics

-

Yes

-

UpdateItem

API

Type

Parameter

Required

Supported

Description

UpdateItem

Request parameter

Key

Yes

Yes

-

TableName

Yes

Yes

-

AttributeUpdates

No

No

Deprecated. Use UpdateExpression instead.

ConditionalOperator

No

No

Deprecated. Use UpdateExpression instead.

ConditionExpression

No

Yes

-

Expected

No

No

Deprecated. Use UpdateExpression instead.

ExpressionAttributeNames

No

Yes

-

ExpressionAttributeValues

No

Yes

-

ReturnConsumedCapacity

No

Yes

This parameter is ignored.

ReturnItemCollectionMetrics

No

Yes

-

ReturnValues

No

Yes

-

ReturnValuesOnConditionCheckFailure

No

Yes

-

UpdateExpression

No

Yes

-

Response parameter

Attributes

-

Yes

-

ConsumedCapacity

-

No

This parameter is not returned.

ItemCollectionMetrics

-

Yes

-

GetItem

API

Parameter type

Parameter

Required

Supported

Description

GetItem

request parameters

Key

Yes

Yes

-

TableName

Yes

Yes

-

AttributesToGet

No

No

Deprecated. Use ProjectionExpression instead.

ConsistentRead

No

Yes

-

ExpressionAttributeNames

No

Yes

-

ProjectionExpression

No

Yes

-

ReturnConsumedCapacity

No

Yes

Ignored. This is a billing-related parameter.

response parameters

ConsumedCapacity

-

No

Not returned. This is a billing-related parameter.

Item

-

Yes

-

DeleteItem

API

Type

Parameter

Required

Supported

Description

DeleteItem

request parameters

Key

Yes

Yes

-

TableName

Yes

Yes

-

ConditionalOperator

No

No

Deprecated. Use ConditionExpression instead.

ConditionExpression

No

Yes

-

Expected

No

No

Deprecated. Use ConditionExpression instead.

ExpressionAttributeNames

No

Yes

-

ExpressionAttributeValues

No

Yes

-

ReturnConsumedCapacity

No

Yes

This billing-related parameter is ignored.

ReturnItemCollectionMetrics

No

Yes

-

ReturnValues

No

Yes

-

ReturnValuesOnConditionCheckFailure

No

Yes

-

response parameters

Attributes

-

Yes

-

ConsumedCapacity

-

No

This billing-related parameter is not returned.

ItemCollectionMetrics

-

Yes

-

BatchWriteItem

API name

Parameter type

Parameter name

Required

Supported

Description

BatchWriteItem

request parameters

RequestItems

Yes

Yes

-

ReturnConsumedCapacity

No

Yes

Billing-related parameters are ignored.

ReturnItemCollectionMetrics

No

Yes

-

response parameters

ConsumedCapacity

-

No

Billing-related parameters are not returned.

ItemCollectionMetrics

-

Yes

-

UnprocessedItems

-

Yes

This parameter is always returned empty. See the limitations described above.

Parameter

Second-level parameter

Third-level parameter

Required

Supported

Description

RequestItems

DeleteRequest

Key

Yes

Yes

-

PutRequest

Item

Yes

Yes

-

BatchGetItem

API

Type

Parameter

Required

Supported

Description

BatchGetItem

request parameters

RequestItems

Yes

Yes

-

ReturnConsumedCapacity

No

Yes

This parameter is ignored.

response parameters

ConsumedCapacity

-

No

This parameter is not returned.

Responses

-

Yes

-

UnprocessedKeys

-

Yes

Behavior differs: this parameter is always empty. See the limitations described above for details.

Parameter

Nested parameter

Required

Supported

Description

RequestItems

ConsistentRead

No

Yes

-

ExpressionAttributeNames

No

Yes

-

Keys

Yes

Yes

-

ProjectionExpression

No

Yes

-

AttributesToGet

No

No

Deprecated. Use ProjectionExpression. Including this parameter in a request will cause an error.

Query

API

Type

Parameter

Required

Supported

Description

Query

request parameters

TableName

Yes

Yes

-

AttributesToGet

No

No

Deprecated. Use ProjectionExpression.

ConditionalOperator

No

No

Deprecated. Use FilterExpression.

ConsistentRead

No

Yes

-

ExclusiveStartKey

No

Yes

-

ExpressionAttributeNames

No

Yes

-

ExpressionAttributeValues

No

Yes

-

FilterExpression

No

Yes

-

IndexName

No

Yes

-

KeyConditionExpression

No

Yes

-

KeyConditions

No

No

Deprecated. Use KeyConditionExpression.

Limit

No

Yes

-

ProjectionExpression

No

Yes

-

QueryFilter

No

No

Deprecated. Use FilterExpression.

ReturnConsumedCapacity

No

Yes

This billing-related parameter is ignored.

ScanIndexForward

No

Yes

-

Select

No

Yes

-

response parameters

ConsumedCapacity

-

No

This billing-related parameter is not returned.

Count

-

Yes

This parameter behaves differently: it is always equal to ScannedCount.

Items

-

Yes

-

LastEvaluatedKey

-

Yes

-

ScannedCount

-

Yes

-

Scan

API name

Type

Parameter

Required

Supported

Description

Scan

request parameters

TableName

Yes

Yes

-

AttributesToGet

No

No

Deprecated. Use ProjectionExpression instead.

ConditionalOperator

No

No

Deprecated. Use FilterExpression instead.

ConsistentRead

No

Yes

-

ExclusiveStartKey

No

Yes

-

ExpressionAttributeNames

No

Yes

-

ExpressionAttributeValues

No

Yes

-

FilterExpression

No

Yes

-

IndexName

No

Yes

-

Limit

No

Yes

-

ProjectionExpression

No

Yes

-

ReturnConsumedCapacity

No

Yes

This billing-related parameter is not supported and is ignored if present.

ScanFilter

No

No

Deprecated. Use FilterExpression instead.

Segment

No

No

Unsupported. Including this parameter in a request causes an error.

Select

No

Yes

-

TotalSegments

No

No

Not supported. Including this parameter in a request causes an error.

response parameters

ConsumedCapacity

-

No

This billing-related parameter is not supported and is not returned.

Count

-

Yes

Behavior differs: This value is always equal to ScannedCount.

Items

-

Yes

-

LastEvaluatedKey

-

Yes

-

ScannedCount

-

Yes

-

TransactWriteItems

API

Type

Parameter

Required

Supported

Notes

TransactWriteItems

request parameter

TransactItems

Yes

Yes

-

ClientRequestToken

No

Yes

-

ReturnConsumedCapacity

No

Yes

This billing-related parameter is ignored.

ReturnItemCollectionMetrics

No

Yes

-

response parameter

ConsumedCapacity

-

No

This billing-related parameter is not returned.

ItemCollectionMetrics

-

Yes

-

Parameter

Sub-parameter

Required

Supported

Notes

TransactItems

ConditionCheck

No

Yes

-

Put

No

Yes

-

Update

No

Yes

-

Delete

No

Yes

-

TransactGetItems

API

Type

Parameter

Required

Supported

Description

TransactGetItems

request parameters

TransactItems

Yes

Yes

-

ReturnConsumedCapacity

No

Yes

This billing-related parameter is ignored.

response parameters

ConsumedCapacity

-

No

This billing-related parameter is not returned.

Responses

-

Yes

-

DescribeTimeToLive

API

Type

Parameter

Required

Supported

Description

DescribeTimeToLive

Request parameters

TableName

Yes

Yes

-

Response parameters

TimeToLiveDescription

-

Yes

-

UpdateTimeToLive

API

Parameter type

Parameter

Required

Supported

Notes

UpdateTimeToLive

request parameters

TableName

Yes

Yes

-

request parameters

TimeToLiveSpecification

Yes

Yes

-

response parameters

TimeToLiveSpecification

-

Yes

-

Parameter

Nested parameter

Required

Supported

Notes

TimeToLiveSpecification

AttributeName

Yes

Yes

-

Enabled

Yes

Yes

-

TagResource

API

Type

Parameter

Required

Supported

Description

TagResource

request parameters

ResourceArn

Yes

Yes

This value is the TableArn returned in TableDescription.

Tags

Yes

Yes

-

UntagResource

API

Type

Parameter

Required

Supported

Description

UntagResource

request parameter

ResourceArn

Yes

Yes

This value is from the TableArn field in TableDescription.

TagKeys

Yes

Yes

-

ListTagsOfResource

API

Type

Parameter

Required

Supported

Description

ListTagsOfResource

Request parameters

ResourceArn

Yes

Yes

The ARN of the resource, from the TableArn field in the TableDescription object.

NextToken

No

Yes

-

Response parameters

Tags

-

Yes

-

NextToken

-

Yes

-

Specific feature differences

The following table lists feature categories where PolarDB's architecture differs significantly from DynamoDB. While DynamoDB implements these features through proprietary APIs, PolarDB provides equivalent solutions using its native capabilities or the broader PostgreSQL ecosystem.

Feature category

DynamoDB API/parameter

PolarDB equivalent solution

Billing

BillingMode, ProvisionedThroughput, OnDemandThroughput, WarmThroughput, ReturnConsumedCapacity, ConsumedCapacity

Because the billing mode is different from that of DynamoDB, related parameters do not take effect after configuration and are automatically ignored.

Elasticity

DescribeTableReplicaAutoScaling, UpdateTableReplicaAutoScaling, DescribeLimits

PolarDB provides elasticity through Serverless and instance type scaling.

PartiQL queries

ExecuteStatement, ExecuteTransaction, BatchExecuteStatement

PolarDB is compatible with both DynamoDB APIs and standard PostgreSQL SQL. You can use SQL directly for complex queries.

Backup and recovery

CreateBackup, DeleteBackup, DescribeBackup, ListBackups, RestoreTableFromBackup, RestoreTableToPointInTime, DescribeContinuousBackups, UpdateContinuousBackups

PolarDB supports periodic automatic backups, on-demand manual backups, and point-in-time recovery (PITR). For more information, see Backup and restoration.

Global table

CreateGlobalTable, DescribeGlobalTable, DescribeGlobalTableSettings, ListGlobalTables, UpdateGlobalTable, UpdateGlobalTableSettings

Uses the Global Database Network (GDN) to provide cross-region data synchronization and local reads.

Server-side encryption

SSESpecification (in CreateTable/UpdateTable)

Provides data-at-rest encryption through Transparent Data Encryption (TDE).

DynamoDB Streams

DescribeStream, GetShardIterator, GetRecords, ListStreams, StreamSpecification

This feature uses PostgreSQL native logical replication to enable incremental subscription to data changes and downstream consumption. For more information, see Subscription Management.

S3 Import and Export

ImportTable, ExportTableToPointInTime, DescribeExport, DescribeImport, ListExports, ListImports

Leverages its HTAP capabilities with a built-in columnar index (IMCI) to run analytical queries online without ETL to a separate system. Alternatively, you can integrate with big data ecosystems such as MaxCompute, AnalyticDB, and E-MapReduce (EMR) using Data Transmission Service (DTS), Object Storage Service (OSS) foreign tables, or logical replication.

Resource Policy

GetResourcePolicy, PutResourcePolicy, DeleteResourcePolicy, and the ResourcePolicy parameter

Uses Resource Access Management (RAM) to provide fine-grained access control for Alibaba Cloud accounts. The data plane uses the native PostgreSQL user and permission system.

Kinesis stream integration

DescribeKinesisStreamingDestination, EnableKinesisStreamingDestination, DisableKinesisStreamingDestination, UpdateKinesisStreamingDestination

Provides stream integration through Data Transmission Service (DTS) or native PostgreSQL logical replication.

Contributor Insights

DescribeContributorInsights, UpdateContributorInsights, ListContributorInsights

Provides features like SQL Insights, performance monitoring, and slow SQL analysis through Database Autonomy Service (DAS).

Endpoint discovery

DescribeEndpoints

You can query the cluster's DynamoDB endpoint by using the DescribeDBClusterEndpoints OpenAPI operation.