Exécuter des instructions SQL à l'aide de l'API Cloud SQL Data

Cette page explique comment exécuter des instructions SQL sur des bases de données sur des instances Cloud SQL à l'aide de l'API Data. Avec l'API Data, vous utilisez l'API Cloud SQL Admin et gcloud CLI pour exécuter des instructions SQL sur n'importe quelle instance sur laquelle vous avez activé l'accès à l'API Data.

Vous pouvez utiliser l'API Data avec des instances qui utilisent des adresses IP publiques, l'accès privé aux services ou Private Service Connect. L'API Data est compatible avec tous les types d'instructions SQL, y compris le langage de manipulation de données (LMD), le langage de définition de données (LDD) et le langage de requête de données (DQL). L'API Data est idéale pour exécuter des instructions administratives rapides et de petite taille, comme la création de rôles ou d'utilisateurs de base de données, et pour effectuer de petites mises à jour de schéma.

Avant de commencer

Pour pouvoir exécuter des instructions SQL sur une instance, procédez comme suit :

Rôles ou autorisations requis

Par défaut, les comptes utilisateur ou de service disposant de l'un des rôles suivants sont autorisés à exécuter des instructions SQL sur une instance Cloud SQL (cloudsql.instances.executesql) :

  • Cloud SQL Admin (roles/cloudsql.admin)
  • Cloud SQL Instance User (roles/cloudsql.instanceUser)
  • Cloud SQL Studio User (roles/cloudsql.studioUser)

Vous pouvez également définir un rôle personnalisé IAM pour le compte d'utilisateur ou le compte de service, qui inclut l'autorisation cloudsql.instances.executesql. Cette autorisation est compatible avec les rôles personnalisés IAM.

Activer ou désactiver l'API Data

Pour utiliser l'API Data, vous devez l'activer pour chaque instance. Vous pouvez désactiver l'API Data à tout moment.

gcloud

Pour activer l'accès à l'API Data sur une instance, utilisez la commande gcloud sql instances patch avec l'indicateur --data-api-access=ALLOW_DATA_API :

gcloud sql instances patch INSTANCE_NAME --data-api-access=ALLOW_DATA_API

Pour désactiver l'accès à l'API Data, utilisez l'option --data-api-access=DENY_DATA_API :

gcloud sql instances patch INSTANCE_NAME --data-api-access=DENY_DATA_API

Remplacez INSTANCE_NAME par le nom de l'instance sur laquelle activer ou désactiver l'API Data.

Exécuter une instruction SQL

Vous pouvez exécuter des instructions SQL sur les bases de données de votre instance Cloud SQL à l'aide de gcloud CLI ou de l'API REST.

gcloud

Pour exécuter une instruction SQL sur une base de données d'une instance à l'aide de gcloud CLI, utilisez la commande gcloud beta sql instances execute-sql :

gcloud beta sql instances execute-sql INSTANCE_NAME \
--database=DATABASE_NAME \
--sql=SQL_STATEMENT \
--partial_result_mode=PARTIAL_RESULT_MODE

Effectuez les remplacements suivants :

  • INSTANCE_NAME : nom de l'instance.
  • DATABASE_NAME : nom de la base de données dans l'instance.
  • SQL_STATEMENT : instruction SQL à exécuter. Si l'instruction contient des espaces ou des caractères spéciaux du shell, elle doit être placée entre guillemets.
  • PARTIAL_RESULT_MODE (facultatif) : Contrôle la manière de répondre lorsque le résultat est incomplet. Il peut s'agir de ALLOW_PARTIAL_RESULT, FAIL_PARTIAL_RESULT ou PARTIAL_RESULT_MODE_UNSPECIFIED. Consultez Modifier le comportement de troncature.

Vous pouvez également inclure l'indicateur --project=PROJECT_ID si nécessaire.

REST

Pour exécuter une instruction SQL sur une base de données d'une instance à l'aide de l'API REST, envoyez une requête POST au point de terminaison executeSql :

POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME/executeSql

Le corps de la requête doit contenir le nom de la base de données et l'instruction SQL :

{
  "database": "DATABASE_NAME",
  "sqlStatement": "SQL_STATEMENT",
  "partialResultMode": "PARTIAL_RESULT_MODE"
}

Effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet.
  • INSTANCE_NAME : nom de l'instance.
  • DATABASE_NAME : nom de la base de données dans l'instance.
  • SQL_STATEMENT : instruction SQL à exécuter.
  • PARTIAL_RESULT_MODE (facultatif) : Contrôle la façon dont l'API répond lorsque le résultat dépasse 10 Mo. Il peut s'agir de FAIL_PARTIAL_RESULT ou ALLOW_PARTIAL_RESULT. Consultez Modifier le comportement de troncature.

Modifier le comportement de troncature

Vous pouvez contrôler la façon dont les résultats volumineux sont gérés lors de l'exécution de SQL.

  • Incluez le champ "partialResultMode" dans la requête. Ce champ accepte les valeurs suivantes :
    • FAIL_PARTIAL_RESULT : génère une erreur si le résultat dépasse 10 Mo ou si seul un résultat partiel peut être récupéré. Ne renvoie pas le résultat.
    • ALLOW_PARTIAL_RESULT : renvoie un résultat tronqué et définit partial_result sur "true" si le résultat dépasse 10 Mo ou si seul un résultat partiel peut être récupéré en raison d'une erreur. Ne générez pas d'erreur.

Limites

  • La taille maximale d'une réponse est de 10 Mo. Les résultats qui dépassent cette taille sont tronqués si partialResultMode est défini sur ALLOW_PARTIAL_RESULT. Dans le cas contraire, une erreur est générée.
  • Les requêtes sont limitées à 0,5 Mo.
  • Vous ne pouvez exécuter des instructions SQL que pour des instances Cloud SQL pour MySQL en cours d'exécution.
  • Cloud SQL n'est pas compatible avec l'utilisation de l'API Data avec les instances configurées pour la réplication de serveur externe.
  • Les requêtes qui prennent plus de 30 secondes sont annulées. Il n'est pas possible de définir un délai d'expiration d'instruction plus long à l'aide de SET SESSION MAX_EXECUTION_TIME. Pour Cloud SQL pour MySQL 5.6 et 5.7, l'expiration du délai des instructions LDD de longue durée peut entraîner un rollback en toute sécurité de fichiers ou de tables orphelins. Soyez prudent avec les instructions telles que ALTER TABLE sur les grandes tables.
  • Cloud SQL limite le nombre de requêtes executeSql simultanées à 10 par instance et par utilisateur. Si cette limite est atteinte, les requêtes suivantes échouent et le message "Nombre maximal de lectures simultanées (10) atteint" s'affiche.
  • Chaque réponse peut contenir jusqu'à 10 messages ou avertissements de base de données.
  • En cas d'erreur de syntaxe ou d'exécution d'une instruction, aucun résultat n'est renvoyé.
  • Pour Cloud SQL pour MySQL, les notifications et les avertissements ne sont disponibles que pour la dernière instruction d'une exécution multi-instructions.
  • Les instructions qui consomment une grande quantité de mémoire peuvent entraîner des erreurs de mémoire insuffisante. Pour savoir comment éviter ces erreurs, consultez Bonnes pratiques pour gérer l'utilisation de la mémoire. Une instance de base de données exécutée avec une utilisation élevée de la mémoire entraîne souvent des problèmes de performances, des blocages ou même des temps d'arrêt de la base de données.