Démarrage d’une transaction SQL Exécution d’une instruction SQL Exécution d’une instruction SQL par lots sur un tableau de données Validation d’une transaction SQL Restauration d’une transaction

Appel de l’API de données Amazon RDS à l’aide de l’AWS CLI

Vous pouvez appeler l’API de données RDS (API de donnée) à l’aide d’AWS CLI.

Les exemples suivants utilisent AWS CLI pour l’API de données. Pour plus d’informations, consultez le document de référence AWS CLI pour l’API de données.

Dans chaque exemple, remplacez l’Amazon Resource Name (ARN) du cluster de bases de données par l’ARN de votre cluster de bases de données Aurora. De même, remplacez l’ARN du secret par l’ARN du secret dans Secrets Manager qui autorise l’accès au cluster de bases de données.

Note

AWS CLI peut formater les réponses en JSON.

Rubriques

Démarrage d’une transaction SQL
Exécution d’une instruction SQL
Exécution d’une instruction SQL par lots sur un tableau de données
Validation d’une transaction SQL
Restauration d’une transaction

Démarrage d’une transaction SQL

Vous pouvez démarrer une transaction SQL à l’aide de la commande CLI aws rds-data begin-transaction. L’appel renvoie un identifiant de transaction.

Important

Dans l’API de données, une transaction expire si aucun appel n’utilise son identifiant de transaction dans un délai de trois minutes. Si une transaction expire avant d’être validée, l’API de données la restaure automatiquement.

Les instructions DDL (Data Definition Language) MySQL d’une transaction provoquent une validation implicite. Nous vous recommandons d’exécuter chaque instruction DDL MySQL dans une commande execute-statement séparée avec l’option --continue-after-timeout.

En plus des options communes, spécifiez l’option --database qui indique le nom de la base de données.

Par exemple, la commande CLI suivante démarre une transaction SQL.

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

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

Voici un exemple de réponse.


{
    "transactionId": "ABC1234567890xyz"
}

Exécution d’une instruction SQL

Vous pouvez exécuter une instruction SQL à l’aide de la commande CLI aws rds-data execute-statement.

Vous pouvez exécuter une instruction SQL à l’intérieur d’une transaction en spécifiant l’identifiant de la transaction avec l’option --transaction-id. Vous pouvez démarrer une transaction à l’aide de la commande CLI aws rds-data begin-transaction. Vous pouvez terminer et valider une transaction à l’aide de la commande CLI aws rds-data commit-transaction.

Important

Si vous ne spécifiez pas l’option --transaction-id, les modifications renvoyées par l’appel sont automatiquement validées.

En plus des options courantes, spécifiez les options suivantes :

--sql (obligatoire) – Instruction SQL à exécuter sur le cluster de bases de données.
--transaction-id (facultatif) – Identifiant d’une transaction démarrée à l’aide de la commande CLI begin-transaction. Spécifiez l’identifiant de la transaction dans laquelle vous souhaitez intégrer l’instruction SQL.
--parameters (facultatif) – Paramètres pour l’instruction SQL.
--include-result-metadata | --no-include-result-metadata (facultatif) – Valeur indiquant si les métadonnées doivent apparaître dans les résultats. La valeur par défaut est --no-include-result-metadata.
--database (facultatif) – Nom de la base de données.

L’option --database peut ne pas fonctionner lorsque vous exécutez une instruction SQL après avoir exécuté --sql "use database_name;" dans la demande précédente. Nous vous recommandons d’utiliser l’option --database plutôt que d’exécuter des instructions --sql "use database_name;".
--continue-after-timeout | --no-continue-after-timeout (facultatif) – Valeur indiquant si l’exécution de l’instruction doit se poursuivre lorsque l’appel dépasse le délai d’expiration de 45 secondes de l’API de données. La valeur par défaut est --no-continue-after-timeout.

Pour les instructions en langage de définition de données (DDL), nous vous recommandons de continuer à exécuter l’instruction après l’expiration de l’appel afin d’éviter les erreurs et la corruption de structures de données.
--format-records-as "JSON"|"NONE" : une valeur facultative qui spécifie si l’ensemble de résultats doit être formaté en tant que chaîne JSON. La valeur par défaut est "NONE". Pour obtenir des informations sur l’utilisation du traitement des ensembles de résultats JSON, consultez Traitement des requêtes d’API Amazon RDS Data au format JSON.

Le cluster de bases de données renvoie une réponse pour l’appel.

Note

La taille de réponse est limitée à 1 Mio. Si l’appel renvoie plus de 1 Mio de données de réponse, l’appel est arrêté.

Le nombre maximal de demandes par seconde est 1 000 pour Aurora Serverless v1. Aucune limite n’est imposée pour les autres bases de données prises en charge.

Par exemple, la commande CLI suivante exécute une instruction SQL unique et omet les métadonnées dans les résultats (par défaut).

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

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

Voici un exemple de réponse.


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

La commande CLI suivante exécute une instruction SQL unique dans une transaction en spécifiant l’option --transaction-id.

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

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

Voici un exemple de réponse.


{
    "numberOfRecordsUpdated": 1
}

La commande CLI suivante exécute une seule instruction SQL avec des paramètres.

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

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

Voici un exemple de réponse.


{
    "numberOfRecordsUpdated": 1
}

La commande CLI suivante exécute une instruction SQL en langage de définition de données (DDL). L’instruction DDL renomme la colonne job en colonne role.

Important

Pour les instructions DDL, nous vous recommandons de continuer à exécuter l’instruction une fois l’appel expiré. Lorsqu’une instruction DDL se termine avant la fin de son exécution, cela peut entraîner des erreurs et corrompre les structures de données. Pour maintenir l’exécution d’une instruction lorsqu’un appel dépasse le délai d’expiration de 45 secondes de l’API de données RDS, sélectionnez l’option --continue-after-timeout.

Pour 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

Pour 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

Voici un exemple de réponse.


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

Note

Les données generatedFields ne sont pas prises en charge par Aurora PostgreSQL. Pour obtenir les valeurs des champs générés, utilisez la clause RETURNING. Pour plus d’informations, consultez Renvoi de données de lignes modifiées dans la documentation PostgreSQL.

Exécution d’une instruction SQL par lots sur un tableau de données

Vous pouvez exécuter une instruction SQL par lots sur un tableau de données à l’aide de la commande CLI aws rds-data batch-execute-statement. Vous pouvez utiliser cette commande pour réaliser une opération d’importation ou de mise à jour en bloc.

Important

Si vous ne spécifiez pas l’option --transaction-id, les modifications renvoyées par l’appel sont automatiquement validées.

En plus des options courantes, spécifiez les options suivantes :

--sql (obligatoire) – Instruction SQL à exécuter sur le cluster de bases de données.

Astuce
Pour les instructions compatibles avec MySQL, n’incluez pas de point-virgule à la fin du paramètre --sql. Un point-virgule final peut entraîner une erreur de syntaxe.
--transaction-id (facultatif) – Identifiant d’une transaction démarrée à l’aide de la commande CLI begin-transaction. Spécifiez l’identifiant de la transaction dans laquelle vous souhaitez intégrer l’instruction SQL.
--parameter-set (facultatif) – Ensembles de paramètres pour l’opération par lots.
--database (facultatif) – Nom de la base de données.

Le cluster de bases de données renvoie une réponse à l’appel.

Note

Il n’existe pas de limite supérieure fixe pour le nombre d’ensembles de paramètres. Toutefois, la taille maximale de la demande HTTP envoyée via l’API de données est de 4 MiB. Si la demande dépasse cette limite, l’API de données renvoie une erreur et ne traite pas la demande. Cette limite de 4 MiB inclut la taille des en-têtes HTTP et la notation JSON dans la demande. Ainsi, le nombre d’ensembles de paramètres que vous pouvez inclure dépend d’une combinaison de facteurs, tels que la taille de l’instruction SQL et la taille de chaque ensemble de paramètres.

La taille de réponse est limitée à 1 Mio. Si l’appel renvoie plus de 1 Mio de données de réponse, l’appel est arrêté.

Le nombre maximal de demandes par seconde est 1 000 pour Aurora Serverless v1. Aucune limite n’est imposée pour les autres bases de données prises en charge.

Par exemple, la commande CLI suivante exécute une instruction SQL par lots sur un tableau de données avec un ensemble de paramètres.

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

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

Note

N’incluez pas les sauts de ligne présents dans l’option --parameter-sets.

Validation d’une transaction SQL

À l’aide de la commande CLI aws rds-data commit-transaction, vous pouvez terminer une transaction SQL que vous avez démarrée avec aws rds-data begin-transaction et valider les modifications.

En plus des options courantes, spécifiez l’option suivante :

--transaction-id (obligatoire) – Identifiant d’une transaction démarrée à l’aide de la commande CLI begin-transaction. Spécifiez l’identifiant de la transaction que vous souhaitez terminer et valider.

Par exemple, la commande CLI suivante termine une transaction SQL et valide les changements.

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

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

Voici un exemple de réponse.


{
    "transactionStatus": "Transaction Committed"
}

Restauration d’une transaction

À l’aide de la commande CLI aws rds-data rollback-transaction, vous pouvez restaurer une transaction SQL que vous avez démarrée avec aws rds-data begin-transaction. La restauration d’une transaction annule les changements apportés.

Important

L’expiration de l’identifiant de la transaction entraîne automatiquement sa restauration. Dans ce cas, une commande aws rds-data rollback-transaction qui spécifie l’identifiant de transaction expiré renvoie une erreur.

En plus des options courantes, spécifiez l’option suivante :

--transaction-id (obligatoire) – Identifiant d’une transaction démarrée à l’aide de la commande CLI begin-transaction. Spécifiez l’identifiant de la transaction que vous souhaitez restaurer.

Par exemple, la commande AWS CLI suivante restaure une transaction SQL.

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

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

Voici un exemple de réponse.


{
    "transactionStatus": "Rollback Complete"
    }

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Référence des opérations

Appels depuis des applications Python

Appel de l’API de données Amazon RDS à l’aide de l’AWS CLI

Note

Rubriques

Démarrage d’une transaction SQL

Important

Exécution d’une instruction SQL

Important

Note

Important

Note

Exécution d’une instruction SQL par lots sur un tableau de données

Important

Astuce

Note

Note

Validation d’une transaction SQL

Restauration d’une transaction

Important