Chamar a API de dados do Amazon RDS com a AWS CLI - Amazon Aurora

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.

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 comando begin-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 database_name;" na solicitação anterior. Recomendamos que você use a opção --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 into mytable 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 into mytable 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 na documentação do PostgreSQL.

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 comando begin-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 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\"}}]]"

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 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\"}}]]"
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 comando begin-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 comando begin-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" }