Esegui istruzioni SQL utilizzando l'API Cloud SQL Data

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:

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.

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=DENY_DATA_API:

gcloud sql instances patch INSTANCE_NAME --data-api-access=DENY_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 beta sql instances execute-sql:

gcloud beta 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.

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"
}

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 le istruzioni come ALTER TABLE nelle 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 e viene visualizzato il messaggio "Maximum concurrent reads 10 reached" (Letture simultanee massime 10 raggiunte).
  • 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 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.