Avvio di una transazione SQL Esecuzione di un'istruzione SQL Esecuzione di un'istruzione SQL batch su un array di dati Esecuzione del commit di una transazione SQL Rollback di una transazione SQL

Chiamata dell'API dati Amazon RDS con AWS CLI

Puoi chiamare RDS Data API (Data API) utilizzando. AWS CLI

I seguenti esempi utilizzano l'API AWS CLI for Data. Per ulteriori informazioni, consulta la Documentazione di riferimento AWS CLI per l'API dati.

In ogni esempio, sostituisci l'Amazon Resource Name (ARN) per il cluster DB con l'ARN per il tuo cluster Aurora DB. Inoltre, sostituisci l'ARN segreto con l'ARN del segreto in Secrets Manager che consente l'accesso al cluster database.

Nota

AWS CLI Può formattare le risposte in JSON.

Argomenti

Avvio di una transazione SQL
Esecuzione di un'istruzione SQL
Esecuzione di un'istruzione SQL batch su un array di dati
Esecuzione del commit di una transazione SQL
Rollback di una transazione SQL

Avvio di una transazione SQL

Puoi avviare una transazione SQL utilizzando il comando CLI aws rds-data begin-transaction. La chiamata restituisce un identificatore di transazione.

Importante

In Data API, una transazione scade se non ci sono chiamate che utilizzano il relativo ID entro tre minuti. Se una transazione scade prima che venga confermata, Data API la ripristina automaticamente.

Le istruzioni DDL (Data Definition Language) MySQL all'interno di una transazione causano un commit implicito. Si consiglia di eseguire ogni istruzione MySQL DDL in un comando execute-statement separato con l'opzione. --continue-after-timeout

Oltre alle opzioni comuni, specifica l'opzione --database, che fornisce il nome del database.

Ad esempio, il comando CLI seguente avvia una transazione SQL.

PerLinux, o: 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"

Per 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"

Di seguito è riportato un esempio della risposta.


{
    "transactionId": "ABC1234567890xyz"
}

Esecuzione di un'istruzione SQL

Puoi eseguire un'istruzione SQL utilizzando il comando CLI aws rds-data execute-statement.

Puoi eseguire un'istruzione SQL in una transazione specificando l'identificatore di transazione con l'opzione --transaction-id. Puoi avviare una transazione utilizzando il comando CLI aws rds-data begin-transaction. Puoi terminare ed eseguire il commit di una transazione utilizzando il comando CLI aws rds-data commit-transaction.

Importante

Se non specifichi l'opzione --transaction-id, viene eseguito automaticamente il commit delle modifiche risultanti dalla chiamata.

Oltre alle opzioni comuni, specifica le seguenti opzioni:

--sql (obbligatoria) – Un'istruzione SQL da eseguire sul cluster database.
--transaction-id (facoltativa) – L'identificatore di una transazione che è stata avviata utilizzando il comando CLI begin-transaction. Specifica l'ID transazione della transazione in cui desideri includere l'istruzione SQL.
--parameters (facoltativa) – I parametri per l'istruzione SQL.
--include-result-metadata | --no-include-result-metadata (opzionale) – Un valore che indica se includere metadati nei risultati. Il valore di default è --no-include-result-metadata.
--database (opzionale) – Il nome del database.

L'opzione --database potrebbe non funzionare quando si esegue un'istruzione SQL dopo l'esecuzione di --sql "use database_name;" nella richiesta precedente. Si consiglia di utilizzare l'opzione --database invece di eseguire le istruzioni --sql "use database_name;".
--continue-after-timeout | --no-continue-after-timeout(opzionale): un valore che indica se continuare a eseguire l'istruzione dopo la chiamata supera l'intervallo di timeout dell'API Data di 45 secondi. Il valore di default è --no-continue-after-timeout.

Per istruzioni DDL (Data Definition Language), è consigliabile continuare a eseguire l'istruzione dopo il timeout della chiamata per evitare errori e la possibilità di strutture dati danneggiate.
--format-records-as "JSON"|"NONE" - Un valore facoltativo che specifica se formattare il set di risultati come stringa JSON. Il valore predefinito è "NONE". Per informazioni sull'utilizzo dell'elaborazione di set di risultati JSON, consulta Elaborazione dei risultati delle query Amazon RDS Data API in formato JSON.

Il cluster database restituisce una risposta per la chiamata.

Nota

Il limite di dimensioni della risposta è 1 MiB. Se la chiamata restituisce più di 1 MiB di dati di risposta, verrà terminata.

InfattiAurora Serverless v1, il numero massimo di richieste al secondo è 1.000. Per tutti gli altri database supportati, non ci sono limiti.

Ad esempio, il comando CLI seguente esegue una singola istruzione SQL e omette i metadati nei risultati (il valore predefinito).

Per LinuxmacOS, oUnix:


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"

Per 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"

Di seguito è riportato un esempio della risposta.


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

Il comando CLI seguente esegue una singola istruzione SQL in una transazione specificando l'opzione --transaction-id.

Per LinuxmacOS, oUnix:


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"

Per 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"

Di seguito è riportato un esempio della risposta.


{
    "numberOfRecordsUpdated": 1
}

Il comando CLI seguente esegue una singola istruzione SQL con parametri.

Per LinuxmacOS, oUnix:


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

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

Di seguito è riportato un esempio della risposta.


{
    "numberOfRecordsUpdated": 1
}

Il comando CLI seguente esegue un'istruzione SQL DDL (Data Definition Language). L'istruzione DDL rinomina la colonna job nella colonna role.

Importante

Per istruzioni DDL, è consigliabile continuare a eseguire l'istruzione dopo il timeout della chiamata. Quando un'istruzione DDL termina prima che l'esecuzione sia terminata, può causare errori e verosimilmente strutture dati danneggiate. Per continuare a eseguire un'istruzione dopo che una chiamata supera l'intervallo di timeout dell'RDS Data API di 45 secondi, specifica l'opzione. --continue-after-timeout

PerLinux, o: 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

Per 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

Di seguito è riportato un esempio della risposta.


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

Nota

I dati generatedFields non sono supportati da Aurora PostgreSQL. Per ottenere i valori dei campi generati, utilizza la clausola RETURNING. Per ulteriori informazioni, consulta Returning Data From Modified Rows nella documentazione PostgreSQL.

Esecuzione di un'istruzione SQL batch su un array di dati

Puoi eseguire un'istruzione SQL batch su un'array di dati utilizzando il comando CLI aws rds-data batch-execute-statement. Puoi utilizzare questo comando per eseguire un'operazione di importazione in blocco o di aggiornamento.

Importante

Se non specifichi l'opzione --transaction-id, viene eseguito automaticamente il commit delle modifiche risultanti dalla chiamata.

Oltre alle opzioni comuni, specifica le seguenti opzioni:

--sql (obbligatoria) – Un'istruzione SQL da eseguire sul cluster database.

Suggerimento
Perché le istruzioni siano compatibili con MySQL, non includere un punto e virgola alla fine del parametro --sql. Un punto e virgola finale potrebbe causare un errore di sintassi.
--transaction-id (facoltativa) – L'identificatore di una transazione che è stata avviata utilizzando il comando CLI begin-transaction. Specifica l'ID transazione della transazione in cui desideri includere l'istruzione SQL.
--parameter-set (facoltativa) – Il set di parametri per l'operazione batch.
--database (opzionale) – Il nome del database.

Il cluster database restituisce una risposta alla chiamata.

Nota

Non è previsto alcun limite massimo al numero di set di parametri. Tuttavia, la dimensione massima della richiesta HTTP inviata tramite Data API è di 4 MiB. Se la richiesta supera questo limite, Data API restituisce un errore e non elabora la richiesta. Questo limite di 4 MiB include la dimensione delle intestazioni HTTP e la notazione JSON nella richiesta. Pertanto, il numero di set di parametri che è possibile includere dipende da una combinazione di fattori, ad esempio la dimensione dell'istruzione SQL e la dimensione di ogni set di parametri.

Il limite di dimensioni della risposta è 1 MiB. Se la chiamata restituisce più di 1 MiB di dati di risposta, verrà terminata.

InfattiAurora Serverless v1, il numero massimo di richieste al secondo è 1.000. Per tutti gli altri database supportati, non ci sono limiti.

Ad esempio, il seguente comando CLI esegue un'istruzione SQL batch su un'array di dati con un set di parametri.

Per LinuxmacOS, oUnix:


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

Per 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

Non includere interruzioni di riga nell'opzione --parameter-sets.

Esecuzione del commit di una transazione SQL

Utilizzando il comando CLI aws rds-data commit-transaction, puoi terminare una transazione SQL avviata con aws rds-data begin-transaction ed eseguire il commit delle modifiche.

Oltre alle opzioni di comando, specifica l'opzione seguente:

--transaction-id (obbligatorio) – L'identificatore di una transazione che è stata avviata utilizzando il comando CLI begin-transaction. Specifica l'ID transazione della transazione che desideri terminare e di cui eseguire il commit.

Ad esempio, il comando CLI seguente termina una transazione SQL ed esegue il commit delle modifiche.

Per LinuxmacOS, oUnix:


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"

Per 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"

Di seguito è riportato un esempio della risposta.


{
    "transactionStatus": "Transaction Committed"
}

Rollback di una transazione SQL

Utilizzando il comando CLI aws rds-data rollback-transaction, puoi eseguire il rollback di una transazione SQL avviata con aws rds-data begin-transaction. Il rollback di una transazione annulla le relative modifiche.

Importante

Se l'ID transazione è scaduto, il rollback della transazione è stato eseguito automaticamente. In questo caso, un comando aws rds-data rollback-transaction che specifica l'ID transazione scaduto restituisce un errore.

Oltre alle opzioni di comando, specifica l'opzione seguente:

--transaction-id (obbligatorio) – L'identificatore di una transazione che è stata avviata utilizzando il comando CLI begin-transaction. Specifica l'ID transazione della transazione di cui si desidera eseguire il rollback.

Ad esempio, il AWS CLI comando seguente ripristina una transazione SQL.

Per LinuxmacOS, oUnix:


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"

Per 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"

Di seguito è riportato un esempio della risposta.


{
    "transactionStatus": "Rollback Complete"
    }

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Riferimento operativo

Chiamate dalle app Python

Chiamata dell'API dati Amazon RDS con AWS CLI

Nota

Argomenti

Avvio di una transazione SQL

Importante

Esecuzione di un'istruzione SQL

Importante

Nota

Importante

Nota

Esecuzione di un'istruzione SQL batch su un array di dati

Importante

Suggerimento

Nota

Nota

Esecuzione del commit di una transazione SQL

Rollback di una transazione SQL

Importante