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

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:

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.

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

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

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.

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

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: retorna um resultado truncado e define 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 "Maximum concurrent reads 10 reached".
  • 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.