| list_instances |
Liste todas as instâncias do Cloud SQL no projeto.
|
| get_instance |
Receba os detalhes de uma instância do Cloud SQL.
|
| create_instance |
Inicia a criação de uma instância do Cloud SQL.
A menos que especificado de outra forma, uma instância recém-criada usa a configuração padrão de um ambiente de desenvolvimento. Confira a configuração padrão de uma instância em um ambiente de desenvolvimento:
{
"tier": "db-perf-optimized-N-2",
"data_disk_size_gb": 100,
"region": "us-central1",
"database_version": "POSTGRES_18",
"edition": "ENTERPRISE_PLUS",
"availability_type": "ZONAL",
"tags": [{"environment": "dev"}]
}
A configuração a seguir é recomendada para uma instância em um ambiente de produção:
{
"tier": "db-perf-optimized-N-8",
"data_disk_size_gb": 250,
"region": "us-central1",
"database_version": "POSTGRES_18",
"edition": "ENTERPRISE_PLUS",
"availability_type": "REGIONAL",
"tags": [{"environment": "prod"}]
}
A seguinte configuração de instância é recomendada para o SQL Server:
{
"tier": "db-perf-optimized-N-8",
"data_disk_size_gb": 250,
"region": "us-central1",
"database_version": "SQLSERVER_2022_STANDARD",
"edition": "ENTERPRISE_PLUS",
"availability_type": "REGIONAL",
"tags": [{"environment": "prod"}]
}
|
| execute_sql |
Execute qualquer instrução SQL válida, incluindo instruções de linguagem de definição de dados (DDL), linguagem de controle de dados (DCL), linguagem de consulta de dados (DQL) ou linguagem de manipulação de dados (DML), em uma instância do Cloud SQL. Para oferecer suporte à ferramenta execute_sql, uma instância do Cloud SQL precisa atender aos seguintes requisitos:
- O valor de
data_api_access precisa ser definido como ALLOW_DATA_API.
- Para uma instância do MySQL, a flag de banco de dados
cloudsql_iam_authentication precisa ser definida como on. Para uma instância do PostgreSQL, a flag de banco de dados cloudsql.iam_authentication precisa ser definida como on.
- Uma conta de usuário ou de serviço do IAM (
CLOUD_IAM_USER ou CLOUD_IAM_SERVICE_ACCOUNT) é necessária para chamar a ferramenta execute_sql. A ferramenta executa as instruções SQL usando os privilégios do usuário do banco de dados conectado com a autenticação de banco de dados do IAM.
Depois de usar a ferramenta create_instance para criar uma instância, use a ferramenta create_user para criar uma conta de usuário do IAM para o usuário conectado ao projeto. A ferramenta execute_sql tem as seguintes limitações:
- Se uma instrução SQL retornar uma resposta maior que 10 MB, ela será truncada.
- A ferramenta
execute_sql tem um tempo limite padrão de 30 segundos. Se uma consulta levar mais de 30 segundos, a ferramenta vai retornar um erro DEADLINE_EXCEEDED.
- A ferramenta
execute_sql não é compatível com o SQL Server.
Se você receber erros semelhantes a "A autenticação do IAM não está ativada para a instância", use a ferramenta get_instance para verificar o valor da flag de autenticação do banco de dados do IAM para a instância. Se você receber erros como "A instância não permite o uso de executeSql para acessar esta instância", use a ferramenta get_instance para verificar a configuração data_api_access. Quando você recebe erros de autenticação:
- Verifique se a conta de usuário conectada no momento existe como um usuário do IAM na instância usando a ferramenta
list_users.
- Se a conta de usuário do IAM não existir, use a ferramenta
create_user para criar a conta de usuário do IAM para o usuário conectado.
- Se o usuário conectado no momento não tiver as funções de usuário do banco de dados adequadas, use a ferramenta
update_user para conceder funções de banco de dados ao usuário. Por exemplo, a função cloudsqlsuperuser pode fornecer a um usuário do IAM muitas permissões necessárias.
Verifique se o usuário conectado no momento tem as permissões corretas do IAM atribuídas ao projeto. Use o comando gcloud projects get-iam-policy [PROJECT_ID] para verificar se o usuário tem as permissões ou os papéis do IAM adequados atribuídos ao projeto.
- O usuário precisa ter a permissão
cloudsql.instance.login para fazer a autenticação automática de banco de dados do IAM.
- O usuário precisa ter a permissão
cloudsql.instances.executeSql para executar instruções SQL usando a ferramenta execute_sql ou a API executeSql.
- Papéis comuns do IAM que contêm as permissões necessárias: usuário da instância do Cloud SQL (
roles/cloudsql.instanceUser) ou administrador do Cloud SQL (roles/cloudsql.admin)
Ao receber um ExecuteSqlResponse, sempre verifique os campos message e status no corpo da resposta. Um código de status HTTP bem-sucedido não garante o sucesso total de todas as instruções SQL. Os campos message e status indicam se houve erros ou avisos parciais durante a execução da instrução SQL.
|
| get_operation |
Receber o status de uma operação de longa duração. Uma operação de longa duração pode levar vários minutos para ser concluída. Se uma operação levar muito tempo, use uma ferramenta de linha de comando para pausar por 30 segundos antes de verificar novamente o status da operação.
|
| create_user |
Crie um usuário de banco de dados para uma instância do Cloud SQL.
- Essa ferramenta retorna uma operação de longa duração. Use a ferramenta
get_operation para pesquisar o status até que a operação seja concluída.
- Ao usar a ferramenta
create_user, especifique o tipo de usuário: CLOUD_IAM_USER ou CLOUD_IAM_SERVICE_ACCOUNT.
- Por padrão, o usuário recém-criado recebe a função
cloudsqlsuperuser, a menos que você especifique outras funções de banco de dados explicitamente na solicitação.
- É possível usar um usuário recém-criado com a ferramenta
execute_sql se ele for um usuário do IAM conectado no momento. A ferramenta execute_sql executa as instruções SQL usando os privilégios do usuário do banco de dados conectado com a autenticação de banco de dados do IAM.
A ferramenta create_user tem as seguintes limitações:
- Não é possível criar um usuário integrado com uma senha.
- A ferramenta
create_user não aceita a criação de um usuário para o SQL Server.
Para criar um usuário do IAM no PostgreSQL:
- O nome de usuário do banco de dados precisa ser o endereço de e-mail do usuário do IAM e estar todo em letras minúsculas. Por exemplo, para criar um usuário para o usuário do IAM do PostgreSQL
example-user@example.com, use a seguinte solicitação:
{
"name": "example-user@example.com",
"type": "CLOUD_IAM_USER",
"instance":"test-instance",
"project": "test-project"
}
O nome de usuário do banco de dados criado para o usuário do IAM é example-user@example.com. Para criar uma conta de serviço do IAM no PostgreSQL:
- O nome de usuário do banco de dados precisa ser criado sem o sufixo
.gserviceaccount.com, mesmo que o endereço de e-mail completo da conta seja service-account-name@project-id.iam.gserviceaccount.com. Por exemplo, para criar uma conta de serviço do IAM para PostgreSQL, use o seguinte formato de solicitação:
{
"name": "test@test-project.iam",
"type": "CLOUD_IAM_SERVICE_ACCOUNT",
"instance": "test-instance",
"project": "test-project"
}
O nome de usuário do banco de dados criado para a conta de serviço do IAM é test@test-project.iam. Para criar um usuário ou uma conta de serviço do IAM no MySQL:
- Quando o Cloud SQL para MySQL armazena um nome de usuário, ele trunca o @ e o nome de domínio do endereço de e-mail do usuário ou da conta de serviço. Por exemplo,
example-user@example.com torna-se example-user.
- Por esse motivo, não é possível adicionar dois usuários do IAM ou contas de serviço com o mesmo nome de usuário, mas nomes de domínio diferentes à mesma instância do Cloud SQL.
- Por exemplo, para criar um usuário para o usuário do IAM do MySQL
example-user@example.com, use a seguinte solicitação:
{
"name": "example-user@example.com",
"type": "CLOUD_IAM_USER",
"instance": "test-instance",
"project": "test-project"
}
O nome de usuário do banco de dados criado para o usuário do IAM é example-user.
- Por exemplo, para criar a conta de serviço do IAM do MySQL
service-account-name@project-id.iam.gserviceaccount.com, use a seguinte solicitação:
{
"name": "service-account-name@project-id.iam.gserviceaccount.com",
"type": "CLOUD_IAM_SERVICE_ACCOUNT",
"instance": "test-instance",
"project": "test-project"
}
O nome de usuário do banco de dados criado para a conta de serviço do IAM é service-account-name.
|
| update_user |
Atualize um usuário de banco de dados para uma instância do Cloud SQL. Um caso de uso comum para o update_user é conceder a um usuário a função cloudsqlsuperuser, que pode fornecer a ele muitas permissões necessárias. Essa ferramenta só aceita a atualização de usuários para atribuir papéis de banco de dados.
- Essa ferramenta retorna uma operação de longa duração. Use a ferramenta
get_operation para pesquisar o status até que a operação seja concluída.
- Antes de chamar a ferramenta
update_user, sempre verifique a configuração atual do usuário, como o tipo de usuário, com a ferramenta list_users.
- Como um caso especial para o MySQL, se a ferramenta
list_users retornar um endereço de e-mail completo para o campo iamEmail, por exemplo, {name=test-account,
iamEmail=test-account@project-id.iam.gserviceaccount.com}, na solicitação update_user, use o endereço de e-mail completo no campo iamEmail do campo name do toolrequest. Exemplo: name=test-account@project-id.iam.gserviceaccount.com.
Parâmetros principais para atualizar as funções dos usuários:
database_roles: uma lista de papéis de banco de dados a serem atribuídos ao usuário.revokeExistingRoles: um campo booleano (padrão: "false") que controla como as funções atuais são processadas. Como as atualizações de função funcionam:
Se revokeExistingRoles for verdadeiro:
- Todas as funções concedidas ao usuário, mas NÃO na lista
database_roles fornecida, serão REVOGADAS.
- A revogação se aplica apenas a papéis que não são do sistema. Funções do sistema, como
cloudsqliamuser, não serão revogadas.
- Todas as funções na lista
database_roles que o usuário ainda NÃO tem serão CONCEDIDAS.
- Se
database_roles estiver vazio, TODOS os papéis não relacionados ao sistema serão revogados.
Se revokeExistingRoles for "false" (padrão):
- Todas as funções na lista
database_roles que o usuário ainda NÃO tem serão CONCEDIDAS.
- Os papéis atuais que NÃO estão na lista
database_roles são MANTIDOS.
- Se
database_roles estiver vazio, não haverá mudança nos papéis do usuário.
Exemplos:
|
| clone_instance |
Crie uma instância do Cloud SQL como um clone de uma instância de origem.
- Essa ferramenta retorna uma operação de longa duração. Use a ferramenta
get_operation para pesquisar o status até que a operação seja concluída.
- A operação de clonagem pode levar vários minutos. Use uma ferramenta de linha de comando para pausar por 30 segundos antes de verificar o status novamente.
|
| update_instance |
Atualiza parcialmente as configurações de configuração de uma instância do Cloud SQL.
- Essa ferramenta retorna uma operação de longa duração. Use a ferramenta
get_operation para pesquisar o status até que a operação seja concluída.
|
| list_users |
Listar todos os usuários de banco de dados de uma instância do Cloud SQL.
|
| import_data |
Importar dados para uma instância do Cloud SQL. Se o arquivo não começar com gs://, a suposição é que ele está armazenado localmente. Se o arquivo for local, ele precisará ser enviado para o Cloud Storage antes de você fazer a chamada import_data. Para fazer upload do arquivo no Cloud Storage, use os comandos gcloud ou gsutil. Antes de fazer upload do arquivo para o Cloud Storage, considere se você quer usar um bucket atual ou criar um novo no projeto fornecido. Depois que o arquivo é enviado para o Cloud Storage, a conta de serviço da instância precisa ter permissões suficientes para ler o arquivo enviado do bucket do Cloud Storage. Isso pode ser feito da seguinte forma:
- Use a ferramenta
get_instance para receber o endereço de e-mail da conta de serviço da instância. Na saída da ferramenta, acesse o valor do campo serviceAccountEmailAddress.
- Conceda à conta de serviço da instância o papel
storage.objectAdmin no bucket do Cloud Storage fornecido. Use um comando como gcloud storage buckets
add-iam-policy-binding ou uma solicitação para a API Cloud Storage. Pode levar de dois a sete minutos ou mais para que a função seja concedida e as permissões sejam propagadas para a conta de serviço no Cloud Storage. Se você encontrar um erro de permissões após atualizar a política do IAM, aguarde alguns minutos e tente de novo.
Depois que as permissões forem concedidas, você poderá importar os dados. Recomendamos que você deixe os parâmetros opcionais vazios e use os padrões do sistema. O tipo de arquivo geralmente é determinado pela extensão. Por exemplo, se o arquivo for SQL, .sql ou .csv para arquivo CSV. Confira a seguir um exemplo de importContext SQL para MySQL.
{
"uri": "gs://sample-gcs-bucket/sample-file.sql",
"kind": "sql#importContext",
"fileType": "SQL"
}
Não há um parâmetro database para o MySQL, já que o nome do banco de dados precisa estar presente no arquivo SQL. Especifique apenas um URI. Nenhum outro campo é obrigatório além de importContext. Para o PostgreSQL, o campo database é obrigatório. Confira a seguir um exemplo de importContext do PostgreSQL com o campo database especificado.
{
"uri": "gs://sample-gcs-bucket/sample-file.sql",
"kind": "sql#importContext",
"fileType": "SQL",
"database": "sample-db"
}
A ferramenta import_data retorna uma operação de longa duração. Use a ferramenta get_operation para pesquisar o status até que a operação seja concluída.
|
