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 d'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 aux services privés 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

Avant de pouvoir exécuter des instructions SQL sur une instance, procédez comme suit.

Configurer l'utilisateur de la base de données

L'API Data doit s'authentifier en tant qu'utilisateur de base de données pour exécuter des instructions SQL.

Pour vous authentifier en tant qu'utilisateur intégré à l'aide d'un mot de passe, procédez comme suit :

1. Créez un compte utilisateur avec un mot de passe non vide. Vous pouvez également utiliser l'utilisateur par défaut sqlserver.
2. Accordez au compte les rôles ou droits requis pour exécuter des instructions SQL. Si l'utilisateur n'est pas sqlserver, accordez-lui le rôle db_owner.
3. Utilisez Secret Manager pour créer un secret régional afin de stocker le mot de passe. Pour des raisons de sécurité, l'API Data demande le nom de ressource du secret au lieu du mot de passe dans la requête API. Le secret régional doit être stocké dans la même région que votre instance Cloud SQL. Les secrets créés à l'aide du point de terminaison mondial de Secret Manager ne sont pas compatibles, même s'ils sont stockés dans la même région.
4. Accorde l'roles/secretmanager.secretAccessor à l'appelant de l'API Data. Il est recommandé de définir des conditions IAM pour permettre à un utilisateur d'accéder à un secret spécifique, mais pas aux autres secrets du projet.

Rôles ou autorisations requis

Les comptes de service ou d'utilisateur utilisés pour appeler l'API Data doivent disposer de l'autorisation d'exécuter des instructions SQL, cloudsql.instances.executesql. Cette autorisation est incluse dans l'un des rôles prédéfinis suivants :

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

Lorsque vous utilisez un secret Secret Manager pour l'authentification, l'utilisateur ou le compte de service doit également disposer de l'autorisation d'accéder au secret, secretmanager.versions.access. Cette autorisation est incluse dans l'un des rôles prédéfinis suivants :

• Secret Manager Secret Accessor (roles/secretmanager.secretAccessor)
• Secret Manager Admin (roles/secretmanager.admin)

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 sql instances patch INSTANCE_NAME --data-api-access=ALLOW_DATA_API

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

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

{
  "dataApiAccess": "ALLOW_DATA_API"
}

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 la gcloud CLI ou de l'API REST.

S'authentifier à l'aide d'un mot de passe

Vous pouvez exécuter des instructions SQL à l'aide de l'authentification par mot de passe intégrée, lorsque le mot de passe est stocké en tant que secret régional avec Secret Manager dans la même région que l'instance Cloud SQL.

gcloud sql instances execute-sql INSTANCE_NAME \
--database=DATABASE_NAME \
--sql=SQL_STATEMENT \
--user=USER \
--password-secret-version=PASSWORD_SECRET_VERSION \
--partial-result-mode=PARTIAL_RESULT_MODE

resource "google_sql_user" "built_in_user" {
  name     = "tf-user"
  host     = "%"  # Don't set this field for PostgreSQL and SQL Server.
  instance = google_sql_database_instance.instance.name
  password = "changeme"
  type     = "BUILT_IN"
}

# Create a regional secret. Global secrets are not supported even if
# located in one region only.
resource "google_secret_manager_regional_secret" "secret" {
  secret_id = "db-password"

  # Use the same region as the Cloud SQL instance.
  location = "us-central1"
}

resource "google_secret_manager_regional_secret_version" "secret_version" {
  secret = google_secret_manager_regional_secret.secret.id
  secret_data = "changeme"
}

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