如何對 Amazon RDS Proxy 中的連線釘選問題進行疑難排解？

解決方法

檢閱 CloudWatch 指標

請完成以下步驟：

1. 開啟 Amazon CloudWatch console (Amazon CloudWatch 主控台)。
2. 在導覽窗格中，選擇 Metrics (指標)，然後選擇 All Metrics (所有指標)。
3. 在 Browse (瀏覽) 索引標籤中，選擇 RDS，然後選擇 Per-Proxy Metrics (每個 Proxy 指標)。
4. 搜尋 DatabaseConnectionsCurrentlySessionPinned 指標。

DatabaseConnectionsCurrentlySessionPinned 指標會顯示 RDS Proxy 每 60 秒釘選的資料庫連線數。當用戶端請求中的作業變更工作階段狀態時，RDS Proxy 會釘選連線。

**注意：**DatabaseConnectionsCurrentlySessionPinned 指標會在 RDS Proxy 偵測到第一個釘選連線時開始記錄，並在釘選連線具有 NULL 值時停止。

檢閱 RDS Proxy 日誌事件

若要取得 SQL 陳述式和 RDS Proxy 內部作業的詳細資訊，請修改 Proxy 以啟用增強型記錄。

**注意：**增強型記錄會在 24 小時後自動關閉。

若要疑難排解連線釘選問題，請檢閱 RDS Proxy 日誌事件。

請完成以下步驟：

1. 開啟 CloudWatch console (CloudWatch 主控台)。
2. 在導覽窗格中，選擇 Logs (日誌)，然後選擇 Log groups (日誌群組)。
3. 選取您 Proxy 的日誌群組，例如 /aws/rds/proxy/name of your proxy。
4. 在 Log Streams (日誌串流) 索引標籤中，選取日誌串流以檢視日誌事件。

執行 CloudWatch Log Insights 查詢以偵測異常

若要存取 CloudWatch Logs Insights 中的查詢編輯器，請完成以下步驟：

1. 開啟 CloudWatch console (CloudWatch 主控台)。
2. 在導覽窗格中，選擇 Logs (日誌)，然後選擇 Log Insights (日誌 Insights)。

使用查詢編輯器執行以下查詢。在每個查詢中，將 proxy-name 替換為您的 Proxy 名稱。

若要判斷個別連線遭到釘選的原因，請執行以下查詢：

fields @message  
| sort @timestamp asc  
| filter @logStream like '{proxy-name}'  
| filter @message like /The client session was pinned to the database connection/

若要依計數取得釘選次數最多的連線，請執行以下查詢：

fields @message  
| sort @timestamp asc  
| filter @logStream like '{proxy-name}'  
| filter @message like /The client session was pinned to the database connection/  
| parse 'Reason: \\\*' as reason  
| stats count() as reasonCount by reason  
| sort by reasonCount desc  
| limit 20

解決工作階段設定變更

**注意：**如果您在執行 AWS Command Line Interface (AWS CLI) 命令時收到錯誤訊息，請參閱對 AWS CLI 錯誤進行疑難排解。此外，請確定您使用的是最新的 AWS CLI 版本。

當用戶端連線變更工作階段層級變數設定時，RDS Proxy 會釘選連線，因為它無法重複使用該連線。

然後，您會收到以下錯誤訊息：

「The client session was pinned to the database connection [dbConnection=xxxx] for the remainder of the session.The proxy can't reuse this connection until the session ends.Reason: SQL changed session settings that the proxy doesn't track.Consider moving session configuration to the proxy's initialization query.」

所有資料庫連線都必須具有相同的設定。若要解決此問題，請在建立 Proxy 時加入 Initialization query (初始查詢) 設定。指定當 Proxy 開啟每個新的資料庫連線時要執行的 SQL 陳述式。若要修改現有 Proxy，您可以使用 Amazon RDS console (Amazon RDS 主控台) 或執行 modify-db-proxy-target-group AWS CLI 命令。

**重要：**請勿將敏感資料 (例如密碼或長期有效的加密金鑰) 新增至初始化查詢。驗證或密碼編譯方法無法保護它，因為任何可存取您 Proxy 目標群組組態的人都可以檢視初始化查詢。

通常，您會將 Initialization query (初始化查詢) 設定與 SET 陳述式搭配使用，讓每個連線具有相同的設定。若要在單一 SET 陳述式中納入多個變數，請使用逗號分隔符號。

例如，您可以執行以下命令，在初始化查詢中設定時區變數：

aws rds modify-db-proxy-target-group --target-group-name default --db-proxy-name proxy --connection-pool-config '{ > "InitQuery": "SET time_zone = \"+00:00\";" > }'

**注意：**將 proxy 替換為您的 Proxy 名稱。

解決剖析訊息和通訊協定層級預備陳述式錯誤

當特定程式庫 (例如 asyncpg/mysql.connector) 在內部使用通訊協定層級預備陳述式時，您會收到以下其中一則錯誤訊息：

• 「The client session was pinned to the database connection [dbConnection=xxxx] for the remainder of the session.The proxy can't reuse this connection until the session ends.Reason: A parse message was detected.」
• 「The client session was pinned to the database connection [dbConnection=xxxx] for the remainder of the session.The proxy can't reuse this connection until the session ends.Reason: A protocol-level prepared statement was detected.」

如果用戶端使用預備陳述式，則 RDS Proxy 會釘選連線。

若要解決此問題，請在 Proxy 明確使用這些連線後，關閉所有使用預備陳述式的連線。

解決大型 SQL 查詢

您可能會收到以下錯誤訊息：

「The client session was pinned to the database connection [dbConnection=xxxx] for the remainder of the session.The proxy can't reuse this connection until the session ends.Reason: The connection ran a SQL query which exceeded the 16384 byte limit.」

對於 RDS Proxy 支援的所有資料庫引擎，當 RDS Proxy 遇到大於 16 KB 的 SQL 陳述式時，會釘選工作階段。最佳實務是縮減 SQL 陳述式的大小。例如，您可以移除註解或限制使用別名。

減少連線釘選

若要避免不必要的資料庫請求導致 Proxy 釘選連線，請採取以下動作：

• 移除會引發連線釘選的資料庫作業。
• 使用批次作業將相關請求合併為單一查詢。

若要標準化連線設定，請採取以下動作：

• 在各個連線之間維持一致的變數和組態設定，以管理交易層級的重複使用。
• 對於 Amazon RDS for PostgreSQL，請在資料庫端設定變數。當您在用戶端端設定變數時，RDS Proxy 會釘選資料庫連線。
• 對於 Amazon RDS for MySQL 資料庫，請使用工作階段釘選篩選條件來指定可安全避開工作階段釘選需求的資料庫作業。

最佳實務是將常見的 SET 陳述式移至 Proxy 的初始化查詢，以便在所有連線之間維持相同的初始化，並維持交易層級的重複使用。

相關資訊

RDS Proxy 概念與術語

使用 Amazon CloudWatch 監控 RDS Proxy 指標