使用 AWS CLI 呼叫 Amazon RDS 資料 API - Amazon Aurora
開始 SQL 交易執行 SQL 陳述式透過資料陣列來執行批次 SQL 陳述式遞交 SQL 交易復原 SQL 交易

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用 AWS CLI 呼叫 Amazon RDS 資料 API

您可以使用 AWS CLI 呼叫 RDS 資料 API(資料 API)。

下列範例會使用 AWS CLI 來呼叫資料 API。如需詳細資訊，請參閱資料 API 的 AWS CLI 參考。

在每個範例中，將資料庫叢集的 Amazon Resource Name (ARN) 取代為 Aurora 資料庫叢集的 ARN。同時也將秘密 ARN 取代為 Secrets Manager 中允許存取資料庫叢集的秘密 ARN。

注意

AWS CLI 可以將回應設為 JSON 格式。

開始 SQL 交易

您可以使用 aws rds-data begin-transaction CLI 命令來開始 SQL 交易。此呼叫會傳回交易識別符。

重要

在資料 API 內，如果三分鐘內沒有使用交易 ID 的任何呼叫，交易就會逾時。如果交易在遞交前就逾時，則資料 API 會自動將其復原。

交易中的 MySQL 資料定義語言 (DDL) 陳述式會導致隱含遞交。我們建議您使用 execute-statement 選項在個別的 --continue-after-timeout 命令中執行每個 MySQL DDL 陳述式。

除了常用選項之外，還將指定 --database 選項，其提供資料庫的名稱。

例如，以下 CLI 命令會開始 SQL 交易。

對於 Linux、macOS 或 Unix：

aws rds-data begin-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret"

在 Windows 中：

aws rds-data begin-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret"

以下是回應的範例。

{
    "transactionId": "ABC1234567890xyz"
}

執行 SQL 陳述式

您可以使用 aws rds-data execute-statement CLI 命令來執行 SQL 陳述式。

您可以透過使用 --transaction-id 選項指定交易識別符，來在交易中執行 SQL 陳述式。您可以使用 aws rds-data begin-transaction CLI 命令來開始交易。您可以使用 aws rds-data commit-transaction CLI 命令來結束和遞交交易。

重要

如果您沒有指定 --transaction-id 選項，系統就會自動遞交呼叫造成的變更。

除了常用的選項，請指定以下選項：

  • --sql (必要) – 在資料庫叢集上執行的 SQL 陳述式。

  • --transaction-id (選用) – 使用 begin-transaction CLI 命令開始的交易識別符。指定您要在其中包含 SQL 陳述式的交易 ID。

  • --parameters (選用) – SQL 陳述式的參數。

  • --include-result-metadata | --no-include-result-metadata (選用) – 此值會指出是否在結果中包含中繼資料。預設值為 --no-include-result-metadata。

  • --database (選用) – 資料庫的名稱。

    當您在先前請求中執行 --sql "use database_name;" 之後執行 SQL 陳述式時，--database 選項可能無法運作。建議您使用 --database 選項，而不是執行 --sql "use database_name;" 陳述式。

  • --continue-after-timeout | --no-continue-after-timeout (選用)：此值會指出在呼叫超過 45 秒的資料 API 逾時間隔後是否繼續執行陳述式。預設值為 --no-continue-after-timeout。

    對於資料定義語言 (DDL) 陳述式，我們建議在呼叫逾時後繼續執行陳述式，來避免錯誤和資料結構毀損的可能性。

  • --format-records-as "JSON"|"NONE" – 選用值，指定是否將結果集格式化為 JSON 字串。預設值為 "NONE"。如需處理 JSON 結果集的使用情況資訊，請參閱以 JSON 格式處理 Amazon RDS 資料 API 查詢結果。

資料庫叢集會傳回呼叫的回應。

注意

回應大小限制為 1 MiB。若呼叫傳回的回應資料超過 1 MiB，系統就會終止呼叫。

對於 Aurora Serverless v1，每秒請求數上限為 1,000。對於所有其他支援的資料庫，沒有限制。

例如，以下 CLI 命令會執行單一 SQL 陳述式並省略結果中的中繼資料 (預設值)。

對於 Linux、macOS 或 Unix：

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "select * from mytable"

在 Windows 中：

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "select * from mytable"

以下是回應的範例。

{
    "numberOfRecordsUpdated": 0,
    "records": [
        [
            {
                "longValue": 1
            },
            {
                "stringValue": "ValueOne"
            }
        ],
        [
            {
                "longValue": 2
            },
            {
                "stringValue": "ValueTwo"
            }
        ],
        [
            {
                "longValue": 3
            },
            {
                "stringValue": "ValueThree"
            }
        ]
    ]
}

以下 CLI 命令會透過指定 --transaction-id 選項來在交易中執行單一 SQL 陳述式。

對於 Linux、macOS 或 Unix：

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "update mytable set quantity=5 where id=201" --transaction-id "ABC1234567890xyz"

在 Windows 中：

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "update mytable set quantity=5 where id=201" --transaction-id "ABC1234567890xyz"

以下是回應的範例。

{
    "numberOfRecordsUpdated": 1
}

以下 CLI 命令會執行含參數的單一 SQL 陳述式。

對於 Linux、macOS 或 Unix：

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "insert into mytable values (:id, :val)" --parameters "[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"value1\"}}]"

在 Windows 中：

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "insert into mytable values (:id, :val)" --parameters "[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"value1\"}}]"

以下是回應的範例。

{
    "numberOfRecordsUpdated": 1
}

以下 CLI 命令會執行資料定義語言 (DDL) SQL 陳述式。DDL 陳述式會將 job 欄重新命名為欄 role。

重要

對於 DDL 陳述式，我們建議在呼叫逾時後繼續執行陳述式。當 DDL 陳述式在完成執行前而終止時，可能會發生錯誤且資料結構可能毀損。若要在呼叫超過 45 秒的 RDS 資料 API 逾時間隔後繼續執行陳述式，請指定 --continue-after-timeout 選項。

對於 Linux、macOS 或 Unix：

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "alter table mytable change column job role varchar(100)" --continue-after-timeout

在 Windows 中：

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "alter table mytable change column job role varchar(100)" --continue-after-timeout

以下是回應的範例。

{
    "generatedFields": [],
    "numberOfRecordsUpdated": 0
}
注意

Aurora PostgreSQL 不支援 generatedFields 資料。若要取得所產生欄位的值，請使用 RETURNING 子句。如需詳細資訊，請參閱 PostgreSQL 中的從修改後的資料列傳回資料。

透過資料陣列來執行批次 SQL 陳述式

您可以透過使用 aws rds-data batch-execute-statement CLI 命令，透過資料陣列來執行批次 SQL 陳述式。您可以使用此命令來執行大量匯入或更新操作。

您可以透過使用 --transaction-id 選項指定交易識別符，來在交易中執行 SQL 陳述式。您可以透過使用 aws rds-data begin-transaction CLI 命令來開始交易。您可以透過使用 aws rds-data commit-transaction CLI 命令來結束和遞交交易。

重要

如果您沒有指定 --transaction-id 選項，系統就會自動遞交呼叫造成的變更。

除了常用的選項，請指定以下選項：

  • --sql (必要) – 在資料庫叢集上執行的 SQL 陳述式。

    提示

    對於 MySQL 相容的陳述句，請不要在 --sql 參數結尾包含分號。結尾分號可能會導致語法錯誤。

  • --transaction-id (選用) – 使用 begin-transaction CLI 命令開始的交易識別符。指定您要在其中包含 SQL 陳述式的交易 ID。

  • --parameter-set (選用) – 批次操作的參數組。

  • --database (選用) – 資料庫的名稱。

資料庫叢集會傳回呼叫的回應。

注意

參數組數目並無固定上限。不過，透過資料 API 提交的 HTTP 請求大小上限為 4 MiB。若請求超過此限制，資料 API 會傳回錯誤，不會處理請求。此 4 MiB 限制包括 HTTP 標頭的大小和請求中的 JSON 標記法。因此，您可包含的參數集數目取決於因素組合，例如 SQL 陳述式的大小和每個參數集的大小。

回應大小限制為 1 MiB。若呼叫傳回的回應資料超過 1 MiB，系統就會終止呼叫。

對於 Aurora Serverless v1，每秒請求數上限為 1,000。對於所有其他支援的資料庫，沒有限制。

例如，以下 CLI 命令會透過含參數組的資料陣列來執行批次 SQL 陳述式。

對於 Linux、macOS 或 Unix：

aws rds-data batch-execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "insert into mytable values (:id, :val)" \
--parameter-sets "[[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueOne\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 2}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueTwo\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 3}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueThree\"}}]]"

在 Windows 中：

aws rds-data batch-execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "insert into mytable values (:id, :val)" ^
--parameter-sets "[[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueOne\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 2}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueTwo\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 3}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueThree\"}}]]"
注意

請勿在 --parameter-sets 選項中包含分行符號。

遞交 SQL 交易

您可以使用 aws rds-data commit-transaction CLI 命令，來結束您透過 aws rds-data begin-transaction 開始的 SQL 交易和遞交變更。

除了常用的選項，請指定以下選項：

  • --transaction-id (必要) – 使用 begin-transaction CLI 命令開始的交易識別符。指定您要結束和遞交的交易 ID。

例如，以下 CLI 命令會結束 SQL 交易和遞交變更。

對於 Linux、macOS 或 Unix：

aws rds-data commit-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--transaction-id "ABC1234567890xyz"

在 Windows 中：

aws rds-data commit-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--transaction-id "ABC1234567890xyz"

以下是回應的範例。

{
    "transactionStatus": "Transaction Committed"
}

復原 SQL 交易

您可以使用 aws rds-data rollback-transaction CLI 命令，來復原您透過 aws rds-data begin-transaction 開始的 SQL 交易。復原交易會取消其變更。

重要

如果交易 ID 已過期，系統會自動復原此交易。在這個情況下，指定此過期交易 ID 的 aws rds-data rollback-transaction 命令會傳回錯誤。

除了常用的選項，請指定以下選項：

  • --transaction-id (必要) – 使用 begin-transaction CLI 命令開始的交易識別符。指定您要復原的交易 ID。

例如，以下 AWS CLI 命令會復原 SQL 交易。

對於 Linux、macOS 或 Unix：

aws rds-data rollback-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--transaction-id "ABC1234567890xyz"

在 Windows 中：

aws rds-data rollback-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--transaction-id "ABC1234567890xyz"

以下是回應的範例。

{
    "transactionStatus": "Rollback Complete"
    }