PolarDB PostgreSQL的DynamoDB相容API支援範圍與使用限制-雲原生資料庫 PolarDB-阿里雲 - PolarDB

PolarDB PostgreSQL版提供了對Amazon DynamoDB主流API的高度相容。但在計劃使用或進行資料移轉前，請務必詳細閱讀本章節，以充分瞭解其相容範圍、使用限制和行為差異，確保您的業務能夠平滑、穩定地運行。

相容性評估工具

為了協助您高效評估現有專案與PolarDB的相容性，PolarDB提供了兩種評估工具，您可以根據自身研發環境任選其一：

（推薦）AI 智能評估 Skill（dynamodb-compat-checker）：
- 技能包：dynamodb-compat-checker.zip
- 基於 AI 編程助手（AI Coding Agent）的智能分析技能，由 AI 直接閱讀並理解您的專案源碼，產出完整的相容性評估與遷移建議報告。
本地靜態程式碼分析工具（polardb_ddb_code_digest）：
- 分析工具：polardb_ddb_code_digest.tar.gz
- 傳統的本地靜態掃描工具，基於關鍵字與文法規則提取 API 使用方式，產生 API 使用報告，供您對照本文檔自行評估。

工具選型建議

優先推薦使用 AI 智能評估 Skill。如果您的研發環境中已具備支援 Skill（Agent Skill）機制的 AI 編程助手（如 Qoder、Claude Code、Codex 等），建議直接使用 dynamodb-compat-checker，其優勢包括：

語言覆蓋不受限：不依賴預置的語言解析器，可分析 Go、Python、Java、JavaScript/TypeScript 等任意語言及各版本 AWS SDK（含 DocumentClient、Enhanced Client 等高層封裝）編寫的專案。
理解能力更強、結果更准：AI 能夠追蹤專案中的封裝類、間接調用與參數構造邏輯，識別靜態關鍵字匹配難以覆蓋的用法，有效降低誤判與漏報。
結論直接可用：不僅輸出 API 與參數使用清單，還會自動對照 PolarDB 相容性矩陣，直接給出遷移結論、必須處理項、行為差異提示與遷移建議，無需您再手動對照本文檔逐項評估。

如果您的環境中暫無可用的 AI 編程助手，再考慮使用本地靜態程式碼分析工具 polardb_ddb_code_digest。請注意，靜態工具存在一定局限：語言覆蓋有限（當前僅支援 Go 和 Python），且基於靜態關鍵字匹配，對封裝調用、動態語義等情境可能存在誤判或漏報，其輸出僅為 API 使用清單，仍需您對照本文檔中的限制列表自行完成評估。

（推薦）AI 智能評估 Skill：dynamodb-compat-checker

工作原理

代碼掃描：AI 編程助手載入該 Skill 後，直接閱讀並理解您的專案源碼，定位 DynamoDB 用戶端的建立方式與所有 API 呼叫點（含封裝類與間接調用），不限程式設計語言與 SDK 版本。
相容性比對：將掃描到的 API、參數及返回欄位逐項對照 PolarDB 相容性矩陣，識別不支援項、已廢棄參數與行為差異。
報告產生：自動產生一份結構化的相容性評估報告 dynamodb_api_analysis_[專案名].md，包含遷移結論、必須處理項、行為差異提示與遷移建議。報告僅記錄介面名、參數名等元資訊，不包含任何業務資料值。

使用說明

下載AI智能評估技能包。
解壓後，將 dynamodb-compat-checker 目錄放入您的 AI 編程助手的技能目錄中（以具體產品為準，例如專案級技能目錄 .qoder/skills/ 或 .claude/skills/）。

在 AI 編程助手中開啟待評估的專案，向助手發起指令，例如：

請掃描當前專案的 DynamoDB API 使用方式，並產生與 PolarDB 的相容性評估報告。

評估完成後，在專案根目錄查看產生的報告 dynamodb_api_analysis_[專案名].md。

本地靜態程式碼分析工具：polardb_ddb_code_digest

工作原理

代碼掃描：工具遞迴掃描您指定的專案目錄，識別並解析源碼檔案（當前支援 Go 和 Python）。
API 分析：基於 AWS 官方 SDK 規範，提取所有 DynamoDB 的 API 呼叫、使用的參數名、常量和運算式結構。
報告產生：對收集到的資訊進行脫敏（移除所有業務資料值）和彙總統計，最終產生一份結構化的 API 使用報告。報告清晰地列出您的專案使用了哪些 API、參數及其使用頻率。

您可以依據此報告，對照本文檔中的限制列表進行自我評估。

使用說明

下載本地靜態程式碼分析工具至您的應用環境中。
解壓該檔案並進入解壓後的目錄中，運行以下代碼安裝專案依賴。
1. 已安裝 Python 環境：需為 3.9.6 及以上版本。
2. （可選）根據您的業務環境，可選擇是否建立虛擬環境，用於隔離專案依賴，避免全域汙染。
```
python3 -m venv venv && source venv/bin/activate
```
3. 安裝專案依賴。
```
pip3 install -r requirements.txt
```
識別並解析源碼檔案：
- 源碼檔案為 Python 檔案（檔案夾）：python3 main.py --dir <path/to/dir> --lang python > scan_output.log
- 源碼檔案為 Go 檔案（檔案夾）：python3 main.py --dir <path/to/dir> --lang go > scan_output.log

使用限制與行為差異

為了協助您快速識別關鍵資訊，在此首先列出PolarDB與原生DynamoDB在功能和行為上的主要差異。

通用限制

廢棄參數：本功能遵循較新版本的API規範。對於已廢棄的舊版參數（如AttributeUpdates、Expected或AttributesToGet等），系統會忽略或直接報錯。請確保您的應用程式使用對應的新版參數（如UpdateExpression、ConditionExpression或ProjectionExpression）。
錯誤資訊：部分操作的錯誤響應資訊可能與原生DynamoDB不完全一致。
統計與計費參數：PolarDB相容層會接受ReturnConsumedCapacity等請求參數，但PolarDB計費模式與DynamoDB不同，會自動忽略對應的參數。
索引投影：為二級索引指定投影屬性（NonKeyAttributes）時，投影的欄位不能包含表的主鍵（分區鍵、排序鍵）或該索引自身的主鍵。

API特定行為差異

UpdateItem
- 當使用REMOVE a.b移除一個不存在的嵌套屬性時（即父屬性a不存在），原生DynamoDB會報錯，而PolarDB會靜默成功，不執行任何操作。
BatchWriteItem
- 原子性：PolarDB中的批量寫入是原子操作，即請求內的所有操作要麼全部成功，要麼全部失敗。因此，返回結果中的UnprocessedItems欄位將始終為空白。
- 主鍵衝突：原生DynamoDB不允許在同一次請求中對同一個主鍵執行PutItem和DeleteItem，而PolarDB當前允許此類操作。
BatchGetItem
- 原子性：與批量寫入類似，批量讀取也是原子操作。因此，返回結果中的UnprocessedKeys欄位將始終為空白。
- 主鍵重複：原生DynamoDB不允許在請求中包含重複的主鍵，而PolarDB允許，並將為每個重複的主鍵返回一條資料。
Query/Scan
- 返回結果中的ScannedCount（掃描計數）與Count（返回計數）的數值始終相等，不區分應用過濾器（FilterExpression）前後的專案數量。
TransactionGetItem/TransactionWriteItem
- 原生DynamoDB不允許在單筆事務中對同一個主鍵進行多次操作，而PolarDB當前允許此類操作。
- TransactionCanceledException目前只可能包含ConditionalCheckFailed和TransactionConflict兩種Reason。ItemCollectionSizeLimitExceeded、ProvisionedThroughputExceeded和ThrottlingError在PolarDB不會發生。任何ValidationError都會以CommonError的形式拋出，而不是在某些情境下成為TransactionCanceledException的一個Reason。

詳細命令與參數支援

說明

是否支援列：
- 是：表示支援該參數。
- 否：表示不支援該參數。
備忘列：對不支援或行為有特殊說明的參數進行了補充解釋。

CreateTable

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
CreateTable	請求參數	AttributeDefinitions	是	是	-
		KeySchema	是	是	-
		TableName	是	是	-
		BillingMode	否	否	請求中包含此項時，會被忽略。
		DeletionProtectionEnabled	否	是	-
		GlobalSecondaryIndexes	否	是	-
		LocalSecondaryIndexes	否	是	-
		OnDemandThroughput	否	否	請求中包含此項時，會被忽略。
		ProvisionedThroughput	否	是	請求中包含此項時，會被忽略。
		ResourcePolicy	否	否	請求中包含此項時，會被忽略。
		SSESpecification	否	否	請求中包含此項時，會被忽略。說明如有加密需求，請使用設定透明資料加密TDE。
		StreamSpecification	否	否	請求中包含此項時，會被忽略。說明如有流複製需求，請使用訂閱管理。
		TableClass	否	否	請求中包含此項時，會被忽略。
		Tags	否	否	請求中包含此項時，會被忽略。
		WarmThroughput	否	否	請求中包含此項時，會被忽略。
	返回參數	TableDescription	-	是	-

DescribeTable

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
DescribeTable	請求參數	TableName	是	是	-
DescribeTable	返回參數	Table	-	是	-

ListTables

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
ListTables	請求參數	ExclusiveStartTableName	否	是	-
	請求參數	Limit	否	是	-
	返回參數	LastEvaluatedTableName	-	是	-
	返回參數	TableNames	-	是	-

UpdateTable

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
UpdateTable	請求參數	TableName	是	是	-
		AttributeDefinitions	否	是	-
		BillingMode	否	否	請求中包含此項時，會被忽略。
		DeletionProtectionEnabled	否	是	-
		GlobalSecondaryIndexUpdates	否	是	建議在業務低峰期進行執行。
		GlobalTableWitnessUpdates	否	否	請求中包含此項時，會報錯。
		MultiRegionConsistency	否	否	請求中包含此項時，會報錯。
		OnDemandThroughput	否	否	請求中包含此項時，會被忽略。
		ProvisionedThroughput	否	否	請求中包含此項時，會被忽略。
		ReplicaUpdates	否	否	請求中包含此項時，會報錯。
		SSESpecification	否	否	請求中包含此項時，會被忽略。說明如有加密需求，請使用設定透明資料加密TDE。
		StreamSpecification	否	否	請求中包含此項時，會被忽略。說明如有流複製需求，請使用訂閱管理。
		TableClass	否	否	請求中包含此項時，會被忽略。
		WarmThroughput	否	否	請求中包含此項時，會被忽略。
	返回參數	TableDescription	-	是	-

DeleteTable

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
DeleteTable	請求參數	TableName	是	是	-
DeleteTable	返回參數	TableDescription	-	是	-

PutItem

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
PutItem	請求參數	Item	是	是	-
		TableName	是	是	-
		ConditionalOperator	否	否	已廢棄。請使用`ConditionExpression`。
		ConditionExpression	否	是	-
		Expected	否	否	已廢棄。請使用`ConditionExpression`。
		ExpressionAttributeNames	否	是	-
		ExpressionAttributeValues	否	是	-
		ReturnConsumedCapacity	否	是	計費相關參數，會被忽略。
		ReturnItemCollectionMetrics	否	是	-
		ReturnValues	否	是	-
		ReturnValuesOnConditionCheckFailure	否	是	-
	返回參數	Attributes	-	是	-
		ConsumedCapacity	-	否	計費相關參數，不返回。
		ItemCollectionMetrics	-	是	-

UpdateItem

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
UpdateItem	請求參數	Key	是	是	-
		TableName	是	是	-
		AttributeUpdates	否	否	已廢棄。請使用`UpdateExpression`。
		ConditionalOperator	否	否	已廢棄。請使用`UpdateExpression`。
		ConditionExpression	否	是	-
		Expected	否	否	已廢棄。請使用`UpdateExpression`。
		ExpressionAttributeNames	否	是	-
		ExpressionAttributeValues	否	是	-
		ReturnConsumedCapacity	否	是	計費相關參數，會被忽略。
		ReturnItemCollectionMetrics	否	是	-
		ReturnValues	否	是	-
		ReturnValuesOnConditionCheckFailure	否	是	-
		UpdateExpression	否	是	-
	返回參數	Attributes	-	是	-
		ConsumedCapacity	-	否	計費相關參數，不返回。
		ItemCollectionMetrics	-	是	-

GetItem

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
GetItem	請求參數	Key	是	是	-
		TableName	是	是	-
		AttributesToGet	否	否	已廢棄。請使用`ProjectionExpression`。
		ConsistentRead	否	是	-
		ExpressionAttributeNames	否	是	-
		ProjectionExpression	否	是	-
		ReturnConsumedCapacity	否	是	計費相關參數，會被忽略。
	返回參數	ConsumedCapacity	-	否	計費相關參數，不返回。
	返回參數	Item	-	是	-

DeleteItem

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
DeleteItem	請求參數	Key	是	是	-
		TableName	是	是	-
		ConditionalOperator	否	否	已廢棄。請使用`ConditionExpression`。
		ConditionExpression	否	是	-
		Expected	否	否	已廢棄。請使用`ConditionExpression`。
		ExpressionAttributeNames	否	是	-
		ExpressionAttributeValues	否	是	-
		ReturnConsumedCapacity	否	是	計費相關參數，會被忽略。
		ReturnItemCollectionMetrics	否	是	-
		ReturnValues	否	是	-
		ReturnValuesOnConditionCheckFailure	否	是	-
	返回參數	Attributes	-	是	-
		ConsumedCapacity	-	否	計費相關參數，不返回。
		ItemCollectionMetrics	-	是	-

BatchWriteItem

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
BatchWriteItem	請求參數	RequestItems	是	是	-
		ReturnConsumedCapacity	否	是	計費相關參數，會被忽略。
		ReturnItemCollectionMetrics	否	是	-
	返回參數	ConsumedCapacity	-	否	計費相關參數，不返回。
		ItemCollectionMetrics	-	是	-
		UnprocessedItems	-	是	行為有差異，恒為空白。見上方限制說明。

參數	二級參數	三級參數	是否必選	是否支援	備忘
RequestItems	DeleteRequest	Key	是	是	-
RequestItems	PutRequest	Item	是	是	-

BatchGetItem

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
BatchGetItem	請求參數	RequestItems	是	是	-
	請求參數	ReturnConsumedCapacity	否	是	計費相關參數，會被忽略。
	返回參數	ConsumedCapacity	-	否	計費相關參數，不返回。
		Responses	-	是	-
		UnprocessedKeys	-	是	行為有差異，恒為空白。見上方限制說明。

參數	二級參數	是否必選	是否支援	備忘
RequestItems	ConsistentRead	否	是	-
	ExpressionAttributeNames	否	是	-
	Keys	是	是	-
	ProjectionExpression	否	是	-
	AttributesToGet	否	否	已廢棄。請使用`ProjectionExpression`，請求中包含此項將報錯。

Query

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
Query	請求參數	TableName	是	是	-
		AttributesToGet	否	否	已廢棄。請使用`ProjectionExpression`。
		ConditionalOperator	否	否	已廢棄。請使用`FilterExpression`。
		ConsistentRead	否	是	-
		ExclusiveStartKey	否	是	-
		ExpressionAttributeNames	否	是	-
		ExpressionAttributeValues	否	是	-
		FilterExpression	否	是	-
		IndexName	否	是	-
		KeyConditionExpression	否	是	-
		KeyConditions	否	否	已廢棄。請使用`KeyConditionExpression`。
		Limit	否	是	-
		ProjectionExpression	否	是	-
		QueryFilter	否	否	已廢棄。請使用`FilterExpression`。
		ReturnConsumedCapacity	否	是	計費相關參數，會被忽略。
		ScanIndexForward	否	是	-
		Select	否	是	-
	返回參數	ConsumedCapacity	-	否	計費相關參數，不返回。
		Count	-	是	行為有差異，恒等於`ScannedCount`。
		Items	-	是	-
		LastEvaluatedKey	-	是	-
		ScannedCount	-	是	-

Scan

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
Scan	請求參數	TableName	是	是	-
		AttributesToGet	否	否	已廢棄。請使用`ProjectionExpression`。
		ConditionalOperator	否	否	已廢棄。請使用`FilterExpression`。
		ConsistentRead	否	是	-
		ExclusiveStartKey	否	是	-
		ExpressionAttributeNames	否	是	-
		ExpressionAttributeValues	否	是	-
		FilterExpression	否	是	-
		IndexName	否	是	-
		Limit	否	是	-
		ProjectionExpression	否	是	-
		ReturnConsumedCapacity	否	是	計費相關參數，會被忽略。
		ScanFilter	否	否	已廢棄。請使用`FilterExpression`。
		Segment	否	否	暫不支援，請求中包含此項將報錯。
		Select	否	是	-
		TotalSegments	否	否	暫不支援，請求中包含此項將報錯。
	返回參數	ConsumedCapacity	-	否	計費相關參數，不返回。
		Count	-	是	行為有差異，恒等於`ScannedCount`。
		Items	-	是	-
		LastEvaluatedKey	-	是	-
		ScannedCount	-	是	-

TransactWriteItems

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
TransactWriteItems	請求參數	TransactItems	是	是	-
		ClientRequestToken	否	是	-
		ReturnConsumedCapacity	否	是	計費相關參數，會被忽略。
		ReturnItemCollectionMetrics	否	是	-
	返回參數	ConsumedCapacity	-	否	計費相關參數，不返回。
	返回參數	ItemCollectionMetrics	-	是	-

參數	二級參數	是否必選	是否支援	備忘
TransactItems	ConditionCheck	否	是	-
	Put	否	是	-
	Update	否	是	-
	Delete	否	是	-

TransactGetItems

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
TransactGetItems	請求參數	TransactItems	是	是	-
	請求參數	ReturnConsumedCapacity	否	是	計費相關參數，會被忽略。
	返回參數	ConsumedCapacity	-	否	計費相關參數，不返回。
	返回參數	Responses	-	是	-

DescribeTimeToLive

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
DescribeTimeToLive	請求參數	TableName	是	是	-
DescribeTimeToLive	返回參數	TimeToLiveDescription	-	是	-

UpdateTimeToLive

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
UpdateTimeToLive	請求參數	TableName	是	是	-
	請求參數	TimeToLiveSpecification	是	是	-
	返回參數	TimeToLiveSpecification	-	是	-

參數	二級參數	是否必選	是否支援	備忘
TimeToLiveSpecification	AttributeName	是	是	-
TimeToLiveSpecification	Enabled	是	是	-

TagResource

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
TagResource	請求參數	ResourceArn	是	是	來自於TableDescription的TableArn欄位。
TagResource	請求參數	Tags	是	是	-

UntagResource

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
UntagResource	請求參數	ResourceArn	是	是	來自於TableDescription的TableArn欄位。
UntagResource	請求參數	TagKeys	是	是	-

ListTagsOfResource

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
ListTagsOfResource	請求參數	ResourceArn	是	是	來自於TableDescription的TableArn欄位。
	請求參數	NextToken	否	是	-
	返回參數	Tags	-	是	-
	返回參數	NextToken	-	是	-

特定的功能差異

下表列出了DynamoDB中與PolarDB架構差異較大的功能類別。這些功能在DynamoDB中通過專有API實現，而PolarDB通過平台自身能力或PostgreSQL生態提供對等方案。

功能類別	DynamoDB介面/參數	PolarDB對等方案
計費相關	`BillingMode`、`ProvisionedThroughput`、`OnDemandThroughput`、`WarmThroughput`、`ReturnConsumedCapacity`、`ConsumedCapacity`	計費模式與DynamoDB不同，相關參數配置後不生效（自動忽略）。
彈性配置	`DescribeTableReplicaAutoScaling`、`UpdateTableReplicaAutoScaling`、`DescribeLimits`	通過Serverless與變更配置實現彈效能力。
PartiQL查詢	`ExecuteStatement`、`ExecuteTransaction`、`BatchExecuteStatement`	同時相容DynamoDB介面與PostgreSQL標準SQL，可直接用SQL滿足複雜查詢需求。
備份與恢複	`CreateBackup`、`DeleteBackup`、`DescribeBackup`、`ListBackups`、`RestoreTableFromBackup`、`RestoreTableToPointInTime`、`DescribeContinuousBackups`、`UpdateContinuousBackups`	支援周期性自動備份與即時生效的手動備份，並支援按時間點恢複（PITR）。詳情請參見備份恢複。
全域表	`CreateGlobalTable`、`DescribeGlobalTable`、`DescribeGlobalTableSettings`、`ListGlobalTables`、`UpdateGlobalTable`、`UpdateGlobalTableSettings`	通過全球資料庫網路（GDN）實現跨地區資料同步與就近讀取。
服務端加密	`SSESpecification`（在`CreateTable`/`UpdateTable`中）	通過設定透明資料加密TDE實現待用資料加密。
DynamoDB Streams	`DescribeStream`、`GetShardIterator`、`GetRecords`、`ListStreams`、`StreamSpecification`	基於PostgreSQL原生邏輯複製，實現資料變更的增量訂閱與下遊消費。詳情請參見訂閱管理。
S3匯入與匯出	`ImportTable`、`ExportTableToPointInTime`、`DescribeExport`、`DescribeImport`、`ListExports`、`ListImports`	基於HTAP能力（內建列存索引（IMCI）），分析查詢可直接線上運行，無需ETL到獨立分析系統。或可通過DTS、OSS外表、邏輯複製對接MaxCompute、AnalyticDB、EMR等巨量資料生態。
資源策略	`GetResourcePolicy`、`PutResourcePolicy`、`DeleteResourcePolicy`、`ResourcePolicy`參數	通過阿里雲帳號使用RAM進行存取控制實現精微調權限管理，資料面採用PostgreSQL原生使用者與許可權體系。
Kinesis流式整合	`DescribeKinesisStreamingDestination`、`EnableKinesisStreamingDestination`、`DisableKinesisStreamingDestination`、`UpdateKinesisStreamingDestination`	通過DTS資料同步或PostgreSQL原生邏輯複製實現流式Data Integration。
貢獻者洞察	`DescribeContributorInsights`、`UpdateContributorInsights`、`ListContributorInsights`	通過資料庫自治服務（DAS）提供SQL洞察、效能監控、慢SQL分析等能力。
服務端點查詢	`DescribeEndpoints`	通過OpenAPI - DescribeDBClusterEndpoints查詢叢集DynamoDB串連地址。