Esegui istruzioni SQL utilizzando l'API Cloud SQL Data

MySQL | PostgreSQL | SQL Server

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. Puoi anche utilizzare l'API di dati per abilitare le estensioni PostgreSQL.

Prima di iniziare

Prima di poter eseguire istruzioni SQL su un'istanza:

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

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

Nella Google Cloud console, 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 di dati.
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 = "POSTGRES_17"

  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. If a service account is used
 * and the instance is Postgres, trim the ".gserviceaccount.com"
 * suffix to avoid exceeding the username length limit.
*/
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.
  database_roles = ["cloudsqlsuperuser"]
}

resource "google_sql_database" "database" {
  name     = "my-database"
  instance = google_sql_database_instance.instance.name
}

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 TABLE IF NOT EXISTS table1 ( col VARCHAR(16) NOT NULL );"

  instance = google_sql_database_instance.instance.name
  database = google_sql_database.database.name
  description = "sql script to create tables"

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

Applicare le modifiche

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

Preparare Cloud Shell

Avvia Cloud Shell.
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).

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
```
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.
Esamina 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
```
Facoltativamente, per utilizzare la versione più recente del provider Google, includi l'opzione -upgrade:
```
terraform init -upgrade
```

Applicare le modifiche

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.
Applica la configurazione Terraform eseguendo il comando seguente e inserendo yes al prompt:
```
terraform apply
```
Attendi che Terraform visualizzi il messaggio "Apply complete!".
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.

Eliminare le modifiche

L'eliminazione di una risorsa google_sql_provision_script non comporta l'eliminazione delle risorse in-database create. 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 PostgreSQL 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 STATEMENT_TIMEOUT non è supportata.
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 "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.
Se si verifica un errore di sintassi o di esecuzione dell'istruzione, non viene restituito alcun risultato. Per ulteriori informazioni su come evitare questi errori, vedere Best practices for la gestione della memoria utilizzata. Per ulteriori informazioni su come evitare questi errori, consulta Best practice per la gestione dell'utilizzo della memoria.
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 questo problema, riprova più tardi. 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.

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

Abilitare o disabilitare l'API di dati

Console

gcloud

Eseguire un'istruzione SQL

gcloud

Terraform

Applicare le modifiche

Preparare Cloud Shell

Preparare la directory

Applicare le modifiche

Eliminare le modifiche

REST

Modificare il comportamento di troncamento

Limitazioni

Esegui istruzioni SQL utilizzando l'API Cloud SQL Data