相容性與限制 - PolarDB

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

相容性評估工具：polardb_ddb_code_digest

為了協助您高效評估現有專案與PolarDB的相容性，PolarDB提供了本地靜態程式碼分析工具polardb_ddb_code_digest.tar.gz。

工作原理

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

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

使用說明

下載本地靜態程式碼分析工具polardb_ddb_code_digest.tar.gz至您的應用環境中。
解壓該檔案並進入解壓後的目錄中，運行以下代碼安裝專案依賴。
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不完全一致。
強一致性讀：不支援在API請求中通過ConsistentRead=true參數來指定單次強一致性讀。一致性層級需在DynamoDB地址中配置。
統計與計費參數：所有與計費和容量消耗相關的請求參數（如ReturnConsumedCapacity）和返回欄位（如ConsumedCapacity）都會被忽略或不返回。
索引投影：為二級索引指定投影屬性（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）前後的專案數量。
TransactWriteItems
- 主鍵衝突：原生DynamoDB不允許在單筆事務中對同一個主鍵進行多次操作，而PolarDB當前允許此類操作。
- 失敗行為：當事務因條件檢查失敗而取消時，原生DynamoDB會嘗試執行所有操作並返回一個包含各操作狀態的列表。
```
// 原生DynamoDB的失敗響應樣本
TransactionCanceledException: Transaction cancelled, please refer cancellation reasons for specific reasons [ConditionalCheckFailed, None, ConditionalCheckFailed]
```
  PolarDB則會在遇到第一個失敗的操作時立即中斷事務並返回錯誤，報錯資訊相對簡單。
```
// PolarDB的失敗響應樣本
ConditionalCheckFailedException: The conditional request failed
```
TransactGetItems
- 主鍵衝突：原生DynamoDB不允許在單筆事務中對同一個主鍵進行多次操作，而PolarDB當前允許此類操作。

詳細命令與參數支援

說明

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

CreateTable

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
CreateTable	請求參數	AttributeDefinitions	是	是	-
		KeySchema	是	是	-
		TableName	是	是	-
		BillingMode	否	否	計費相關參數，會被忽略。
		GlobalSecondaryIndexes	否	是	-
		LocalSecondaryIndexes	否	是	-
		ProvisionedThroughput	否	是	計費相關參數，會被忽略。
		SSESpecification	否	否	-
		StreamSpecification	否	否	-
		Tags	否	否	-
	返回參數	TableDescription	-	是	-

DescribeTable

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

ListTables

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

DeleteTable

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

PutItem

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

UpdateItem

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

GetItem

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
GetItem	請求參數	Key	是	是	-
		TableName	是	是	-
		AttributesToGet	否	否	已廢棄。請使用`ProjectionExpression`。
		ConsistentRead	否	否	只能設定為`false`。預設會話一致性，一致性層級在訪問地址上配置。
		ExpressionAttributeNames	否	是	-
		ProjectionExpression	否	是	-
		ReturnConsumedCapacity	否	是	計費相關參數，會被忽略。
	返回參數	ConsumedCapacity	-	否	計費相關參數，不返回。
	返回參數	Item	-	是	-

DeleteItem

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

BatchWriteItem

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

BatchGetItem

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

Query

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
Query	請求參數	TableName	是	是	-
		AttributesToGet	否	否	已廢棄。請使用`ProjectionExpression`。
		ConditionalOperator	否	否	已廢棄。請使用`FilterExpression`。
		ConsistentRead	否	否	只能設定為`false`。預設會話一致性，一致性層級在訪問地址上配置。
		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	否	否	只能設定為`false`。一致性層級在訪問地址上配置。
		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	-	否	統計相關參數，不返回。

TransactGetItems

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