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 di Amazon RDS con la AWS CLI

Puoi chiamare l’API dati di Amazon RDS (API dati) utilizzando la AWS CLI.

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

In ogni esempio, sostituisci il nome della risorsa Amazon (ARN) del cluster di database con l’ARN per il cluster di database Aurora. 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

All’interno dell’API dati, una transazione scade se non ci sono chiamate che utilizzano il suo ID transazione in un periodo di tre minuti. Se una transazione scade prima del commit, viene automaticamente sottoposta a rollback dall’API dati.

Le istruzioni DDL (Data Definition Language) MySQL all’interno di una transazione causano un commit implicito. Consigliamo di eseguire ogni istruzioni DDL MySQL 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.

Per Linux, macOS o 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 (facoltativo): un valore che indica se continuare l’esecuzione dell’istruzione dopo che la chiamata supera l’intervallo di timeout di 45 secondi dell’API dati. 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 di default è "NONE". Per informazioni sull'utilizzo dell'elaborazione di set di risultati JSON, consulta Elaborazione dei risultati delle query dell’API dati di Amazon RDS 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.

Per Aurora Serverless v1, il numero massimo di richieste al secondo è 1.000. Per tutti gli altri database supportati, non esiste alcun limite.

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

Per Linux, macOS o 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"

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 Linux, macOS o 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"

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 Linux, macOS o 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\"}}]"

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 l’esecuzione di un’istruzione dopo che una chiamata supera il timeout di 45 secondi dell’API dati di RDS, specifica l’opzione --continue-after-timeout.

Per Linux, macOS o 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 l’API dati è 4 MiB. Se la richiesta supera questo limite, l’API dati 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.

Per Aurora Serverless v1, il numero massimo di richieste al secondo è 1.000. Per tutti gli altri database supportati, non esiste alcun limite.

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

Per Linux, macOS o 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\"}}]]"

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 Linux, macOS o 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"

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 comando AWS CLI seguente esegue il rollback di una transazione SQL.

Per Linux, macOS o 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"

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 alle operazioni

Chiamata dalle app Python

Chiamata dell’API dati di Amazon RDS con la 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