Esegui istruzioni SQL utilizzando l'API Cloud SQL Data

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

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

Prima di iniziare

Prima di poter eseguire istruzioni SQL su un'istanza:

Ruoli o autorizzazioni richiesti

Per impostazione predefinita, gli utenti o gli account di servizio con uno dei seguenti ruoli hanno l'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 l'account di servizio che includa l'cloudsql.instances.executesql autorizzazione. Questa autorizzazione è supportata nei ruoli personalizzati IAM.

Abilitare o disabilitare l'API di dati

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

Console

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

    Vai a Istanze Cloud SQL

  2. Per aprire la pagina Panoramica di un'istanza, fai clic sul nome dell'istanza.
  3. Dal menu di navigazione SQL, seleziona Connessioni.
  4. Fai clic sulla scheda Networking.
  5. Seleziona la casella di controllo Consenti API di dati.
  6. Fai clic su Salva.

gcloud

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

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

Per disabilitare 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 abilitare o disabilitare l'API di dati.

Eseguire un'istruzione SQL

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

gcloud

Per eseguire un'istruzione SQL su un database di un'istanza utilizzando la 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

Esegui 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. Consulta Modificare il comportamento di troncamento.

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

Terraform

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

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 modifiche

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

Preparare Cloud Shell

  1. Avvia Cloud Shell.

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

    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

Preparare la directory

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

  1. In Cloud Shell, crea una directory e un nuovo file all'interno della directory. Il nome del file deve avere l' .tf estensione, ad esempio main.tf. In questo tutorial, il file viene chiamato main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Se stai seguendo un tutorial, puoi copiare il codice campione in ogni sezione o passaggio.

    Copia il codice campione nel file main.tf appena creato.

    Facoltativamente, copia il codice da GitHub. Questa operazione è consigliata quando lo snippet Terraform fa parte di una soluzione end-to-end.

  3. Esamina e modifica i parametri di esempio da applicare al tuo ambiente.
  4. Salva le modifiche.
  5. Inizializza Terraform. Devi eseguire questa operazione una sola volta per directory. 
    terraform init

    Facoltativamente, per utilizzare la versione più recente del provider Google, includi l'opzione -upgrade: 

    terraform init -upgrade

Applica modifiche

  1. Esamina la configurazione e verifica che le risorse che Terraform creerà o aggiornerà corrispondano alle tue aspettative: 
    terraform plan

    Apporta le correzioni necessarie alla configurazione.

  2. Applica la configurazione Terraform eseguendo il comando seguente e inserendo yes al prompt: 
    terraform apply

    Attendi che Terraform visualizzi il messaggio "Apply complete!" (Applicazione completata).

  3. Apri il Google Cloud progetto per visualizzare i risultati. Nella Google Cloud console, 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 elimina le risorse in-database che ha creato. Per eliminarle, puoi aggiungere esplicitamente istruzioni 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
}

Esegui 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 come risponde l'API quando il risultato supera i 10 MB. Può essere FAIL_PARTIAL_RESULT o ALLOW_PARTIAL_RESULT. Consulta 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 per una risposta è di 10 MB. I risultati che superano questa dimensione 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 di dati 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 alle 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 viene raggiunto questo limite, le richieste successive non vanno a buon fine con il messaggio "At most 10 concurrent queries may be run on this instance. Try again later." (Su questa istanza è possibile eseguire al massimo 10 query simultanee.
  • Riprova più tardi.) o "Maximum concurrent reads 10 reached." (È stato raggiunto il numero massimo di letture simultanee: 10).
  • Se si verifica un errore di sintassi o di esecuzione dell'istruzione, non viene restituito alcun risultato.
  • Per Cloud SQL per MySQL, avvisi e notifiche sono disponibili solo per l'ultima istruzione di un'esecuzione con più istruzioni.
  • Per Cloud SQL per MySQL, le notifiche e gli avvisi sono disponibili solo per l'ultima istruzione di un'esecuzione multi-istruzione. Per ulteriori informazioni su come evitare questi errori, vedere Best practices for la gestione della memoria utilizzata. Un'istanza di database in esecuzione con un elevato utilizzo della memoria spesso causa problemi di prestazioni, blocchi o persino tempi di inattività del database.
  • 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 di dati può essere bloccata temporaneamente per motivi di integrità dei dati quando sono in corso determinate operazioni di manutenzione sull'istanza.
  • Se si verifica questa situazione, riprova più tardi. Per questo motivo, le richieste non andranno a buon fine con l'errore "not supported for instances in certain Assured Workloads control packages folders" per determinati progetti Assured Workloads e per i progetti con constraints/sql.restrictNoncompliantResourceCreation applicato manualmente.