| list_instances |
Répertorie toutes les instances Cloud SQL du projet.
|
| get_instance |
Obtenez les détails d'une instance Cloud SQL.
|
| create_instance |
Lance la création d'une instance Cloud SQL.
Sauf indication contraire, une instance nouvellement créée utilise la configuration d'instance par défaut d'un environnement de développement. Voici la configuration par défaut d'une instance dans un environnement de développement :
{
"tier": "db-perf-optimized-N-2",
"data_disk_size_gb": 100,
"region": "us-central1",
"database_version": "POSTGRES_18",
"edition": "ENTERPRISE_PLUS",
"availability_type": "ZONAL",
"tags": [{"environment": "dev"}]
}
La configuration suivante est recommandée pour une instance dans un environnement de production :
{
"tier": "db-perf-optimized-N-8",
"data_disk_size_gb": 250,
"region": "us-central1",
"database_version": "POSTGRES_18",
"edition": "ENTERPRISE_PLUS",
"availability_type": "REGIONAL",
"tags": [{"environment": "prod"}]
}
La configuration d'instance suivante est recommandée pour SQL Server :
{
"tier": "db-perf-optimized-N-8",
"data_disk_size_gb": 250,
"region": "us-central1",
"database_version": "SQLSERVER_2022_STANDARD",
"edition": "ENTERPRISE",
"availability_type": "REGIONAL",
"tags": [{"environment": "prod"}]
}
|
| execute_sql |
Exécutez n'importe quelle instruction SQL valide, y compris les instructions de langage de définition de données (LDD), de langage de contrôle de données (LCD), de langage de requête de données (LRD) ou de langage de manipulation de données (LMD), sur une instance Cloud SQL. Pour que l'outil execute_sql soit compatible, une instance Cloud SQL doit répondre aux exigences suivantes :
- La valeur de
data_api_access doit être définie sur ALLOW_DATA_API.
- Pour les utilisateurs intégrés, password_secret_version doit être défini.
- Sinon, pour les utilisateurs IAM, l'option de base de données
cloudsql_iam_authentication doit être définie sur on pour une instance MySQL. Pour une instance PostgreSQL, l'option de base de données cloudsql.iam_authentication doit être définie sur on.
- Après avoir utilisé l'outil
create_instance pour créer une instance, vous pouvez utiliser l'outil create_user pour créer un compte utilisateur IAM pour l'utilisateur actuellement connecté au projet.
L'outil execute_sql présente les limites suivantes :
- Si une instruction SQL renvoie une réponse de plus de 10 Mo, elle sera tronquée.
- L'outil
execute_sql a un délai avant expiration par défaut de 30 secondes. Si une requête s'exécute pendant plus de 30 secondes, l'outil renvoie une erreur DEADLINE_EXCEEDED.
- L'outil
execute_sql n'est pas compatible avec SQL Server.
Si vous recevez des erreurs semblables à "L'authentification IAM n'est pas activée pour l'instance", vous pouvez utiliser l'outil get_instance pour vérifier la valeur du flag d'authentification IAM pour les bases de données de l'instance. Si vous recevez des erreurs telles que "L'instance n'autorise pas l'utilisation d'executeSql pour accéder à cette instance", vous pouvez utiliser l'outil get_instance pour vérifier le paramètre data_api_access. Lorsque vous recevez des erreurs d'authentification :
- Vérifiez si le compte utilisateur actuellement connecté existe en tant qu'utilisateur IAM sur l'instance à l'aide de l'outil
list_users.
- Si le compte utilisateur IAM n'existe pas, utilisez l'outil
create_user pour créer le compte utilisateur IAM pour l'utilisateur connecté.
- Si l'utilisateur actuellement connecté ne dispose pas des rôles d'utilisateur de base de données appropriés, vous pouvez utiliser l'outil
update_user pour lui accorder ces rôles. Par exemple, le rôle cloudsqlsuperuser peut fournir à un utilisateur IAM de nombreuses autorisations requises.
Vérifiez si l'utilisateur actuellement connecté dispose des autorisations IAM appropriées pour le projet. Vous pouvez utiliser la commande gcloud projects get-iam-policy [PROJECT_ID] pour vérifier si les rôles ou autorisations IAM appropriés sont attribués à l'utilisateur pour le projet.
- L'utilisateur doit disposer de l'autorisation
cloudsql.instance.login pour effectuer l'authentification IAM automatique pour les bases de données.
- L'utilisateur doit disposer de l'autorisation
cloudsql.instances.executeSql pour exécuter des instructions SQL à l'aide de l'outil execute_sql ou de l'API executeSql.
- Rôles IAM courants contenant les autorisations requises : utilisateur d'instance Cloud SQL (
roles/cloudsql.instanceUser) ou administrateur Cloud SQL (roles/cloudsql.admin)
Lorsque vous recevez un ExecuteSqlResponse, vérifiez toujours les champs message et status dans le corps de la réponse. Un code d'état HTTP réussi ne garantit pas le succès complet de toutes les instructions SQL. Les champs message et status indiquent si des erreurs ou des avertissements partiels se sont produits lors de l'exécution de l'instruction SQL.
|
| execute_sql_readonly |
Exécutez n'importe quelle instruction SQL en lecture seule valide sur une instance Cloud SQL. Pour que l'outil execute_sql_readonly soit compatible, une instance Cloud SQL doit répondre aux exigences suivantes :
- La valeur de
data_api_access doit être définie sur ALLOW_DATA_API.
- Pour une instance MySQL, l'option de base de données
cloudsql_iam_authentication doit être définie sur on. Pour une instance PostgreSQL, l'option de base de données cloudsql.iam_authentication doit être définie sur on.
- Un compte utilisateur IAM ou un compte de service IAM (
CLOUD_IAM_USER ou CLOUD_IAM_SERVICE_ACCOUNT) est requis pour appeler l'outil execute_sql_readonly. L'outil exécute les instructions SQL à l'aide des droits d'accès de l'utilisateur de base de données connecté avec l'authentification IAM pour les bases de données.
Après avoir utilisé l'outil create_instance pour créer une instance, vous pouvez utiliser l'outil create_user pour créer un compte utilisateur IAM pour l'utilisateur actuellement connecté au projet. L'outil execute_sql_readonly présente les limites suivantes :
- Si une instruction SQL renvoie une réponse de plus de 10 Mo, elle sera tronquée.
- L'outil a un délai avant expiration de 30 secondes par défaut. Si une requête s'exécute pendant plus de 30 secondes, l'outil renvoie une erreur
DEADLINE_EXCEEDED.
- L'outil n'est pas compatible avec SQL Server.
Si vous recevez des erreurs semblables à "L'authentification IAM n'est pas activée pour l'instance", vous pouvez utiliser l'outil get_instance pour vérifier la valeur du flag d'authentification IAM pour les bases de données de l'instance. Si vous recevez des erreurs telles que "L'instance n'autorise pas l'utilisation d'executeSql pour accéder à cette instance", vous pouvez utiliser l'outil get_instance pour vérifier le paramètre data_api_access. Lorsque vous recevez des erreurs d'authentification :
- Vérifiez si le compte utilisateur actuellement connecté existe en tant qu'utilisateur IAM sur l'instance à l'aide de l'outil
list_users.
- Si le compte utilisateur IAM n'existe pas, utilisez l'outil
create_user pour créer le compte utilisateur IAM pour l'utilisateur connecté.
- Si l'utilisateur actuellement connecté ne dispose pas des rôles d'utilisateur de base de données appropriés, vous pouvez utiliser l'outil
update_user pour lui accorder ces rôles. Par exemple, le rôle cloudsqlsuperuser peut fournir à un utilisateur IAM de nombreuses autorisations requises.
Vérifiez si l'utilisateur actuellement connecté dispose des autorisations IAM appropriées pour le projet. Vous pouvez utiliser la commande gcloud projects get-iam-policy [PROJECT_ID] pour vérifier si les rôles ou autorisations IAM appropriés sont attribués à l'utilisateur pour le projet.
- L'utilisateur doit disposer de l'autorisation
cloudsql.instance.login pour effectuer l'authentification IAM automatique pour les bases de données.
- L'utilisateur doit disposer de l'autorisation
cloudsql.instances.executeSql pour exécuter des instructions SQL à l'aide de l'outil execute_sql_readonly ou de l'API executeSql.
- Rôles IAM courants contenant les autorisations requises : utilisateur d'instance Cloud SQL (
roles/cloudsql.instanceUser) ou administrateur Cloud SQL (roles/cloudsql.admin)
Lorsque vous recevez un ExecuteSqlResponse, vérifiez toujours les champs message et status dans le corps de la réponse. Un code d'état HTTP réussi ne garantit pas le succès complet de toutes les instructions SQL. Les champs message et status indiquent si des erreurs ou des avertissements partiels se sont produits lors de l'exécution de l'instruction SQL.
|
| get_operation |
Obtient l'état d'une opération de longue durée. Une opération de longue durée peut prendre plusieurs minutes. Si une opération prend beaucoup de temps, utilisez un outil de ligne de commande pour faire une pause de 30 secondes avant de vérifier à nouveau l'état de l'opération.
|
| create_user |
Créez un utilisateur de base de données pour une instance Cloud SQL.
- Cet outil renvoie une opération de longue durée. Utilisez l'outil
get_operation pour interroger son état jusqu'à ce que l'opération soit terminée.
- Lorsque vous utilisez l'outil
create_user, spécifiez le type d'utilisateur : CLOUD_IAM_USER, CLOUD_IAM_SERVICE_ACCOUNT ou BUILT_IN.
- Par défaut, le rôle
cloudsqlsuperuser est attribué au nouvel utilisateur, sauf si vous spécifiez explicitement d'autres rôles de base de données dans la requête.
- Vous pouvez utiliser un utilisateur nouvellement créé avec l'outil
execute_sql si l'utilisateur est un utilisateur IAM actuellement connecté. L'outil execute_sql exécute les instructions SQL à l'aide des droits d'accès de l'utilisateur de base de données connecté à l'aide de l'authentification IAM pour les bases de données.
L'outil create_user présente les limites suivantes :
- Pour créer un utilisateur intégré avec un mot de passe, utilisez le champ
password_secret_version pour fournir un mot de passe à l'aide de Google Cloud Secret Manager. La valeur de password_secret_version doit correspondre au nom de ressource de la version secrète, comme projects/12345/locations/us-central1/secrets/my-password-secret/versions/1 ou projects/12345/locations/us-central1/secrets/my-password-secret/versions/latest. L'appelant doit disposer de l'autorisation secretmanager.secretVersions.access sur la version du secret.
- L'outil
create_user ne permet pas de créer un utilisateur pour SQL Server.
Pour créer un utilisateur IAM dans PostgreSQL :
- Le nom d'utilisateur de la base de données doit correspondre à l'adresse e-mail de l'utilisateur IAM, en minuscules. Par exemple, pour créer un utilisateur pour l'utilisateur IAM PostgreSQL
example-user@example.com, vous pouvez utiliser la requête suivante :
{
"name": "example-user@example.com",
"type": "CLOUD_IAM_USER",
"instance":"test-instance",
"project": "test-project"
}
Le nom d'utilisateur de base de données créé pour l'utilisateur IAM est example-user@example.com. Pour créer un compte de service IAM dans PostgreSQL :
- Le nom d'utilisateur de la base de données doit être créé sans le suffixe
.gserviceaccount.com, même si l'adresse e-mail complète du compte est service-account-name@project-id.iam.gserviceaccount.com. Par exemple, pour créer un compte de service IAM pour PostgreSQL, vous pouvez utiliser le format de requête suivant :
{
"name": "test@test-project.iam",
"type": "CLOUD_IAM_SERVICE_ACCOUNT",
"instance": "test-instance",
"project": "test-project"
}
Le nom d'utilisateur de base de données créé pour le compte de service IAM est test@test-project.iam. Pour créer un utilisateur IAM ou un compte de service IAM dans MySQL :
- Lorsque Cloud SQL pour MySQL stocke un nom d'utilisateur, il tronque le signe @ et le nom de domaine de l'adresse e-mail de l'utilisateur ou du compte de service. Par exemple,
example-user@example.com devient example-user.
- Pour cette raison, vous ne pouvez pas ajouter deux utilisateurs IAM ou comptes de service ayant le même nom d'utilisateur, mais des noms de domaine différents, à la même instance Cloud SQL.
- Par exemple, pour créer un utilisateur pour l'utilisateur IAM MySQL
example-user@example.com, utilisez la requête suivante :
{
"name": "example-user@example.com",
"type": "CLOUD_IAM_USER",
"instance": "test-instance",
"project": "test-project"
}
Le nom d'utilisateur de base de données créé pour l'utilisateur IAM est example-user.
- Par exemple, pour créer le compte de service IAM MySQL
service-account-name@project-id.iam.gserviceaccount.com, utilisez la requête suivante :
{
"name": "service-account-name@project-id.iam.gserviceaccount.com",
"type": "CLOUD_IAM_SERVICE_ACCOUNT",
"instance": "test-instance",
"project": "test-project"
}
Le nom d'utilisateur de base de données créé pour le compte de service IAM est service-account-name.
|
| update_user |
Mettez à jour un utilisateur de base de données pour une instance Cloud SQL. Un cas d'utilisation courant pour update_user consiste à accorder à un utilisateur le rôle cloudsqlsuperuser, qui peut lui fournir de nombreuses autorisations requises. Cet outil ne permet que de modifier les utilisateurs pour leur attribuer des rôles de base de données.
- Cet outil renvoie une opération de longue durée. Utilisez l'outil
get_operation pour interroger son état jusqu'à ce que l'opération soit terminée.
- Avant d'appeler l'outil
update_user, vérifiez toujours la configuration existante de l'utilisateur, comme le type d'utilisateur avec l'outil list_users.
- Dans le cas particulier de MySQL, si l'outil
list_users renvoie une adresse e-mail complète pour le champ iamEmail, par exemple {name=test-account,
iamEmail=test-account@project-id.iam.gserviceaccount.com}, utilisez l'adresse e-mail complète dans le champ iamEmail de la requête update_user, dans le champ name de votre toolrequest. Par exemple : name=test-account@project-id.iam.gserviceaccount.com.
Paramètres clés pour modifier les rôles utilisateur :
database_roles : liste des rôles de base de données à attribuer à l'utilisateur.revokeExistingRoles : champ booléen (valeur par défaut : false) qui contrôle la façon dont les rôles existants sont gérés. Fonctionnement des mises à jour des rôles :
Si revokeExistingRoles est défini sur "true" :
- Tous les rôles existants accordés à l'utilisateur, mais qui ne figurent PAS dans la liste
database_roles fournie, seront RÉVOQUÉS.
- La révocation ne s'applique qu'aux rôles non système. Les rôles système tels que
cloudsqliamuser, etc., ne seront pas révoqués.
- Tous les rôles de la liste
database_roles que l'utilisateur ne possède PAS encore lui seront ACCORDÉS.
- Si
database_roles est vide, TOUS les rôles existants non système sont révoqués.
Si revokeExistingRoles est défini sur "false" (valeur par défaut) :
- Tous les rôles de la liste
database_roles que l'utilisateur ne possède PAS encore lui seront ACCORDÉS.
- Les rôles existants qui ne figurent PAS dans la liste
database_roles sont CONSERVÉS.
- Si
database_roles est vide, les rôles de l'utilisateur ne sont pas modifiés.
Exemples :
|
| clone_instance |
Créez une instance Cloud SQL qui est un clone d'une instance source.
- Cet outil renvoie une opération de longue durée. Utilisez l'outil
get_operation pour interroger son état jusqu'à ce que l'opération soit terminée.
- L'opération de clonage peut prendre plusieurs minutes. Utilisez un outil de ligne de commande pour faire une pause de 30 secondes avant de vérifier à nouveau l'état.
|
| update_instance |
Met à jour partiellement les paramètres de configuration d'une instance Cloud SQL.
- Cet outil renvoie une opération de longue durée. Utilisez l'outil
get_operation pour interroger son état jusqu'à ce que l'opération soit terminée.
- Certaines opérations de mise à jour, comme la modification de l'édition ou du niveau de l'instance, peuvent entraîner le redémarrage de l'instance, ce qui se traduit par un temps d'arrêt. Avant de procéder à de telles opérations, obtenez la confirmation de l'utilisateur.
|
| list_users |
Répertorie tous les utilisateurs de base de données pour une instance Cloud SQL.
|
| create_backup |
Effectue une sauvegarde sur une instance Cloud SQL. Renseignez toujours les champs "Projet" et "Instance" de la demande. L'emplacement (région) et la description de la sauvegarde peuvent également être fournis de manière facultative. Dans ce cas, les champs de requête correspondants doivent également être renseignés.
|
| restore_backup |
Restaure une sauvegarde sur une instance Cloud SQL. Les champs target_instance et target_project doivent être fournis et renseignés dans la requête. L'identifiant de sauvegarde peut être fourni de plusieurs manières :
- Un backup_run_id (qui est un entier).
- URI de sauvegarde au format
projects/{project-id}/backups/{backup-uid}.
- URI de sauvegarde au format
projects/{project-id}/locations/{location}/backupVaults/{backupvault}/dataSources/{datasource}/backups/{backup-uid}.
Utilisez l'identifiant pour remplir le champ backup_id de la requête. Le champ "source_project" doit être renseigné dans la requête. Si l'identifiant est un backup_run_id, le source_project sera fourni. Si l'identifiant est un URI de sauvegarde, il peut être nécessaire d'extraire le source_project de l'URI. Ne confondez pas le source_project extrait avec le target_project, qui sera fourni d'une autre manière. De plus, si l'identifiant est un backup_run_id, l'instance source doit être fournie et renseignée dans la requête. N'essayez pas de créer l'instance avant la restauration. La restauration elle-même créera l'instance si nécessaire. Confirmez les paramètres avec l'utilisateur avant d'exécuter la restauration.
|
| import_data |
Importer des données dans une instance Cloud SQL Si le fichier ne commence pas par gs://, il est considéré comme stocké en local. Si le fichier est local, il doit être importé dans Cloud Storage avant que vous puissiez effectuer l'appel import_data. Pour importer le fichier dans Cloud Storage, vous pouvez utiliser les commandes gcloud ou gsutil. Avant d'importer le fichier dans Cloud Storage, déterminez si vous souhaitez utiliser un bucket existant ou en créer un dans le projet fourni. Une fois le fichier importé dans Cloud Storage, le compte de service de l'instance doit disposer des autorisations suffisantes pour lire le fichier importé à partir du bucket Cloud Storage. Pour ce faire :
- Utilisez l'outil
get_instance pour obtenir l'adresse e-mail du compte de service de l'instance. À partir du résultat de l'outil, obtenez la valeur du champ serviceAccountEmailAddress.
- Attribuez le rôle
storage.objectAdmin au compte de service de l'instance sur le bucket Cloud Storage fourni. Utilisez une commande telle que gcloud storage buckets
add-iam-policy-binding ou une requête à l'API Cloud Storage. Il peut s'écouler entre deux et sept minutes, voire plus, avant que le rôle ne soit accordé et que les autorisations ne soient propagées au compte de service dans Cloud Storage. Si vous rencontrez une erreur d'autorisation après avoir mis à jour la stratégie IAM, attendez quelques minutes, puis réessayez.
Une fois les autorisations accordées, vous pouvez importer les données. Nous vous recommandons de laisser les paramètres facultatifs vides et d'utiliser les valeurs par défaut du système. Le type de fichier peut généralement être déterminé par l'extension du fichier. Par exemple, si le fichier est un fichier SQL, .sql ou .csv pour un fichier CSV. Voici un exemple de importContext SQL pour MySQL.
{
"uri": "gs://sample-gcs-bucket/sample-file.sql",
"kind": "sql#importContext",
"fileType": "SQL"
}
Aucun paramètre database n'est présent pour MySQL, car le nom de la base de données doit figurer dans le fichier SQL. Ne spécifiez qu'un seul URI. Aucun autre champ n'est obligatoire en dehors de importContext. Pour PostgreSQL, le champ database est obligatoire. Voici un exemple de importContext PostgreSQL avec le champ database spécifié.
{
"uri": "gs://sample-gcs-bucket/sample-file.sql",
"kind": "sql#importContext",
"fileType": "SQL",
"database": "sample-db"
}
L'outil import_data renvoie une opération de longue durée. Utilisez l'outil get_operation pour interroger son état jusqu'à ce que l'opération soit terminée.
|
| postgres_upgrade_precheck |
Vérifie si une instance Cloud SQL pour PostgreSQL est prête pour une mise à niveau de version majeure vers la version cible spécifiée. Le target_database_version DOIT être fourni dans la requête (par exemple, POSTGRES_15). Cet outil permet d'identifier les problèmes potentiels avant de tenter la mise à niveau, ce qui réduit le risque d'échec ou d'indisponibilité. Cet outil n'est compatible qu'avec les instances principales PostgreSQL et ne s'exécute pas sur les répliques en lecture. La vérification préalable évalue généralement les éléments suivants :
- Compatibilité du schéma de base de données avec la version cible.
- Limites et fonctionnalités non compatibles de Cloud SQL.
- Contraintes liées aux ressources d'instance (par exemple, nombre de relations).
- Compatibilité des paramètres et des extensions de la base de données actuelle.
- État général et disponibilité de l'instance.
Cet outil renvoie une opération de longue durée. Utilisez l'outil get_operation avec le nom de l'opération renvoyé par cet appel pour interroger son état. IMPORTANT : Une fois l'état de l'opération défini sur "DONE", les résultats détaillés de la vérification préalable sont disponibles dans la ressource Operation. Vous devrez inspecter la réponse de get_operation. Les résultats se trouvent dans le champ pre_check_major_version_upgrade_context.pre_check_response. Les résultats sont structurés et indiquent :
- INFO : informations générales.
- AVERTISSEMENT : problèmes potentiels qui ne bloquent pas la mise à niveau, mais qui doivent être examinés.
- ERREUR : Problèmes critiques qui DOIVENT être résolus avant de tenter la mise à niveau.
Chaque résultat doit inclure un message et les actions requises. Il est essentiel de résoudre tous les problèmes signalés avant de procéder à la mise à niveau vers une version majeure. Si pre_check_response est vide ou manquant, cela signifie qu'aucun problème n'a été identifié lors de la vérification préalable. L'exécution de cette vérification préalable n'a aucune incidence sur la disponibilité de l'instance.
|
