View a markdown version of this page

使用 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。有关更多信息，请参阅 Data API 的 AWS CLI 参考。

在每个示例中，将数据库集群的 Amazon 资源名称（ARN）替换为 Aurora 数据库集群的 ARN。另外，将密钥 ARN 替换为 Secrets Manager 中允许访问该数据库集群的密钥的 ARN。

注意

AWS CLI 可以使用 JSON 设置响应格式。

启动 SQL 事务

您可以使用 aws rds-data begin-transaction CLI 命令启动 SQL 事务。调用会返回事务标识符。

重要

在数据 API 中，如果三分钟之内没有任何调用使用某个事务的 ID，该事务将超时。如果事务在提交之前超时，数据 API 会自动进行回滚。

事务内的 MySQL 数据定义语言（DDL，Data Definition Language）语句会导致隐式提交。建议您在单独的 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（可选）– 一个值，指定当调用超过了数据 API 超时间隔（45 秒）后，是否继续运行语句。默认为 --no-continue-after-timeout。

    对于数据定义语言（DDL）语句，我们建议在调用超时后继续运行语句，以避免错误以及数据结构损坏的可能性。

  • --format-records-as "JSON"|"NONE" – 一个可选值，它指定是否将结果集格式化为 JSON 字符串。默认值为 "NONE"。有关处理 JSON 结果集的使用信息，请参阅处理 JSON 格式的 Amazon RDS 数据 API 查询结果。

数据库集群为调用返回响应。

注意

响应大小限制为 1MiB。如果调用返回的响应数据超过 1MiB，则调用将终止。

例如，以下 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 语句在结束运行之前终止，则可能导致错误以及数据结构损坏。要在调用超过 RDS 数据 API 超时间隔（45 秒）后继续运行语句，请指定 --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 请求的最大大小为 4MiB。如果请求超出此限制，数据 API 将返回错误并且不处理请求。此 4MiB 限制包括 HTTP 标头的大小和请求中的 JSON 符号。因此，可以包含的参数集数取决于因素的组合，例如 SQL 语句的大小和每个参数集的大小。

响应大小限制为 1MiB。如果调用返回的响应数据超过 1MiB，则调用将终止。

例如，以下 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"
	    }