Esegui istruzioni SQL utilizzando l'API Cloud SQL Data

Console

1. Nella console Cloud de Confiance , 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 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 di dati.

REST

Per abilitare l'accesso all'API di dati su un'istanza, invia una richiesta PATCH all'endpoint instances.patch:

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

Il corpo della richiesta deve contenere il campo dataApiAccess impostato su ALLOW_DATA_API:

{
  "dataApiAccess": "ALLOW_DATA_API"
}

Per disattivare l'accesso all'API di dati, imposta dataApiAccess su DISALLOW_DATA_API.

gcloud

Per eseguire un'istruzione SQL su un database in 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. Consulta Modifica del 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, come 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 = "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 ".s3ns-system.iam.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. For least privilege, you can create smaller roles
  # and then assign them to this user in place of `cloudsqlsuperuser`.
  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]
}

Applica le modifiche

Per applicare la configurazione di Terraform in un progetto Cloud de Confiance , completa i passaggi descritti nelle sezioni seguenti.

Prepara Cloud Shell

1. Avvia Cloud Shell.

2. Imposta il progetto Cloud de Confiance 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 principale).

1. 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

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 opzione è 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 l'ultima versione del provider Google, includi l'opzione -upgrade:

   terraform init -upgrade

Applica le 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 di Terraform eseguendo questo comando e inserendo yes al prompt:

   terraform apply

   Attendi finché Terraform non visualizza il messaggio "Apply complete!".

3. Apri il tuo progetto Cloud de Confiance per visualizzare i risultati. Nella console Cloud de Confiance , 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 esplicitamente istruzioni nello script, ad esempio drop ... if exists, e poi applicare le modifiche.

REST

Per eseguire un'istruzione SQL su un database in 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 la risposta dell'API supera i 10 MB. Può essere FAIL_PARTIAL_RESULT, ALLOW_PARTIAL_RESULT o PARTIAL_RESULT_MODE_UNSPECIFIED. Consulta Modifica del comportamento di troncamento.

gcloud

Per eseguire un'istruzione SQL su un database in 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 \
--user=USER \
--password-secret-version=PASSWORD_SECRET_VERSION \
--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.
• USER: l'utente del database con cui eseguire l'autenticazione.
• PASSWORD_SECRET_VERSION: il nome della risorsa del secret di Secret Manager contenente la password dell'utente del database. Il secret deve essere un secret regionale e deve essere archiviato nella stessa regione dell'istanza Cloud SQL. Il formato del nome della risorsa previsto è projects/{project}/locations/{location}/secrets/{secret}/versions/{secret_version}.
• 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 Modifica del comportamento di troncamento.

Terraform

Puoi utilizzare l'API Data su Terraform per eseguire il provisioning di risorse nel database, come 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_user" "built_in_user" {
  name     = "tf-user"
  host     = "%"  # Don't set this field for PostgreSQL and SQL Server.
  instance = google_sql_database_instance.instance.name
  password = "changeme"
  type     = "BUILT_IN"
}

# Create a regional secret. Global secrets are not supported even if
# located in one region only.
resource "google_secret_manager_regional_secret" "secret" {
  secret_id = "db-password"

  # Use the same region as the Cloud SQL instance.
  location = "us-central1"
}

resource "google_secret_manager_regional_secret_version" "secret_version" {
  secret = google_secret_manager_regional_secret.secret.id
  secret_data = "changeme"
}

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"
  user = google_sql_user.built_in_user.name

  # The location should be the same as the Cloud SQL instance's location.
  password_secret_version = "projects/my-project/locations/us-central1/secrets/db-password/versions/latest"

  # The built-in database user and password secret version must be created
  # first. Cloud SQL will retrieve password from Secret Manager
  # and connect to this user account to execute your script.
  depends_on = [
    google_sql_user.built_in_user,
    google_secret_manager_regional_secret_version.secret_version
  ]
}

Applica le modifiche

Per applicare la configurazione di Terraform in un progetto Cloud de Confiance , completa i passaggi descritti nelle sezioni seguenti.

Prepara Cloud Shell

1. Avvia Cloud Shell.

2. Imposta il progetto Cloud de Confiance 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 principale).

1. 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

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 opzione è 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 l'ultima versione del provider Google, includi l'opzione -upgrade:

   terraform init -upgrade

Applica le 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 di Terraform eseguendo questo comando e inserendo yes al prompt:

   terraform apply

   Attendi finché Terraform non visualizza il messaggio "Apply complete!".

3. Apri il tuo progetto Cloud de Confiance per visualizzare i risultati. Nella console Cloud de Confiance , 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 esplicitamente istruzioni nello script, ad esempio drop ... if exists, e poi applicare le modifiche.

REST

Per eseguire un'istruzione SQL su un database in 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",
  "user": "USER",
  "passwordSecretVersion": "PASSWORD_SECRET_VERSION",
  "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.
• USER: l'utente del database con cui eseguire l'autenticazione.
• PASSWORD_SECRET_VERSION: il nome della risorsa del secret di Secret Manager contenente la password dell'utente del database. Il secret deve essere un secret regionale e deve essere archiviato nella stessa regione dell'istanza Cloud SQL. Il formato del nome della risorsa previsto è projects/{project}/locations/{location}/secrets/{secret}/versions/{secret_version}.
• PARTIAL_RESULT_MODE: facoltativo. Controlla il modo in cui la risposta dell'API supera i 10 MB. Può essere FAIL_PARTIAL_RESULT, ALLOW_PARTIAL_RESULT o PARTIAL_RESULT_MODE_UNSPECIFIED. Consulta Modifica del comportamento di troncamento.