Nesta página, você verá informações e exemplos de conexão a uma instância do Cloud SQL por meio de um serviço em execução no Cloud Run.
Para instruções detalhadas sobre como executar um aplicativo da Web de amostra do Cloud Run conectado ao Cloud SQL, consulte o guia de início rápido para se conectar no Cloud Run
O Cloud SQL é um serviço de banco de dados totalmente gerenciado que ajuda a configurar, manter, gerenciar e administrar seus bancos de dados relacionais na nuvem.
O Cloud Run é uma plataforma de computação gerenciada que permite executar contêineres diretamente na infraestrutura do Google Cloud.
Configurar uma instância do Cloud SQL
- Ative a API Cloud SQL Admin no projeto do Google Cloud do qual você está se conectando,
caso ainda não tenha feito isso:
- Crie uma instância do Cloud SQL para PostgreSQL. Recomendamos que você escolha um
local da instância do Cloud SQL na mesma região do serviço do Cloud Run para melhorar a latência, evitar alguns custos de rede e reduzir
os riscos de falha entre regiões.
Por padrão, o Cloud SQL atribui um endereço IP público a uma nova instância. Você também tem a opção de atribuir um endereço IP privado. Para mais informações sobre as opções de conectividade de ambos, consulte a página Visão geral da conexão.
Configurar o Cloud Run
As etapas para configurar o Cloud Functions dependem do tipo de endereço IP atribuído à instância do Cloud SQL. Se você encaminhar todo o tráfego de saída por meio da saída VPC direta ou de um conector de acesso VPC sem servidor, use um endereço IP particular. Compare os dois métodos de saída de rede.IP público (padrão)
- Verifique se a instância tem um endereço IP público. Você pode verificar isso na página Visão geral da sua instância no Console do Google Cloud. Se precisar adicionar um, consulte a página Como configurar o IP público para ver instruções.
- Receba o INSTANCE_CONNECTION_NAME da instância. Esse valor pode ser encontrado
na página Visão geral da instância no
console do Google Cloud ou executando o
seguinte comando
gcloud sql instances describe
: Substitua INSTANCE_NAME pelo nome da sua instância do Cloud SQL.gcloud sql instances describe INSTANCE_NAME
- Acesse o CLOUD_RUN_SERVICE_ACCOUNT_NAME do seu serviço do Cloud Run. Encontre esse valor na página IAM do projeto que hospeda o serviço do Cloud Run no console do Google Cloud ou executando o seguinte comando
gcloud run services describe
no projeto que hospeda o serviço do Cloud Run: Substitua as seguintes variáveis:gcloud run services describe CLOUD_RUN_SERVICE_NAME --region CLOUD_RUN_SERVICE_REGION --format="value(spec.template.spec.serviceAccountName)"
- CLOUD_RUN_SERVICE_NAME: o nome do serviço do Cloud Run
- CLOUD_RUN_SERVICE_REGION: a região do seu serviço do Cloud Run
- Configure a conta de serviço do serviço do Cloud Run. Verifique se a conta de serviço tem os papéis e as permissões do Cloud SQL adequados para se conectar ao Cloud SQL.
Cloud SQL Client
(recomendável)Cloud SQL Admin
cloudsql.instances.connect
cloudsql.instances.get
- Se você estiver adicionando uma conexão do Cloud SQL a um novo serviço, o serviço precisa estar em contêiner e ser enviado para o Container Registry ou o Artifact Registry. Se você ainda não tiver uma conexão, consulte estas instruções sobre como criar e implantar uma imagem de contêiner.
-
A conta de serviço do seu serviço precisa de um dos seguintes
papéis do IAM:
Como qualquer alteração de configuração, definir uma nova configuração para a conexão do Cloud SQL leva à criação de uma nova revisão do Cloud Run. As revisões seguintes também receberão automaticamente essa conexão do Cloud SQL, a menos que você faça atualizações explícitas para alterá-la.
Console
-
Comece a configurar o serviço. Para adicionar conexões do Cloud SQL a um serviço, faça o seguinte:
- Na lista Serviços, clique no nome do serviço que você quer.
- Em Visualizar no Cloud Functions, clique no nome do serviço.
- Clique em Editar e implantar novamente.
- Ative a conexão com uma instância do Cloud SQL:
- Clique em Contêiner, variáveis e secrets, conexões e segurança .
- Clique na guia Contêiner.
- Role a tela até Conexões do Cloud SQL.
- Clique em Adicionar conexão.
- Clique no botão Ativar o Cloud SQL Admin se você ainda não tiver ativado a API Cloud SQL Admin.
- Se você estiver adicionando uma conexão a uma instância do Cloud SQL no projeto, selecione a instância do Cloud SQL que quiser no menu.
- Se você estiver usando uma instância do Cloud SQL de outro projeto, selecione string de conexão personalizada no menu e insira o nome completo da conexão da instância no formato PROJECT-ID:REGION:INSTANCE-ID.
- Para excluir uma conexão, mantenha o cursor à direita dela para exibir o ícone Excluir e clique nele.
-
Clique em Criar ou Implantar.
Linha de comando
Antes de usar qualquer um dos comandos abaixo, faça as seguintes substituições:
- IMAGE pela imagem que você está implantando
- SERVICE_NAME pelo nome do serviço do Cloud Run;
-
INSTANCE_CONNECTION_NAME pelo nome da conexão da instância do Cloud SQL ou uma lista de nomes de conexões separados por vírgulas.
Para implantar um novo contêiner, use o seguinte comando:
Para atualizar um serviço atual, use o seguinte comando:gcloud run deploy \ --image=IMAGE \ --add-cloudsql-instances=INSTANCE_CONNECTION_NAME
gcloud run services update SERVICE_NAME \ --add-cloudsql-instances=INSTANCE_CONNECTION_NAME
Terraform
O código a seguir cria um contêiner base do Cloud Run, com uma instância conectada do Cloud SQL.
-
Para aplicar as mudanças, insira
terraform apply
. - Para verificar as alterações, consulte o serviço do Cloud Run, clicando na guia Revisões e na guia Conexões.
IP particular
Se a conta de serviço de autorização pertencer a um projeto diferente daquele que contém a instância do Cloud SQL, faça isto:
- Nos dois projetos, ative a API Cloud SQL Admin.
- Na conta de serviço no projeto que contém a instância do Cloud SQL, adicione as permissões do IAM.
- Verifique se a instância do Cloud SQL criada anteriormente tem um endereço IP particular. Para adicionar um endereço IP interno, acesse Configurar IP particular.
- Configure o método de saída para se conectar à mesma rede VPC que a instância do Cloud SQL. Observe as seguintes condições:
- A saída VPC direta e o acesso VPC sem servidor aceitam a comunicação com redes VPC conectadas usando o Cloud VPN e o peering de rede VPC.
- A saída VPC direta e o acesso VPC sem servidor não são compatíveis com redes legadas.
- A menos que você esteja usando a VPC compartilhada, é necessário que um conector compartilhe o mesmo projeto e a mesma região do recurso que o utiliza, mas o conector pode enviar tráfego para recursos em regiões diferentes.
- Conecte-se usando o endereço de IP privado e a porta
5432
da instância.
Conecte-se ao Cloud SQL
Depois de configurar o Cloud Run conecte-se à instância do Cloud SQL.
IP público (padrão)
Para caminhos de IP público, o Cloud Run fornece criptografia e se conecta usando o proxy do Cloud SQL Auth de duas maneiras:
- Com soquetes Unix
- Com um conector do Cloud SQL
Usar o Secret Manager
O Google recomenda que você use o Secret Manager para armazenar informações sensíveis, como credenciais do SQL. É possível transmitir secrets como variáveis de ambiente ou montá-los como um volume com o Cloud Run.
Depois de criar um secret no Secret Manager, atualize um serviço existente com o seguinte comando:
Linha de comando
gcloud run services update SERVICE_NAME \ --add-cloudsql-instances=INSTANCE_CONNECTION_NAME --update-env-vars=INSTANCE_CONNECTION_NAME=INSTANCE_CONNECTION_NAME_SECRET \ --update-secrets=DB_USER=DB_USER_SECRET:latest \ --update-secrets=DB_PASS=DB_PASS_SECRET:latest \ --update-secrets=DB_NAME=DB_NAME_SECRET:latest
Terraform
A instrução a seguir cria recursos secretos para armazenar com segurança os valores de usuário, senha e nome do banco de dados usando google_secret_manager_secret
e google_secret_manager_secret_version
. Observe que você precisa atualizar a conta do serviço de computação do projeto para ter acesso a cada secret.
Atualize o recurso principal do Cloud Run para incluir os novos secrets.
Para aplicar as mudanças, insira terraform apply
.
O comando de exemplo usa a versão do secret, latest. No entanto, o Google recomenda fixar o secret em uma versão específica, SECRET_NAME:v1.
IP particular
Para caminhos IP particulares, o aplicativo se conecta diretamente à instância por uma rede VPC. Esse método usa TCP para a conexão direta com a instância do Cloud SQL sem usar o proxy de autenticação do Cloud SQL.
Conectar com TCP
Conecte-se usando o endereço IP privado da sua instância do Cloud SQL como o host e a porta 5432
.
Python
Para ver esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.
Java
Para conferir esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.
Observação:
- CLOUD_SQL_CONNECTION_NAME precisa ser representado como <MEU-PROJETO>:<REGIÃO-DA-INSTÂNCIA>:<NOME-DA-INSTÂNCIA>
- O uso do argumento ipTypes=PRIVATE forçará o SocketFactory a se conectar ao IP privado associado de uma instância
- Consulte os requisitos de versão de fábrica do soquete JDBC para o arquivo pom.xml aqui.
Node.js
Para ver esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.
Go
Para ver esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.
C#
Para ver esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub (em inglês).
Ruby
Para ver esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.
PHP
Para ver esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.
Práticas recomendadas e outras informações
Use o proxy do Cloud SQL Auth ao testar seu aplicativo localmente. Consulte o guia de início rápido para o uso do proxy de autenticação do Cloud SQL e confira instruções detalhadas.
Se preferir, teste usando o Cloud SQL Proxy por meio de um contêiner do Docker.
Pools de conexões
As conexões aos bancos de dados podem ser descartadas pelo próprio servidor de banco de dados ou pela infraestrutura da plataforma. Recomendamos o uso de uma biblioteca de cliente compatível com pools de conexões que reconectam automaticamente conexões de cliente danificadas. Para exemplos mais detalhados sobre como usar pools de conexões, consulte a página Como gerenciar conexões de banco de dados.Limites de conexão
As edições MySQL e PostgreSQL do Cloud SQL impõem um limite máximo de conexões simultâneas. Esses limites podem variar dependendo do mecanismo do banco de dados escolhido. Consulte a página Limites e cotas do Cloud SQL.As instâncias de contêiner do Cloud Run são limitadas a 100 conexões com um banco de dados do Cloud SQL. Cada instância de um serviço ou job do Cloud Run pode ter 100 conexões com o banco de dados e, conforme esse serviço ou job é escalonado, o número total de conexões por implantação pode aumentar.
Limite o número máximo de conexões por instância usando um pool de conexões. Para exemplos mais detalhados sobre como limitar o número de conexões, consulte a página Como gerenciar conexões de banco de dados.
Limites de cota da API
O Cloud Run fornece um mecanismo que se conecta usando o proxy do Cloud SQL Auth, por meio da API Cloud SQL Admin. Os limites de cota da API se aplicam ao proxy do Cloud SQL Auth. A cota da API Cloud SQL Admin usada é aproximadamente duas vezes o número de instâncias do Cloud SQL configuradas pelo número de instâncias do Cloud Run de um serviço específico implantado a qualquer momento. É possível limitar ou aumentar o número de instâncias do Cloud Run para modificar a cota de API esperada consumida.A seguir
- Saiba mais sobre o Cloud Run.
- Saiba mais sobre como criar e implantar imagens de contêiner.
- Veja um exemplo completo em Python de como usar o Cloud Run com o PostgreSQL.