Executar instruções SQL usando a API Data do Cloud SQL

MySQL | PostgreSQL | SQL Server

Nesta página, descrevemos como executar instruções SQL em bancos de dados em instâncias do Cloud SQL usando a API Data. Com a API Data, você usa a API Cloud SQL Admin e a CLI gcloud para executar instruções SQL em qualquer instância em que você tenha ativado o acesso à API Data.

É possível usar a API Data com instâncias que usam endereços IP públicos, acesso a serviços particulares ou o Private Service Connect. A API Data é compatível com todos os tipos de instruções SQL, incluindo linguagem de manipulação de dados (DML), linguagem de definição de dados (DDL) e linguagem de consulta de dados (DQL). A API Data é boa para executar instruções administrativas pequenas e rápidas, como criar funções ou usuários de banco de dados e fazer pequenas atualizações de esquema.

Antes de começar

Antes de executar instruções SQL em uma instância, faça o seguinte:

Configure a instância para a autenticação do banco de dados do IAM.
Adicione um usuário ou conta de serviço do IAM à instância e conceda à conta os papéis ou permissões necessários para executar instruções SQL.

Permissões ou papéis necessários

Por padrão, as contas de usuário ou de serviço com um dos seguintes papéis têm permissão para executar instruções SQL em uma instância do 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)

Também é possível definir um papel personalizado do IAM para a conta de usuário ou serviço que inclui a permissão cloudsql.instances.executesql. Essa permissão é suportada por papéis personalizados do IAM.

Ativar ou desativar a API Data

Para usar a API Data, é necessário ativá-la em cada instância. É possível desativar a API Data a qualquer momento.

Console

No console Google Cloud , acesse a página Instâncias do Cloud SQL.

Acesse "Instâncias do Cloud SQL"
Para abrir a página Visão geral de uma instância, clique no nome da instância.
No menu de navegação SQL, selecione Conexões.
Clique na guia Rede.
Marque a caixa de seleção Permitir API de dados.
Clique em Salvar.

gcloud

Para ativar o acesso à API Data em uma instância, use o comando gcloud sql instances patch com a flag --data-api-access=ALLOW_DATA_API:

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

Para desativar o acesso à API Data, use a flag --data-api-access=DISALLOW_DATA_API:

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

Substitua INSTANCE_NAME pelo nome da instância em que a API Data será ativada ou desativada.

Executar uma instrução SQL

É possível executar instruções SQL em bancos de dados na instância do Cloud SQL usando a CLI gcloud ou a API REST.

gcloud

Para executar uma instrução SQL em um banco de dados em uma instância usando a CLI gcloud, use o 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

Faça as seguintes substituições:

INSTANCE_NAME: o nome da instância.
DATABASE_NAME: o nome do banco de dados na instância.
SQL_STATEMENT: a instrução SQL a ser executada. Se a instrução contiver espaços ou caracteres especiais do shell, ela precisará estar entre aspas.
PARTIAL_RESULT_MODE: opcional. Controla como responder quando o resultado está incompleto. Pode ser ALLOW_PARTIAL_RESULT, FAIL_PARTIAL_RESULT ou PARTIAL_RESULT_MODE_UNSPECIFIED. Consulte Como modificar o comportamento de truncamento.

Também é possível incluir a flag --project=PROJECT_ID, se necessário.

Terraform

É possível usar a API Data no Terraform para provisionar recursos no banco de dados, como bancos de dados, tabelas, extensões, usuários e concessões de privilégios, sem se conectar manualmente à instância. Para executar um script SQL no Terraform, use o recurso google_sql_provision_script do 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]
}

Aplique as alterações

Para aplicar a configuração do Terraform em um projeto Google Cloud , siga as etapas nas seções a seguir.

Preparar o Cloud Shell

Inicie o Cloud Shell.
Defina o projeto Google Cloud padrão em que você quer aplicar as configurações do Terraform.

Você só precisa executar esse comando uma vez por projeto, e ele pode ser executado em qualquer diretório.
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
As variáveis de ambiente serão substituídas se você definir valores explícitos no arquivo de configuração do Terraform.

Preparar o diretório

Cada arquivo de configuração do Terraform precisa ter o próprio diretório, também chamado de módulo raiz.

No Cloud Shell, crie um diretório e um novo arquivo dentro dele. O nome do arquivo precisa ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o arquivo é chamado de main.tf.
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
Se você estiver seguindo um tutorial, poderá copiar o exemplo de código em cada seção ou etapa.

Copie o exemplo de código no main.tf recém-criado.

Se preferir, copie o código do GitHub. Isso é recomendado quando o snippet do Terraform faz parte de uma solução de ponta a ponta.
Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
Salve as alterações.
Inicialize o Terraform. Você só precisa fazer isso uma vez por diretório.
```
terraform init
```
Opcionalmente, para usar a versão mais recente do provedor do Google, inclua a opção -upgrade:
```
terraform init -upgrade
```

Aplique as alterações

Revise a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expectativas:
```
terraform plan
```
Faça as correções necessárias na configuração.
Para aplicar a configuração do Terraform, execute o comando a seguir e digite yes no prompt:
```
terraform apply
```
Aguarde até que o Terraform exiba a mensagem "Apply complete!".
Abra seu Google Cloud projeto para conferir os resultados. No console do Google Cloud , navegue até seus recursos na UI para verificar se foram criados ou atualizados pelo Terraform.

Excluir as alterações

A exclusão de um recurso google_sql_provision_script não remove os recursos no banco de dados que ele criou. Para excluir, adicione explicitamente instruções no script, como drop ... if exists, e aplique as mudanças.

REST

Para executar uma instrução SQL em um banco de dados em uma instância usando a API REST, envie uma solicitação POST ao endpoint executeSql:

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

O corpo da solicitação precisa conter o nome do banco de dados e a instrução SQL:

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

Faça as seguintes substituições:

PROJECT_ID: o ID do projeto.
INSTANCE_NAME: o nome da instância.
DATABASE_NAME: o nome do banco de dados na instância.
SQL_STATEMENT: a instrução SQL a ser executada.
PARTIAL_RESULT_MODE: opcional. Controla como a API responde quando o resultado excede 10 MB. Pode ser FAIL_PARTIAL_RESULT ou ALLOW_PARTIAL_RESULT. Consulte Como modificar o comportamento de truncamento.

Modificar o comportamento de truncamento

É possível controlar como os resultados grandes são processados ao executar SQL.

Inclua o campo "partialResultMode" na solicitação. Esse campo aceita os seguintes valores:
- FAIL_PARTIAL_RESULT: gera um erro se o resultado exceder 10 MB ou se apenas um resultado parcial puder ser recuperado. Não retorne o resultado.
- ALLOW_PARTIAL_RESULT: retorne um resultado truncado e defina partial_result como "true" se o resultado exceder 10 MB ou se apenas um resultado parcial puder ser recuperado devido a um erro. Não gere um erro.

Limitações

O limite de tamanho para uma resposta é de 10 MB. Os resultados que excederem esse tamanho serão truncados se partialResultMode estiver definido como ALLOW_PARTIAL_RESULT. Caso contrário, um erro será gerado.
As solicitações são limitadas a 0,5 MB.
Só é possível executar instruções SQL para instâncias do Cloud SQL para MySQL em execução.
O Cloud SQL não é compatível com o uso da API Data com instâncias configuradas para replicação de servidor externo.
As solicitações que levam mais de 30 segundos são canceladas. Não é possível definir um tempo limite de instrução maior usando SET SESSION MAX_EXECUTION_TIME. No Cloud SQL para MySQL 5.6 e 5.7, o tempo limite de instruções DDL de longa execução pode causar tabelas ou arquivos órfãos que não podem ser revertidos com segurança. Tenha cuidado com instruções como ALTER TABLE em tabelas grandes.
O Cloud SQL limita o número de solicitações executeSql simultâneas a 10 por instância para cada usuário. Se esse limite for atingido, as solicitações subsequentes vão falhar com a mensagem "No máximo 10 consultas simultâneas podem ser executadas nesta instância. Tente de novo mais tarde" ou "O número máximo de leituras simultâneas (10) foi atingido".
Cada resposta pode conter no máximo 10 mensagens ou avisos do banco de dados.
Se houver um erro de sintaxe ou de execução da instrução, nenhum resultado será retornado.
No Cloud SQL para MySQL, os avisos e alertas estão disponíveis apenas para a última instrução de uma execução com várias instruções.
Instruções que consomem muita memória podem causar erros de falta de memória. Para mais informações sobre como evitar esses erros, consulte Práticas recomendadas para gerenciar o uso da memória. Uma instância de banco de dados em execução com alta utilização de memória geralmente causa problemas de desempenho, interrupções ou até mesmo inatividade no banco de dados.
A API Data pode ser bloqueada temporariamente para fins de integridade de dados quando determinadas operações de manutenção estão em andamento na instância. Tente de novo mais tarde se isso acontecer.
A API Data ainda não garante a residência de dados. As solicitações vão falhar com o erro "indisponível para instâncias em determinadas pastas de pacotes de controle do Assured Workloads" para alguns projetos do Assured Workloads e para projetos com constraints/sql.restrictNoncompliantResourceCreation aplicado manualmente.

Executar instruções SQL usando a API Data do Cloud SQL Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Permissões ou papéis necessários

Ativar ou desativar a API Data

Console

gcloud

Executar uma instrução SQL

gcloud

Terraform

Aplique as alterações

Preparar o Cloud Shell

Preparar o diretório

Aplique as alterações

Excluir as alterações

REST

Modificar o comportamento de truncamento

Limitações

Executar instruções SQL usando a API Data do Cloud SQL