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

MySQL | PostgreSQL | SQL Server

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. Vous pouvez également utiliser l'API Data pour activer les extensions PostgreSQL.

Avant de commencer

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

Configurez l'instance pour l'authentification IAM pour les bases de données.
Ajoutez un utilisateur ou un compte de service IAM à l'instance, puis accordez-lui les rôles ou autorisations requis pour exécuter des instructions SQL.

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.

Console

Dans la console Google Cloud , accédez à la page Instances Cloud SQL.

Accéder à la page Instances Cloud SQL
Pour ouvrir la page Présentation d'une instance, cliquez sur son nom.
Dans le menu de navigation SQL, sélectionnez Connexions.
Cliquez sur l'onglet Réseau.
Cochez la case Autoriser l'API Data.
Cliquez sur Enregistrer.

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=DISALLOW_DATA_API :

gcloud sql instances patch INSTANCE_NAME --data-api-access=DISALLOW_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 la gcloud CLI, utilisez la commande gcloud sql instances execute-sql :

gcloud 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.

Terraform

Vous pouvez utiliser l'API Data sur Terraform pour provisionner des ressources dans la base de données, telles que des bases de données, des tables, des extensions, des utilisateurs et des droits d'accès, sans vous connecter manuellement à l'instance. Pour exécuter un script SQL sur Terraform, utilisez la ressource Terraform google_sql_provision_script.

resource "google_sql_database_instance" "instance" {
  name             = "my-instance"
  database_version = "POSTGRES_17"

  settings {
    tier            = "db-perf-optimized-N-2"
    data_api_access = "ALLOW_DATA_API"  # This allows the use of Data API.
    database_flags {
      name  = "cloudsql.iam_authentication"
      value = "on"
    }
  }
}

/*
 * Create a database user for your account and grant roles so it has privilege to
 * access the database. Set the type to CLOUD_IAM_USER for huamn account or
 * CLOUD_IAM_SERVICE_ACCOUNT for service account. If a service account is used
 * and the instance is Postgres, trim the ".gserviceaccount.com"
 * suffix to avoid exceeding the username length limit.
*/
resource "google_sql_user" "iam_user" {
  name     = "account-used-to-apply-this-config@example.com"
  instance = google_sql_database_instance.instance.name
  type     = "CLOUD_IAM_USER"

  # Roles granted to the user. Smaller roles are preferred, if exist.
  database_roles = ["cloudsqlsuperuser"]
}

resource "google_sql_database" "database" {
  name     = "my-database"
  instance = google_sql_database_instance.instance.name
}

resource "google_sql_provision_script" "script" {
  # You can inline the script or import from a file like script  = file("${path.module}/script.sql")
  # When modified, the whole script will be executed again. It's recommended to
  # make the script idempotent with patterns like create if not exists ... or
  # if not exists (select ...) then ... end if.
  script  = "CREATE TABLE IF NOT EXISTS table1 ( col VARCHAR(16) NOT NULL );"

  instance = google_sql_database_instance.instance.name
  database = google_sql_database.database.name
  description = "sql script to create tables"

  # The identity account used to apply your Terraform config must exist as an
  # IAM user or IAM service account in the instance. Terraform connects to the
  # instance via IAM database authentication to execute the script.
  depends_on = [google_sql_user.iam_user]
}

Appliquer les modifications

Pour appliquer votre configuration Terraform dans un projet Google Cloud , suivez les procédures des sections suivantes.

Préparer Cloud Shell

Lancez Cloud Shell.
Définissez le projet Google Cloud par défaut dans lequel vous souhaitez appliquer vos configurations Terraform.

Vous n'avez besoin d'exécuter cette commande qu'une seule fois par projet et vous pouvez l'exécuter dans n'importe quel répertoire.
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
Les variables d'environnement sont remplacées si vous définissez des valeurs explicites dans le fichier de configuration Terraform.

Préparer le répertoire

Chaque fichier de configuration Terraform doit avoir son propre répertoire (également appelé module racine).

Dans Cloud Shell, créez un répertoire et un nouveau fichier dans ce répertoire. Le nom du fichier doit comporter l'extension .tf, par exemple main.tf. Dans ce tutoriel, le fichier est appelé main.tf.
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
Si vous suivez un tutoriel, vous pouvez copier l'exemple de code dans chaque section ou étape.

Copiez l'exemple de code dans le fichier main.tf que vous venez de créer.

Vous pouvez également copier le code depuis GitHub. Cela est recommandé lorsque l'extrait Terraform fait partie d'une solution de bout en bout.
Examinez et modifiez les exemples de paramètres à appliquer à votre environnement.
Enregistrez les modifications.
Initialisez Terraform. Cette opération n'est à effectuer qu'une seule fois par répertoire.
```
terraform init
```
Vous pouvez également utiliser la dernière version du fournisseur Google en incluant l'option -upgrade :
```
terraform init -upgrade
```

Appliquer les modifications

Examinez la configuration et vérifiez que les ressources que Terraform va créer ou mettre à jour correspondent à vos attentes :
```
terraform plan
```
Corrigez les modifications de la configuration si nécessaire.
Appliquez la configuration Terraform en exécutant la commande suivante et en saisissant yes lorsque vous y êtes invité :
```
terraform apply
```
Attendez que Terraform affiche le message "Apply completed!" (Application terminée).
Ouvrez votre projet Google Cloud pour afficher les résultats. Dans la console Google Cloud , accédez à vos ressources dans l'interface utilisateur pour vous assurer que Terraform les a créées ou mises à jour.

Supprimer les modifications

La suppression d'une ressource google_sql_provision_script ne supprime pas les ressources de base de données qu'elle a créées. Pour les supprimer, vous pouvez ajouter explicitement des instructions dans le script, telles que drop ... if exists, puis appliquer les modifications.

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"
  "autoIamAuthn": true
}

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 PostgreSQL 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 STATEMENT_TIMEOUT.
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 avec le message "Au maximum 10 requêtes simultanées peuvent être exécutées sur cette instance. Réessayez plus tard" ou "Nombre maximal de lectures simultanées (10) atteint".
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é.
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.
L'API Data peut être temporairement bloquée à des fins d'intégrité des données lorsque certaines opérations de maintenance sont en cours sur l'instance. Si cela se produit, réessayez plus tard.
L'API Data ne garantit pas encore la résidence des données. Les requêtes échoueront avec l'erreur "not supported for instances in certain Assured Workloads control packages folders" (non compatible avec les instances dans certains dossiers de packages de contrôles Assured Workloads) pour certains projets Assured Workloads et pour les projets avec constraints/sql.restrictNoncompliantResourceCreation appliqué manuellement.

Exécuter des instructions SQL à l'aide de l'API Cloud SQL Data Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Avant de commencer

Rôles ou autorisations requis

Activer ou désactiver l'API Data

Console

gcloud

Exécuter une instruction SQL

gcloud

Terraform

Appliquer les modifications

Préparer Cloud Shell

Préparer le répertoire

Appliquer les modifications

Supprimer les modifications

REST

Modifier le comportement de troncature

Limites

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