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. Você também pode usar a API Data para ativar extensões do PostgreSQL.

Antes de começar

Antes de executar instruções SQL em uma instância, siga estas etapas.

Configurar o usuário do banco de dados

A API Data precisa ser autenticada como um usuário do banco de dados para executar instruções SQL. É possível se autenticar como um usuário integrado, um usuário do IAM, uma conta de serviço do IAM ou um grupo do IAM.

Para autenticar usando o IAM, faça o seguinte:

1. Configure a instância para a autenticação do banco de dados do IAM.
2. Adicione um usuário, conta de serviço ou grupo do IAM à instância.
3. Conceda à conta os papéis ou privilégios necessários para executar instruções SQL. É possível atribuir funções de banco de dados ao criar a conta ou atualizar a conta. Se você criou papéis de banco de dados personalizados com privilégios mínimos, atribua-os à conta. Caso contrário, atribua o papel predefinido cloudsqlsuperuser à conta, use a API Data para criar novos papéis de banco de dados personalizados com menos privilégios e conceda os novos papéis à conta em vez de cloudsqlsuperuser.

Para se autenticar como um usuário integrado usando senha, faça o seguinte:

1. Crie um usuário.
2. Use o Secret Manager para criar um secret regional e armazenar a senha. Por segurança, a API Data solicita o nome do recurso do secret em vez da senha na solicitação de API. O segredo regional precisa ser armazenado na mesma região que a instância do Cloud SQL. Um secret criado usando o endpoint global do Secret Manager não é compatível, mesmo que seja armazenado na mesma região.
Como prática recomendada,
3. Defina condições do IAM opcionais para permitir que um usuário acesse um secret específico, mas não outros secrets no projeto.

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

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

   Acesse "Instâncias do Cloud SQL"

2. Para abrir a página Visão geral de uma instância, clique no nome da instância.
3. No menu de navegação SQL, selecione Conexões.
4. Clique na guia Rede.
5. Marque a caixa de seleção Permitir API Data.
6. 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 você quer ativar ou desativar a API Data.

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.

Para se conectar usando o IAM:

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.

Para se conectar como um usuário integrado usando senha:

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

Faça as seguintes substituições:

• USER: o usuário do banco de dados a ser autenticado.
• PASSWORD_SECRET_VERSION: o nome do recurso do secret do Secret Manager que contém a senha do usuário do banco de dados. O secret precisa ser regional e armazenado na mesma região da instância do Cloud SQL. O formato esperado do nome do recurso é projects/{project}/locations/{location}/secrets/{secret}/versions/{secret_version}.

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 = "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     = "[e-mail]"
  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]
}

Aplique as alterações

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

Preparar o Cloud Shell

1. Inicie o Cloud Shell.

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

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

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

3. Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
4. Salve as alterações.
5. 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

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

2. 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!".

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

Observação:as amostras do Terraform geralmente presumem que as APIs necessárias estejam ativadas no seu projeto Google Cloud .

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, ALLOW_PARTIAL_RESULT ou PARTIAL_RESULT_MODE_UNSPECIFIED. 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 incluindo o campo "partialResultMode" na solicitação. Esse campo aceita os seguintes valores:

• FAIL_PARTIAL_RESULT: Padrão. Gere 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.
• PARTIAL_RESULT_MODE_UNSPECIFIED: modo não especificado, efetivamente o mesmo que FAIL_PARTIAL_RESULT.

Limitações

• O limite de tamanho para uma resposta é de 10 MB. Resultados que excedem esse tamanho sã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 PostgreSQL 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 STATEMENT_TIMEOUT.
• 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.
• 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.
• O script SQL e a resposta de execução podem transitar por locais intermediários entre o cliente e o local da instância de destino. Por esse motivo, 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.