Chamar a API de dados do Amazon RDS com a AWS CLI
É possível chamar a API de dados do RDS (API de dados) usando a AWS CLI.
Os exemplos a seguir usam a AWS CLI para a API de dados. Para obter mais informações, consulte AWS CLI Referência para a API de dados.
Em cada exemplo, substitua o nome do recurso da Amazon (ARN) do cluster de banco de dados pelo ARN do cluster de banco de dados do Aurora. Além disso, substitua o ARN do segredo pelo ARN do segredo no Secrets Manager que concede acesso ao cluster de banco de dados.
nota
A AWS CLI pode formatar respostas em JSON.
Tópicos
Iniciar uma transação SQL
Você pode iniciar uma transação SQL usando o comando aws rds-data
begin-transaction
da CLI. A chamada retorna um identificador da transação.
Importante
Com a API de dados, uma transação atinge o tempo limite quando não ocorre nenhuma chamada que usa o ID da respectiva transação no espaço de três minutos. Caso uma transação atinja o tempo limite antes de ser confirmada, a API de dados a reverte automaticamente.
As instruções da linguagem de definição de dados (DDL) do MySQL dentro de uma transação causam uma confirmação implícita. Recomendamos que você execute cada instrução de DDL do MySQL em um comando execute-statement
separado com a opção --continue-after-timeout
.
Além das opções comuns, especifique a opção --database
, que fornece o nome do banco de dados.
Por exemplo, o comando da CLI a seguir inicia uma transação SQL.
Para Linux, macOS ou 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
"
Para 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
"
Este é um exemplo da resposta.
{
"transactionId": "ABC1234567890xyz
"
}
Executar uma instrução SQL
Você pode executar uma instrução SQL usando o comando aws rds-data execute-statement
da CLI.
Você pode executar a instrução SQL em uma transação especificando o identificador da transação com a opção --transaction-id
. Você pode iniciar uma transação usando o comando aws rds-data begin-transaction
da CLI. Você pode encerrar e confirmar uma transação usando o comando aws rds-data
commit-transaction
da CLI.
Importante
Se você não especificar a opção --transaction-id
, as alterações resultantes da chamadas serão confirmadas automaticamente.
Além das opções comuns, especifique as opções a seguir:
-
--sql
(obrigatório): uma instrução SQL para ser executada no cluster de banco de dados. -
--transaction-id
(opcional): o identificador de uma transação que foi iniciada usando o comandobegin-transaction
da CLI. Especifique o ID da transação que você deseja incluir na instrução SQL. -
--parameters
(opcional): os parâmetros para a instrução SQL. -
--include-result-metadata | --no-include-result-metadata
(opcional): um valor que indica se os metadados devem ou não ser incluídos no resultado. O padrão é--no-include-result-metadata
. -
--database
(opcional): o nome do banco de dados.A opção
--database
pode não funcionar quando você executa uma instrução SQL depois de executar--sql "use
na solicitação anterior. Recomendamos que você use a opçãodatabase_name
;"--database
em vez de executar instruções--sql "use
.database_name
;" -
--continue-after-timeout | --no-continue-after-timeout
(opcional): um valor que indica se a instrução deve continuar a ser executada depois que a chamada excede o intervalo de 45 segundos do tempo limite da API de dados. O padrão é--no-continue-after-timeout
.Para instruções DDL (linguagem de definição de dados, data definition language), recomendamos continuar a executar a instrução depois que a chamada expira para evitar erros e a possibilidade de estruturas de dados corrompidos.
-
--format-records-as "JSON"|"NONE"
: um valor opcional que especifica se o conjunto de resultados será formatado como uma string JSON. O padrão é"NONE"
. Para obter informações de uso sobre o processamento de conjuntos de resultados JSON, consulte Processar resultados de consulta da API de dados do Amazon RDS no formato JSON.
O cluster de banco de dados retorna uma resposta para a chamada.
nota
O limite de tamanho da resposta é de 1 MiB. Se a chamada retornar mais que 1 MiB de dados de resposta, ela será encerrada.
No Aurora Serverless v1, o número máximo de solicitações por segundo é mil. Para todos os outros bancos de dados compatíveis, não há limite.
Por exemplo, o comando da CLI a seguir executa uma única instrução SQL e omite os metadados nos resultados (o padrão).
Para Linux, macOS ou 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
"
Para 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
"
Este é um exemplo da resposta.
{
"numberOfRecordsUpdated": 0,
"records": [
[
{
"longValue": 1
},
{
"stringValue": "ValueOne
"
}
],
[
{
"longValue": 2
},
{
"stringValue": "ValueTwo
"
}
],
[
{
"longValue": 3
},
{
"stringValue": "ValueThree
"
}
]
]
}
O comando da CLI a seguir executa uma única instrução SQL em uma transação especificando a opção --transaction-id
.
Para Linux, macOS ou 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
"
Para 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
"
Este é um exemplo da resposta.
{
"numberOfRecordsUpdated": 1
}
O comando da CLI a seguir executa uma única instrução SQL com parâmetros.
Para Linux, macOS ou 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 intomytable
values (:id
,:val
)" --parameters "[{\"name\": \"id
\", \"value\": {\"longValue\":1
}},{\"name\": \"val
\", \"value\": {\"stringValue\": \"value1
\"}}]"
Para 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 intomytable
values (:id
,:val
)" --parameters "[{\"name\": \"id
\", \"value\": {\"longValue\":1
}},{\"name\": \"val
\", \"value\": {\"stringValue\": \"value1
\"}}]"
Este é um exemplo da resposta.
{
"numberOfRecordsUpdated": 1
}
O comando da CLI a seguir executa uma instrução SQL da linguagem de definição de dados (DDL). A instrução DDL renomeia a coluna job
para coluna role
.
Importante
Para instruções DDL, recomendamos continuar a executar a instrução depois que a chamada expira. Quando uma instrução DDL é encerrada antes que ela termine de ser executada, podem ocorrer erros e possivelmente estruturas de dados corrompidos. Para continuar a executar uma instrução depois que uma chamada excede o intervalo de 45 segundos do tempo limite da API de dados do RDS, especifique a opção --continue-after-timeout
.
Para Linux, macOS ou 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
Para 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
Este é um exemplo da resposta.
{
"generatedFields": [],
"numberOfRecordsUpdated": 0
}
nota
Os dados generatedFields
não são compatíveis com o Aurora PostgreSQL. Para obter os valores de campos gerados, use a cláusula RETURNING
. Para obter mais informações, consulte Returning data from modified rows
Executar uma instrução SQL em lote em uma matriz de dados
Você pode executar uma instrução SQL em lote em uma matriz de dados usando o comando aws rds-data batch-execute-statement
da CLI. Você pode usar esse comando para executar uma importação em massa ou uma operação de atualização.
Você pode executar a instrução SQL em uma transação especificando o identificador da transação com a opção --transaction-id
. Você pode iniciar uma transação usando o comando aws rds-data
begin-transaction
da CLI. Você pode encerrar e confirmar uma transação usando o comando aws rds-data commit-transaction
da CLI.
Importante
Se você não especificar a opção --transaction-id
, as alterações resultantes da chamadas serão confirmadas automaticamente.
Além das opções comuns, especifique as opções a seguir:
-
--sql
(obrigatório): uma instrução SQL para ser executada no cluster de banco de dados.dica
Para obter instruções compatíveis com o MySQL, não inclua ponto e vírgula no final do parâmetro
--sql
. Um ponto e vírgula à direita pode causar um erro de sintaxe. -
--transaction-id
(opcional): o identificador de uma transação que foi iniciada usando o comandobegin-transaction
da CLI. Especifique o ID da transação que você deseja incluir na instrução SQL. -
--parameter-set
(opcional): os conjuntos de parâmetros para a operação em lote. -
--database
(opcional): o nome do banco de dados.
O cluster de banco de dados retorna uma resposta para a chamada.
nota
Não há um limite posterior fixo para o número de conjuntos de parâmetros. No entanto, o tamanho máximo da solicitação HTTP enviada via API de dados é 4 MiB. Se a solicitação exceder esse limite, a API de dados exibirá um erro e não processará a solicitação. Este limite de 4 MiB inclui o tamanho dos cabeçalhos HTTP e a notação JSON na solicitação. Assim, o número de conjuntos de parâmetros que você pode incluir depende de uma combinação de fatores, como o tamanho da instrução SQL e o tamanho de cada conjunto de parâmetros.
O limite de tamanho da resposta é de 1 MiB. Se a chamada retornar mais que 1 MiB de dados de resposta, ela será encerrada.
No Aurora Serverless v1, o número máximo de solicitações por segundo é mil. Para todos os outros bancos de dados compatíveis, não há limite.
Por exemplo, o comando da CLI a seguir executa uma instrução SQL em lote em uma matriz de dados com um conjunto de parâmetros.
Para Linux, macOS ou 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 intomytable
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
\"}}]]"
Para 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 intomytable
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
\"}}]]"
nota
Não inclua quebras de linha na opção --parameter-sets
.
Confirmar uma transação SQL
Com o uso do comando aws rds-data commit-transaction
da CLI, você pode encerrar uma transação SQL que iniciou com aws rds-data
begin-transaction
e confirmar as alterações.
Além das opções comuns, especifique a opção a seguir:
-
--transaction-id
(obrigatório): o identificador de uma transação que foi iniciada usando o comandobegin-transaction
da CLI. Especifique o ID da transação que você deseja encerrar e confirmar.
Por exemplo, o comando da CLI a seguir encerra uma transação SQL e confirma as alterações.
Para Linux, macOS ou 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
"
Para 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
"
Este é um exemplo da resposta.
{
"transactionStatus": "Transaction Committed"
}
Reverter uma transação SQL
Com o uso do comando aws rds-data rollback-transaction
da CLI, você pode reverter uma transação SQL que iniciou com aws rds-data
begin-transaction
. Reverter uma transação cancela as alterações feitas nela.
Importante
Se o ID da transação expirou, a transação foi revertida automaticamente. Nesse caso, um comando aws rds-data rollback-transaction
que especifica o ID da transação expirado retorna um erro.
Além das opções comuns, especifique a opção a seguir:
-
--transaction-id
(obrigatório): o identificador de uma transação que foi iniciada usando o comandobegin-transaction
da CLI. Especifique o ID da transação que você deseja reverter.
Por exemplo, o comando da AWS CLI a seguir reverte uma transação SQL.
Para Linux, macOS ou 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
"
Para 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
"
Este é um exemplo da resposta.
{
"transactionStatus": "Rollback Complete"
}