| list_instances |
Elenca tutte le istanze Cloud SQL nel progetto.
|
| get_instance |
Recupera i dettagli di un'istanza Cloud SQL.
|
| create_instance |
Avvia la creazione di un'istanza Cloud SQL.
Se non diversamente specificato, un'istanza appena creata utilizza la configurazione predefinita di un ambiente di sviluppo. Di seguito è riportata la configurazione predefinita per un'istanza in un ambiente di sviluppo:
{
"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"}]
}
Per un'istanza in un ambiente di produzione è consigliata la seguente configurazione:
{
"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"}]
}
Per SQL Server è consigliata la seguente configurazione dell'istanza:
{
"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 |
Esegui qualsiasi istruzione SQL valida, incluse istruzioni DDL (Data Definition Language), DCL (Data Control Language), DQL (Data Query Language) o DML (Data Manipulation Language), su un'istanza Cloud SQL. Per supportare lo strumento execute_sql, un'istanza Cloud SQL deve soddisfare i seguenti requisiti:
- Il valore di
data_api_access deve essere impostato su ALLOW_DATA_API.
- Per gli utenti integrati, deve essere impostata password_secret_version.
- In caso contrario, per gli utenti IAM, per un'istanza MySQL, il flag di database
cloudsql_iam_authentication deve essere impostato su on. Per un'istanza PostgreSQL, il flag di database cloudsql.iam_authentication deve essere impostato su on.
- Dopo aver utilizzato lo strumento
create_instance per creare un'istanza, puoi utilizzare lo strumento create_user per creare un account utente IAM per l'utente attualmente connesso al progetto.
Lo strumento execute_sql presenta le seguenti limitazioni:
- Se un'istruzione SQL restituisce una risposta superiore a 10 MB, la risposta verrà troncata.
- Lo strumento
execute_sql ha un timeout predefinito di 30 secondi. Se una query viene eseguita per più di 30 secondi, lo strumento restituisce un errore DEADLINE_EXCEEDED.
- Lo strumento
execute_sql non è supportato per SQL Server.
Se ricevi errori simili a "L'autenticazione IAM non è abilitata per l'istanza", puoi utilizzare lo strumento get_instance per controllare il valore del flag di autenticazione database IAM per l'istanza. Se ricevi errori come "L'istanza non consente l'utilizzo di executeSql per accedere a questa istanza", puoi utilizzare lo strumento get_instance per controllare l'impostazione data_api_access. Quando ricevi errori di autenticazione:
- Controlla se l'account utente attualmente connesso esiste come utente IAM nell'istanza utilizzando lo strumento
list_users.
- Se l'account utente IAM non esiste, utilizza lo strumento
create_user per creare l'account utente IAM per l'utente che ha eseguito l'accesso.
- Se l'utente attualmente connesso non dispone dei ruoli utente del database appropriati, puoi utilizzare lo strumento
update_user per concedere i ruoli del database all'utente. Ad esempio, il ruolo cloudsqlsuperuser può fornire a un utente IAM molte autorizzazioni richieste.
Controlla se all'utente attualmente connesso sono assegnate le autorizzazioni IAM corrette per il progetto. Puoi utilizzare il comando gcloud projects get-iam-policy [PROJECT_ID] per verificare se all'utente sono assegnati i ruoli o le autorizzazioni IAM appropriati per il progetto.
- L'utente deve disporre dell'autorizzazione
cloudsql.instance.login per eseguire l'autenticazione IAM dei database automatica.
- L'utente deve disporre dell'autorizzazione
cloudsql.instances.executeSql per eseguire istruzioni SQL utilizzando lo strumento execute_sql o l'API executeSql.
- Ruoli IAM comuni che contengono le autorizzazioni richieste: Utente istanza Cloud SQL (
roles/cloudsql.instanceUser) o Amministratore Cloud SQL (roles/cloudsql.admin)
Quando ricevi un ExecuteSqlResponse, controlla sempre i campi message e status nel corpo della risposta. Un codice di stato HTTP riuscito non garantisce la riuscita completa di tutte le istruzioni SQL. I campi message e status indicheranno se si sono verificati errori o avvisi parziali durante l'esecuzione dell'istruzione SQL.
|
| execute_sql_readonly |
Esegui qualsiasi istruzione SQL di sola lettura valida su un'istanza Cloud SQL. Per supportare lo strumento execute_sql_readonly, un'istanza Cloud SQL deve soddisfare i seguenti requisiti:
- Il valore di
data_api_access deve essere impostato su ALLOW_DATA_API.
- Per un'istanza MySQL, il flag di database
cloudsql_iam_authentication deve essere impostato su on. Per un'istanza PostgreSQL, il flag di database cloudsql.iam_authentication deve essere impostato su on.
- Per chiamare lo strumento
execute_sql_readonly è necessario un account utente IAM o un account di servizio IAM (CLOUD_IAM_USER o CLOUD_IAM_SERVICE_ACCOUNT). Lo strumento esegue le istruzioni SQL utilizzando i privilegi dell'utente del database che ha eseguito l'accesso con l'autenticazione IAM dei database.
Dopo aver utilizzato lo strumento create_instance per creare un'istanza, puoi utilizzare lo strumento create_user per creare un account utente IAM per l'utente attualmente connesso al progetto. Lo strumento execute_sql_readonly presenta le seguenti limitazioni:
- Se un'istruzione SQL restituisce una risposta superiore a 10 MB, la risposta verrà troncata.
- Lo strumento ha un timeout predefinito di 30 secondi. Se una query viene eseguita per più di 30 secondi, lo strumento restituisce un errore
DEADLINE_EXCEEDED.
- Lo strumento non è supportato per SQL Server.
Se ricevi errori simili a "L'autenticazione IAM non è abilitata per l'istanza", puoi utilizzare lo strumento get_instance per controllare il valore del flag di autenticazione database IAM per l'istanza. Se ricevi errori come "L'istanza non consente l'utilizzo di executeSql per accedere a questa istanza", puoi utilizzare lo strumento get_instance per controllare l'impostazione data_api_access. Quando ricevi errori di autenticazione:
- Controlla se l'account utente attualmente connesso esiste come utente IAM nell'istanza utilizzando lo strumento
list_users.
- Se l'account utente IAM non esiste, utilizza lo strumento
create_user per creare l'account utente IAM per l'utente che ha eseguito l'accesso.
- Se l'utente attualmente connesso non dispone dei ruoli utente del database appropriati, puoi utilizzare lo strumento
update_user per concedere i ruoli del database all'utente. Ad esempio, il ruolo cloudsqlsuperuser può fornire a un utente IAM molte autorizzazioni richieste.
Controlla se all'utente attualmente connesso sono assegnate le autorizzazioni IAM corrette per il progetto. Puoi utilizzare il comando gcloud projects get-iam-policy [PROJECT_ID] per verificare se all'utente sono assegnati i ruoli o le autorizzazioni IAM appropriati per il progetto.
- L'utente deve disporre dell'autorizzazione
cloudsql.instance.login per eseguire l'autenticazione IAM dei database automatica.
- L'utente deve disporre dell'autorizzazione
cloudsql.instances.executeSql per eseguire istruzioni SQL utilizzando lo strumento execute_sql_readonly o l'API executeSql.
- Ruoli IAM comuni che contengono le autorizzazioni richieste: Utente istanza Cloud SQL (
roles/cloudsql.instanceUser) o Amministratore Cloud SQL (roles/cloudsql.admin)
Quando ricevi un ExecuteSqlResponse, controlla sempre i campi message e status nel corpo della risposta. Un codice di stato HTTP riuscito non garantisce la riuscita completa di tutte le istruzioni SQL. I campi message e status indicheranno se si sono verificati errori o avvisi parziali durante l'esecuzione dell'istruzione SQL.
|
| get_operation |
Recupera lo stato di un'operazione a lunga esecuzione. Il completamento di un'operazione a lunga esecuzione può richiedere diversi minuti. Se un'operazione richiede molto tempo, utilizza uno strumento a riga di comando per mettere in pausa per 30 secondi prima di ricontrollare lo stato dell'operazione.
|
| create_user |
Crea un utente del database per un'istanza Cloud SQL.
- Questo strumento restituisce un'operazione a lunga esecuzione. Utilizza lo strumento
get_operation per eseguire il polling del relativo stato fino al completamento dell'operazione.
- Quando utilizzi lo strumento
create_user, specifica il tipo di utente: CLOUD_IAM_USER, CLOUD_IAM_SERVICE_ACCOUNT o BUILT_IN.
- Per impostazione predefinita, al nuovo utente viene assegnato il ruolo
cloudsqlsuperuser, a meno che tu non specifichi esplicitamente altri ruoli del database nella richiesta.
- Puoi utilizzare un utente appena creato con lo strumento
execute_sql se l'utente è un utente IAM attualmente connesso. Lo strumento execute_sql esegue le istruzioni SQL utilizzando i privilegi dell'utente del database che ha eseguito l'accesso utilizzando l'autenticazione IAM dei database.
Lo strumento create_user presenta le seguenti limitazioni:
- Per creare un utente integrato con password, utilizza il campo
password_secret_version per fornire la password utilizzando Google Cloud Secret Manager. Il valore di password_secret_version deve essere il nome della risorsa della versione del secret, ad esempio projects/12345/locations/us-central1/secrets/my-password-secret/versions/1 o projects/12345/locations/us-central1/secrets/my-password-secret/versions/latest. Il chiamante deve disporre dell'autorizzazione secretmanager.secretVersions.access per la versione del secret.
- Lo strumento
create_user non supporta la creazione di un utente per SQL Server.
Per creare un utente IAM in PostgreSQL:
- Il nome utente del database deve essere l'indirizzo email dell'utente IAM e deve essere tutto in minuscolo. Ad esempio, per creare un utente per l'utente PostgreSQL IAM
example-user@example.com, puoi utilizzare la seguente richiesta:
{
"name": "example-user@example.com",
"type": "CLOUD_IAM_USER",
"instance":"test-instance",
"project": "test-project"
}
Il nome utente del database creato per l'utente IAM è example-user@example.com. Per creare un account di servizio IAM in PostgreSQL:
- Il nome utente del database deve essere creato senza il suffisso
.gserviceaccount.com anche se l'indirizzo email completo dell'account è service-account-name@project-id.iam.gserviceaccount.com. Ad esempio, per creare un account di servizio IAM per PostgreSQL, puoi utilizzare il seguente formato di richiesta:
{
"name": "test@test-project.iam",
"type": "CLOUD_IAM_SERVICE_ACCOUNT",
"instance": "test-instance",
"project": "test-project"
}
Il nome utente del database creato per il account di servizio IAM è test@test-project.iam. Per creare un utente IAM o un account di servizio IAM in MySQL:
- Quando Cloud SQL per MySQL memorizza un nome utente, tronca il carattere @ e il nome di dominio dall'indirizzo email dell'utente o del account di servizio. Ad esempio,
example-user@example.com diventa example-user.
- Per questo motivo, non puoi aggiungere due utenti IAM o service account con lo stesso nome utente, ma nomi di dominio diversi, alla stessa istanza Cloud SQL.
- Ad esempio, per creare un utente per l'utente IAM MySQL
example-user@example.com, utilizza la seguente richiesta:
{
"name": "example-user@example.com",
"type": "CLOUD_IAM_USER",
"instance": "test-instance",
"project": "test-project"
}
Il nome utente del database creato per l'utente IAM è example-user.
- Ad esempio, per creare il account di servizio IAM MySQL
service-account-name@project-id.iam.gserviceaccount.com, utilizza la seguente richiesta:
{
"name": "service-account-name@project-id.iam.gserviceaccount.com",
"type": "CLOUD_IAM_SERVICE_ACCOUNT",
"instance": "test-instance",
"project": "test-project"
}
Il nome utente del database creato per il account di servizio IAM è service-account-name.
|
| update_user |
Aggiorna un utente database per un'istanza Cloud SQL. Un caso d'uso comune per update_user è concedere a un utente il ruolo cloudsqlsuperuser, che può fornire a un utente molte autorizzazioni richieste. Questo strumento supporta solo l'aggiornamento degli utenti per assegnare ruoli di database.
- Questo strumento restituisce un'operazione a lunga esecuzione. Utilizza lo strumento
get_operation per eseguire il polling del relativo stato fino al completamento dell'operazione.
- Prima di chiamare lo strumento
update_user, controlla sempre la configurazione esistente dell'utente, ad esempio il tipo di utente, con lo strumento list_users.
- Come caso speciale per MySQL, se lo strumento
list_users restituisce un indirizzo email completo per il campo iamEmail, ad esempio {name=test-account,
iamEmail=test-account@project-id.iam.gserviceaccount.com}, nella richiesta update_user utilizza l'indirizzo email completo nel campo iamEmail del campo name della richiesta dello strumento. Ad esempio, name=test-account@project-id.iam.gserviceaccount.com.
Parametri chiave per l'aggiornamento dei ruoli utente:
database_roles: un elenco di ruoli del database da assegnare all'utente.revokeExistingRoles: un campo booleano (valore predefinito: false) che controlla la gestione dei ruoli esistenti. Come funzionano gli aggiornamenti dei ruoli:
Se revokeExistingRoles è vero:
- Tutti i ruoli esistenti concessi all'utente ma NON presenti nell'elenco
database_roles fornito verranno REVOCATI.
- La revoca si applica solo ai ruoli non di sistema. I ruoli di sistema come
cloudsqliamuser e così via non verranno revocati.
- Tutti i ruoli nell'elenco
database_roles che l'utente NON ha già verranno CONCESSI.
- Se
database_roles è vuoto, vengono revocati TUTTI i ruoli non di sistema esistenti.
Se revokeExistingRoles è false (impostazione predefinita):
- Tutti i ruoli nell'elenco
database_roles che l'utente NON ha già verranno CONCESSI.
- I ruoli esistenti NON presenti nell'elenco
database_roles vengono MANTENUTI.
- Se
database_roles è vuoto, i ruoli dell'utente non vengono modificati.
Esempi:
|
| clone_instance |
Crea un'istanza Cloud SQL come clone di un'istanza di origine.
- Questo strumento restituisce un'operazione a lunga esecuzione. Utilizza lo strumento
get_operation per eseguire il polling del suo stato fino al completamento dell'operazione.
- L'operazione di clonazione può richiedere diversi minuti. Utilizza uno strumento a riga di comando per mettere in pausa per 30 secondi prima di ricontrollare lo stato.
|
| update_instance |
Aggiorna parzialmente le impostazioni di configurazione di un'istanza Cloud SQL.
- Questo strumento restituisce un'operazione a lunga esecuzione. Utilizza lo strumento
get_operation per eseguire il polling del relativo stato fino al completamento dell'operazione.
- Alcune operazioni di aggiornamento, come la modifica dell'upgrade della versione o del livello dell'istanza, potrebbero causare il riavvio dell'istanza, con conseguente tempo di inattività. Prima di procedere con queste operazioni, chiedi conferma all'utente.
|
| list_users |
Elenca tutti gli utenti del database per un'istanza Cloud SQL.
|
| create_backup |
Esegue un backup su un'istanza Cloud SQL. Compila sempre i campi progetto e istanza nella richiesta. Possono essere forniti facoltativamente anche la posizione (regione) e la descrizione del backup, nel qual caso devono essere compilati anche i campi della richiesta corrispondenti.
|
| restore_backup |
Ripristina un backup in un'istanza Cloud SQL. target_instance e target_project devono essere forniti e compilati nella richiesta. L'identificatore di backup può essere fornito in diversi modi:
- Un backup_run_id (un numero intero).
- Un URI di backup nel formato
projects/{project-id}/backups/{backup-uid}.
- Un URI di backup nel formato
projects/{project-id}/locations/{location}/backupVaults/{backupvault}/dataSources/{datasource}/backups/{backup-uid}.
Utilizza l'identificatore per compilare il campo backup_id nella richiesta. Il campo source_project deve essere compilato nella richiesta. Se l'identificatore è un backup_run_id, verrà fornito il source_project. Se l'identificatore è un URI di backup, potrebbe essere necessario estrarre source_project dall'URI. Non confondere il source_project estratto con il target_project, che verrà fornito in altri modi. Inoltre, se l'identificatore è un backup_run_id, la source_instance deve essere fornita e compilata nella richiesta. Non tentare di creare l'istanza prima del ripristino, perché il ripristino stesso creerà l'istanza, se necessario. Prima di eseguire il ripristino, conferma i parametri con l'utente.
|
| import_data |
Importa i dati in un'istanza Cloud SQL. Se il file non inizia con gs://, si presume che sia archiviato localmente. Se il file è locale, deve essere caricato in Cloud Storage prima di poter effettuare la chiamata import_data effettiva. Per caricare il file su Cloud Storage, puoi utilizzare i comandi gcloud o gsutil. Prima di caricare il file in Cloud Storage, valuta se vuoi utilizzare un bucket esistente o crearne uno nuovo nel progetto fornito. Dopo il caricamento del file su Cloud Storage, il account di servizio dell'istanza deve disporre di autorizzazioni sufficienti per leggere il file caricato dal bucket Cloud Storage. Per farlo:
- Utilizza lo strumento
get_instance per ottenere l'indirizzo email del account di servizio dell'istanza. Dall'output dello strumento, ottieni il valore del campo serviceAccountEmailAddress.
- Concedi al account di servizio dell'istanza il ruolo
storage.objectAdmin nel bucket Cloud Storage fornito. Utilizza un comando come gcloud storage buckets
add-iam-policy-binding o una richiesta all'API Storage di Cloud Storage. Possono essere necessari da 2 a 7 minuti o più prima che il ruolo venga concesso e le autorizzazioni vengano propagate al account di servizio in Cloud Storage. Se si verifica un errore di autorizzazione dopo aver aggiornato il criterio IAM, attendi qualche minuto e riprova.
Una volta concesse le autorizzazioni, puoi importare i dati. Ti consigliamo di lasciare vuoti i parametri facoltativi e di utilizzare i valori predefiniti del sistema. Il tipo di file può in genere essere determinato dall'estensione del file. Ad esempio, se il file è un file SQL, .sql o .csv per il file CSV. Di seguito è riportato un esempio di importContext SQL per MySQL.
{
"uri": "gs://sample-gcs-bucket/sample-file.sql",
"kind": "sql#importContext",
"fileType": "SQL"
}
Non è presente alcun parametro database per MySQL, poiché il nome del database deve essere presente nel file SQL. Specifica un solo URI. Al di fuori di importContext, non sono necessari altri campi. Per PostgreSQL, il campo database è obbligatorio. Di seguito è riportato un esempio di importContext PostgreSQL con il campo database specificato.
{
"uri": "gs://sample-gcs-bucket/sample-file.sql",
"kind": "sql#importContext",
"fileType": "SQL",
"database": "sample-db"
}
Lo strumento import_data restituisce un'operazione a lunga esecuzione. Utilizza lo strumento get_operation per eseguire il polling del suo stato fino al completamento dell'operazione.
|
| postgres_upgrade_precheck |
Verifica se un'istanza Cloud SQL per PostgreSQL è pronta per un upgrade della versione principale alla versione di destinazione specificata. target_database_version DEVE essere fornito nella richiesta (ad es. POSTGRES_15).
Questo strumento aiuta a identificare potenziali problemi prima di tentare l'upgrade vero e proprio, riducendo il rischio di errori o tempi di inattività. Questo strumento è supportato solo per le istanze principali PostgreSQL e non viene eseguito sulle repliche di lettura. Il precontrollo in genere valuta:
- Compatibilità dello schema del database con la versione di destinazione.
- Limitazioni di Cloud SQL e funzionalità non supportate.
- Vincoli delle risorse dell'istanza (ad es. numero di relazioni).
- Compatibilità delle impostazioni e delle estensioni del database attuali.
- Stato e preparazione complessivi dell'istanza.
Questo strumento restituisce un'operazione a lunga esecuzione. Utilizza lo strumento get_operation con il nome dell'operazione restituito da questa chiamata per verificarne lo stato. IMPORTANTE: una volta che lo stato dell'operazione è DONE, i risultati dettagliati del controllo preliminare sono disponibili nella risorsa Operation. Dovrai esaminare la risposta di get_operation. I risultati si trovano nel campo pre_check_major_version_upgrade_context.pre_check_response. I risultati sono strutturati e indicano:
- INFO: informazioni generali.
- AVVISO: potenziali problemi che non bloccano l'upgrade, ma che devono essere esaminati.
- ERRORE: problemi critici che DEVONO essere risolti prima di tentare l'upgrade.
Ogni risultato deve includere un messaggio e le azioni richieste. È fondamentale risolvere i problemi segnalati prima di procedere con l'upgrade della versione principale. Se pre_check_response è vuoto o mancante, indica che non sono stati identificati problemi durante il controllo preliminare. L'esecuzione di questo controllo preliminare non influisce sulla disponibilità dell'istanza.
|
