Esegui istruzioni SQL utilizzando l'API Cloud SQL Data

MySQL | PostgreSQL | SQL Server

Questa pagina descrive come eseguire istruzioni SQL sui database nelle istanze Cloud SQL utilizzando l'API Data. Con l'API Data, utilizzi l'API Cloud SQL Admin e gcloud CLI per eseguire istruzioni SQL su qualsiasi istanza in cui hai attivato l'accesso all'API Data.

Puoi utilizzare l'API Data con istanze che utilizzano indirizzi IP pubblici, accesso privato ai servizi o Private Service Connect. L'API Data supporta tutti i tipi di istruzioni SQL, inclusi DML (Data Manipulation Language), DDL (Data Definition Language) e DQL (Data Query Language). L'API Data è adatta per eseguire istruzioni amministrative piccole e rapide, ad esempio la creazione di ruoli o utenti del database e l'esecuzione di piccoli aggiornamenti dello schema.

Prima di iniziare

Prima di poter eseguire istruzioni SQL su un'istanza, completa i seguenti passaggi:

Configura l'istanza per l'autenticazione IAM dei database.
Aggiungi un utente o service account IAM all'istanza e concedi all'account i ruoli o le autorizzazioni richiesti per eseguire le istruzioni SQL.

Ruoli o autorizzazioni richiesti

Per impostazione predefinita, gli utenti o i service account con uno dei seguenti ruoli dispongono dell'autorizzazione per eseguire istruzioni SQL su un'istanza 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)

Puoi anche definire un ruolo personalizzato IAM per l'utente o il account di servizio che include l'autorizzazione cloudsql.instances.executesql. Questa autorizzazione è supportata nei ruoli personalizzati IAM.

Attivare o disattivare l'API Data

Per utilizzare l'API di dati, devi abilitarla per ogni istanza. Puoi disattivare l'API Data in qualsiasi momento.

Console

Nella console Google Cloud , vai alla pagina Istanze Cloud SQL.

Vai a Istanze Cloud SQL
Per aprire la pagina Panoramica di un'istanza, fai clic sul nome dell'istanza.
Dal menu di navigazione SQL, seleziona Connessioni.
Fai clic sulla scheda Networking.
Seleziona la casella di controllo Consenti API Data.
Fai clic su Salva.

gcloud

Per abilitare l'accesso all'API di dati su un'istanza, utilizza il comando gcloud sql instances patch con il flag --data-api-access=ALLOW_DATA_API:

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

Per disattivare l'accesso all'API di dati, utilizza il flag --data-api-access=DISALLOW_DATA_API:

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

Sostituisci INSTANCE_NAME con il nome dell'istanza su cui attivare o disattivare l'API Data.

Esegui un'istruzione SQL

Puoi eseguire istruzioni SQL sui database nell'istanza Cloud SQL utilizzando gcloud CLI o l'API REST.

gcloud

Per eseguire un'istruzione SQL su un database di un'istanza utilizzando gcloud CLI, utilizza il comando gcloud sql instances execute-sql:

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

Effettua le seguenti sostituzioni:

INSTANCE_NAME: il nome dell'istanza
DATABASE_NAME: il nome del database all'interno dell'istanza.
SQL_STATEMENT: l'istruzione SQL da eseguire. Se l'istruzione contiene spazi o caratteri speciali della shell, deve essere racchiusa tra virgolette.
PARTIAL_RESULT_MODE: facoltativo. Controlla come rispondere quando il risultato è incompleto. Può essere ALLOW_PARTIAL_RESULT, FAIL_PARTIAL_RESULT o PARTIAL_RESULT_MODE_UNSPECIFIED. Vedi Modificare il comportamento di troncamento.

Se necessario, puoi anche includere il flag --project=PROJECT_ID.

Terraform

Puoi utilizzare l'API Data su Terraform per eseguire il provisioning di risorse nel database, ad esempio database, tabelle, estensioni, utenti e concessioni di privilegi, senza connetterti manualmente all'istanza. Per eseguire uno script SQL su Terraform, utilizza la risorsa Terraform google_sql_provision_script.

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

  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.
 */
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.
  # This field doesn't support MySQL 5.6 and 5.7.
  database_roles = ["cloudsqlsuperuser"]
}

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 DATABASE pets;"
  instance = google_sql_database_instance.instance.name

  # Some of your queries may require a database. You can create and use a
  # database in the script or explicitly create and reference a database
  # like database = google_sql_database.database.name.

  description = "sql script to create DBs"

  # 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]
}

Applica le modifiche

Per applicare la configurazione Terraform in un progetto Google Cloud , completa i passaggi nelle sezioni seguenti.

Prepara Cloud Shell

Avvia Cloud Shell.
Imposta il progetto Google Cloud predefinito in cui vuoi applicare le configurazioni Terraform.

Devi eseguire questo comando una sola volta per progetto e puoi eseguirlo in qualsiasi directory.
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
Le variabili di ambiente vengono sostituite se imposti valori espliciti nel file di configurazione Terraform.

Prepara la directory

Ogni file di configurazione Terraform deve avere la propria directory (chiamata anche modulo radice).

In Cloud Shell, crea una directory e un nuovo file al suo interno. Il nome file deve avere l'estensione .tf, ad esempio main.tf. In questo tutorial, il file è denominato main.tf.
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
Se stai seguendo un tutorial, puoi copiare il codice campione in ogni sezione o passaggio.

Copia il codice campione nel main.tf appena creato.

(Facoltativo) Copia il codice da GitHub. Questa operazione è consigliata quando lo snippet Terraform fa parte di una soluzione end-to-end.
Rivedi e modifica i parametri di esempio da applicare al tuo ambiente.
Salva le modifiche.
Inizializza Terraform. Devi eseguire questa operazione una sola volta per directory.
```
terraform init
```
(Facoltativo) Per utilizzare l'ultima versione del provider Google, includi l'opzione -upgrade:
```
terraform init -upgrade
```

Applica le modifiche

Rivedi la configurazione e verifica che le risorse che Terraform creerà o aggiornerà corrispondano alle tue aspettative:
```
terraform plan
```
Apporta le correzioni necessarie alla configurazione.
Applica la configurazione Terraform eseguendo questo comando e inserendo yes al prompt:
```
terraform apply
```
Attendi che Terraform visualizzi il messaggio "Apply complete!".
Apri il tuo Google Cloud progetto per visualizzare i risultati. Nella console Google Cloud , vai alle risorse nell'interfaccia utente per assicurarti che Terraform le abbia create o aggiornate.

Elimina le modifiche

L'eliminazione di una risorsa google_sql_provision_script non comporta l'eliminazione delle risorse nel database che ha creato. Per eliminarli, puoi aggiungere istruzioni esplicite nello script, ad esempio drop ... if exists, e poi applicare le modifiche.

REST

Per eseguire un'istruzione SQL su un database di un'istanza utilizzando l'API REST, invia una richiesta POST all'endpoint executeSql:

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

Il corpo della richiesta deve contenere il nome del database e l'istruzione SQL:

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

Effettua le seguenti sostituzioni:

PROJECT_ID: il tuo ID progetto.
INSTANCE_NAME: il nome dell'istanza
DATABASE_NAME: il nome del database all'interno dell'istanza.
SQL_STATEMENT: l'istruzione SQL da eseguire.
PARTIAL_RESULT_MODE: facoltativo. Controlla il modo in cui l'API risponde quando il risultato supera i 10 MB. Può essere FAIL_PARTIAL_RESULT o ALLOW_PARTIAL_RESULT. Vedi Modificare il comportamento di troncamento.

Modificare il comportamento di troncamento

Puoi controllare la gestione dei risultati di grandi dimensioni durante l'esecuzione di SQL.

Includi il campo "partialResultMode" nella richiesta. Questo campo accetta i seguenti valori:
- FAIL_PARTIAL_RESULT: genera un errore se il risultato supera i 10 MB o se è possibile recuperare solo un risultato parziale. Non restituire il risultato.
- ALLOW_PARTIAL_RESULT: restituisce un risultato troncato e imposta partial_result su true se il risultato supera i 10 MB o se è possibile recuperare solo un risultato parziale a causa di un errore. Non generare un errore.

Limitazioni

La dimensione massima di una risposta è 10 MB. I risultati che superano queste dimensioni vengono troncati se partialResultMode è impostato su ALLOW_PARTIAL_RESULT, altrimenti viene generato un errore.
Le richieste sono limitate a 0,5 MB.
Puoi eseguire istruzioni SQL solo per le istanze Cloud SQL per MySQL in esecuzione.
Cloud SQL non supporta l'utilizzo dell'API Data con le istanze configurate per la replica del server esterno.
Le richieste che richiedono più di 30 secondi vengono annullate. L'impostazione di un timeout dell'istruzione più elevato utilizzando SET SESSION MAX_EXECUTION_TIME non è supportata. Per Cloud SQL per MySQL 5.6 e 5.7, il timeout delle istruzioni DDL a lunga esecuzione può causare file o tabelle orfani di cui non è possibile eseguire il rollback in modo sicuro. Fai attenzione con istruzioni come ALTER TABLE su tabelle di grandi dimensioni.
Cloud SQL limita il numero di richieste executeSql simultanee a 10 per istanza per ogni utente. Se questo limite viene raggiunto, le richieste successive non vanno a buon fine con il messaggio "Su questa istanza possono essere eseguite al massimo 10 query simultanee. Riprova più tardi" o "È stato raggiunto il numero massimo di letture simultanee (10)".
Ogni risposta può contenere un massimo di 10 messaggi o avvisi del database.
Se si verifica un errore di sintassi o di esecuzione dell'istruzione, non viene restituito alcun risultato.
Per Cloud SQL per MySQL, gli avvisi e le notifiche sono disponibili solo per l'ultima istruzione di un'esecuzione multi-istruzione.
Le istruzioni che consumano una grande quantità di memoria possono causare errori di memoria insufficiente. Per saperne di più su come evitare questi errori, consulta Best practice per la gestione della memoria utilizzata. Un'istanza di database in esecuzione con un utilizzo elevato della memoria spesso causa problemi di prestazioni, arresti o anche tempi di inattività del database.
L'API Data può essere bloccata temporaneamente per motivi di integrità dei dati quando sull'istanza sono in corso determinate operazioni di manutenzione. Se si verifica, riprova più tardi.
L'API Data non garantisce ancora la residenza dei dati. Le richieste non andranno a buon fine e verrà visualizzato l'errore "not supported for instances in certain Assured Workloads control packages folders" (non supportato per le istanze in determinate cartelle dei pacchetti di controllo di Assured Workloads) per determinati progetti Assured Workloads e per i progetti con constraints/sql.restrictNoncompliantResourceCreation applicato manualmente.

Esegui istruzioni SQL utilizzando l'API Cloud SQL Data Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Prima di iniziare

Ruoli o autorizzazioni richiesti

Attivare o disattivare l'API Data

Console

gcloud

Esegui un'istruzione SQL

gcloud

Terraform

Applica le modifiche

Prepara Cloud Shell

Prepara la directory

Applica le modifiche

Elimina le modifiche

REST

Modificare il comportamento di troncamento

Limitazioni

Esegui istruzioni SQL utilizzando l'API Cloud SQL Data