All Products
Search

This Product

    PolarDB:Compatibility and limitations

    Document Center

    PolarDB:Compatibility and limitations

    Last Updated:Jun 18, 2026

    PolarDB for PostgreSQL is highly compatible with mainstream Amazon DynamoDB APIs. Before you use this feature or perform a data migration, read this section carefully to understand its scope of compatibility, limitations, and behavioral differences. This helps ensure your service runs smoothly.

    Compatibility assessment tool: polardb_ddb_code_digest

    PolarDB provides the compatibility assessment tool, polardb_ddb_code_digest.tar.gz, to help you assess the compatibility of your existing projects with PolarDB.

    How it works

    image

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

    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 lists the APIs, parameters, and call frequencies used by your project.

    You can use this report to perform a self-assessment against the limitations described in this document.

    Procedure

    1. Download the compatibility assessment tool polardb_ddb_code_digest.tar.gz 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 a later version installed.

      2. (Optional) To isolate project dependencies and prevent conflicts with global packages, you can 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 lists the key functional and behavioral differences between PolarDB and native DynamoDB.

    General limitations

    • Deprecated parameters: This feature follows recent API specifications. The system ignores or returns an error for deprecated parameters from older versions, such as AttributeUpdates, Expected, or AttributesToGet. Ensure your application uses the corresponding new parameters, such as UpdateExpression, ConditionExpression, or ProjectionExpression.

    • Error messages: The error messages returned for some operations may differ from native DynamoDB's.

    • Statistics and billing parameters: All request parameters and response fields related to billing and capacity consumption, such as the ReturnConsumedCapacity parameter and the ConsumedCapacity field, are ignored or omitted.

    • Index projection: When you specify projected attributes (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.

    API-specific behavioral differences

    • UpdateItem

      • If you use REMOVE a.b to remove a nested attribute that does not exist (that is, the parent attribute a does not exist), native DynamoDB returns an error. In contrast, PolarDB succeeds silently and performs no operation.

    • BatchWriteItem

      • Atomicity: Batch writes in PolarDB are atomic operations, which means that all operations within a request either all succeed or all fail. Therefore, the UnprocessedItems field in the response will always be empty.

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

    • BatchGetItem

      • Atomicity: Similar to a batch write, a batch read is also an atomic operation. Therefore, the UnprocessedKeys field in the returned result will always be empty.

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

    • Query/Scan

      • In the response, ScannedCount is always equal to Count. The system 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 allows these operations.

      • A TransactionCanceledException currently only includes the reasons ConditionalCheckFailed and TransactionConflict. The reasons ItemCollectionSizeLimitExceeded, ProvisionedThroughputExceeded, and ThrottlingError do not occur in PolarDB. PolarDB throws any ValidationError as a CommonError instead of including it as a reason within a TransactionCanceledException.

    Commands and parameters

    Note

    • Supported column:

      • Yes: The parameter is supported.

      • No: The parameter is not supported.

    • Notes column: Explains parameters that are unsupported or have special behaviors.

    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

    Ignored if specified.

    ResourcePolicy

    No

    No

    Ignored if specified.

    SSESpecification

    No

    No

    Ignored if specified.

    Note

    For encryption, use Transparent Data Encryption (TDE).

    StreamSpecification

    No

    No

    Ignored if specified.

    Note

    For stream replication, use subscription management.

    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 parameters

    TableName

    Yes

    Yes

    -

    Response parameters

    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 name

    Parameter 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 returns an error.

    MultiRegionConsistency

    No

    No

    Including this parameter returns an error.

    OnDemandThroughput

    No

    No

    This parameter is ignored.

    ProvisionedThroughput

    No

    No

    This parameter is ignored.

    ReplicaUpdates

    No

    No

    Including this parameter returns an error.

    SSESpecification

    No

    No

    This parameter is ignored.

    Note

    If you require encryption, use Set transparent data encryption (TDE).

    StreamSpecification

    No

    No

    This parameter is ignored.

    Note

    If you require 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

    Parameter 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

    This parameter is ignored.

    ReturnItemCollectionMetrics

    No

    Yes

    -

    ReturnValues

    No

    Yes

    -

    ReturnValuesOnConditionCheckFailure

    No

    Yes

    -

    response parameters

    Attributes

    -

    Yes

    -

    ConsumedCapacity

    -

    No

    This parameter is not returned.

    ItemCollectionMetrics

    -

    Yes

    -

    UpdateItem

    API name

    Parameter type

    Parameter

    Required

    Supported

    Notes

    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 billing-related parameter is ignored.

    ReturnItemCollectionMetrics

    No

    Yes

    -

    ReturnValues

    No

    Yes

    -

    ReturnValuesOnConditionCheckFailure

    No

    Yes

    -

    UpdateExpression

    No

    Yes

    -

    response parameter

    Attributes

    -

    Yes

    -

    ConsumedCapacity

    -

    No

    This billing-related 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

    This billing-related parameter is ignored.

    response parameters

    ConsumedCapacity

    -

    No

    This billing-related parameter is not returned.

    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

    The API ignores this billing-related parameter.

    ReturnItemCollectionMetrics

    No

    Yes

    -

    ReturnValues

    No

    Yes

    -

    ReturnValuesOnConditionCheckFailure

    No

    Yes

    -

    Response parameters

    Attributes

    -

    Yes

    -

    ConsumedCapacity

    -

    No

    The API does not return this billing-related parameter.

    ItemCollectionMetrics

    -

    Yes

    -

    BatchWriteItem

    API name

    Type

    Parameter

    Required

    Supported

    Description

    BatchWriteItem

    request parameters

    RequestItems

    Yes

    Yes

    -

    ReturnConsumedCapacity

    No

    No

    This billing-related parameter is ignored.

    ReturnItemCollectionMetrics

    No

    Yes

    -

    response parameters

    ConsumedCapacity

    -

    No

    This billing-related parameter is not returned.

    ItemCollectionMetrics

    -

    Yes

    -

    UnprocessedItems

    -

    Yes

    This parameter behaves differently: it is always 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 name

    Parameter type

    Parameter name

    Required

    Supported

    Notes

    BatchGetItem

    request parameters

    RequestItems

    Yes

    Yes

    -

    ReturnConsumedCapacity

    No

    No

    The service ignores this billing-related parameter.

    response parameters

    ConsumedCapacity

    -

    No

    The service does not return this billing-related parameter.

    Responses

    -

    Yes

    -

    UnprocessedKeys

    -

    Yes

    This parameter is always returned empty. Refer to the limitations section for details.

    Parameter

    Nested parameter

    Required

    Supported

    Notes

    RequestItems

    ConsistentRead

    No

    Yes

    -

    ExpressionAttributeNames

    No

    Yes

    -

    Keys

    Yes

    Yes

    -

    ProjectionExpression

    No

    Yes

    -

    AttributesToGet

    No

    No

    Deprecated. Use ProjectionExpression instead. 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. Please 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 instead.

    Limit

    No

    Yes

    -

    ProjectionExpression

    No

    Yes

    -

    QueryFilter

    No

    No

    Deprecated. Please use FilterExpression.

    ReturnConsumedCapacity

    No

    No

    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

    The behavioral difference is that it is always equal to ScannedCount.

    Items

    -

    Yes

    -

    LastEvaluatedKey

    -

    Yes

    -

    ScannedCount

    -

    Yes

    -

    Scan

    API name

    Parameter 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

    No

    This billing-related parameter is ignored.

    ScanFilter

    No

    No

    Deprecated. Use FilterExpression instead.

    Segment

    No

    No

    Unsupported. Including this parameter in a request will cause an error.

    Select

    No

    Yes

    -

    TotalSegments

    No

    Yes

    -

    Response parameters

    ConsumedCapacity

    -

    No

    The service does not return this billing-related parameter.

    Count

    -

    Yes

    Behavior differs: Its value always matches ScannedCount.

    Items

    -

    Yes

    -

    LastEvaluatedKey

    -

    Yes

    -

    ScannedCount

    -

    Yes

    -

    TransactWriteItems

    API name

    Parameter type

    Parameter name

    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

    Notes

    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

    Type

    Parameter

    Required

    Supported

    Notes

    UpdateTimeToLive

    Request

    TableName

    Yes

    Yes

    -

    Request

    TimeToLiveSpecification

    Yes

    Yes

    -

    Response

    TimeToLiveSpecification

    -

    Yes

    -

    Parameter

    Nested parameter

    Required

    Supported

    Notes

    TimeToLiveSpecification

    AttributeName

    Yes

    Yes

    -

    Enabled

    Yes

    Yes

    -

    TagResource

    API

    Parameter type

    Parameter

    Required

    Supported

    Notes

    TagResource

    Request parameters

    ResourceArn

    Yes

    Yes

    From the TableArn field in TableDescription.

    Tags

    Yes

    Yes

    -

    UntagResource

    API

    Parameter type

    Parameter

    Required

    Supported

    Notes

    UntagResource

    Request parameters

    ResourceArn

    Yes

    Yes

    From the TableArn field in TableDescription.

    TagKeys

    Yes

    Yes

    -

    ListTagsOfResource

    API

    Parameter type

    Parameter

    Required

    Supported

    Notes

    ListTagsOfResource

    Request parameters

    ResourceArn

    Yes

    Yes

    From the TableArn field in TableDescription.

    NextToken

    No

    Yes

    -

    Response parameters

    Tags

    -

    Yes

    -

    NextToken

    -

    Yes

    -

    Specific functional differences

    The following table lists DynamoDB feature categories that differ substantially from the PolarDB architecture. These features are implemented through dedicated APIs in DynamoDB, while PolarDB provides equivalent solutions through its platform capabilities or the PostgreSQL ecosystem.

    Feature category

    DynamoDB interfaces/parameters

    PolarDB equivalent

    Billing

    BillingMode, ProvisionedThroughput, OnDemandThroughput, WarmThroughput, ReturnConsumedCapacity, ConsumedCapacity

    Billing model differs from DynamoDB. Related parameters are automatically ignored when configured.

    Elastic scaling

    DescribeTableReplicaAutoScaling, UpdateTableReplicaAutoScaling, DescribeLimits

    Elastic scaling through Serverless and specification changes.

    PartiQL queries

    ExecuteStatement, ExecuteTransaction, BatchExecuteStatement

    Supports both DynamoDB interfaces and standard PostgreSQL SQL for complex queries.

    Backup and restore

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

    Periodic automatic backups, instant manual backups, and point-in-time recovery (PITR).

    Global tables

    CreateGlobalTable, DescribeGlobalTable, DescribeGlobalTableSettings, ListGlobalTables, UpdateGlobalTable, UpdateGlobalTableSettings

    Cross-region data synchronization and local reads through Global Database Network (GDN).

    Server-side encryption

    SSESpecification (in CreateTable/UpdateTable)

    Static data encryption through Transparent Data Encryption (TDE).

    DynamoDB Streams

    DescribeStream, GetShardIterator, GetRecords, ListStreams, StreamSpecification

    Incremental data subscription and downstream consumption based on PostgreSQL native logical replication.

    S3 import and export

    ImportTable, ExportTableToPointInTime, DescribeExport, DescribeImport, ListExports, ListImports

    HTAP capabilities (built-in In-Memory Column Index (IMCI)) enable online analytical queries without ETL to a separate analytics system. Alternatively, you can use DTS, OSS foreign tables, or logical replication for integration with MaxCompute, AnalyticDB, and EMR.

    Resource policies

    GetResourcePolicy, PutResourcePolicy, DeleteResourcePolicy, ResourcePolicy parameter

    Fine-grained access control through Alibaba Cloud RAM, and PostgreSQL native user and permission system for the data plane.

    Kinesis streaming

    DescribeKinesisStreamingDestination, EnableKinesisStreamingDestination, DisableKinesisStreamingDestination, UpdateKinesisStreamingDestination

    Streaming data integration through DTS data synchronization or PostgreSQL native logical replication.

    Contributor insights

    DescribeContributorInsights, UpdateContributorInsights, ListContributorInsights

    SQL insights, performance monitoring, and slow query analysis through Database Autonomy Service (DAS).

    Service endpoint query

    DescribeEndpoints

    Query cluster DynamoDB endpoints through OpenAPI - DescribeDBClusterEndpoints.