Nesta página você aprende como se conectar a uma instância do Cloud SQL para PostgreSQL a partir de um aplicativo do App Engine e como fazer leituras e gravações no Cloud SQL. O Cloud SQL é um banco de dados SQL que reside na nuvem do Google.
Para saber mais, consulte a documentação do Cloud SQL. Para informações sobre preços e limites do Cloud SQL, consulte a página de preços do Cloud SQL. Os aplicativos do App Engine também estão sujeitos às cotas dessa plataforma.
Antes de começar
- Crie ou selecione um projeto do GCP no Console do GCP e verifique se o projeto inclui um aplicativo do App Engine e se o faturamento está ativado:
Acessar o App EngineO Painel será aberto se houver um aplicativo do App Engine no projeto e se o faturamento estiver ativado. Caso contrário, siga as instruções para escolher uma região e ativar o faturamento.
- Ativar Cloud SQL API.
-
Para implantar o aplicativo com a ferramenta
gcloud
, você precisa fazer o download, instalar e inicializar o SDK do Cloud:
Fazer o download do SDKSe a ferramenta
gcloud
já estiver instalada e você quiser configurá-la para usar um ID do projeto do GCP diferente do inicializado, consulte Como gerenciar as configurações do SDK do Cloud.
Como configurar a instância do Cloud SQL
Para criar e configurar uma instância do Cloud SQL, siga as seguintes etapas:
- Crie uma instância do Cloud SQL para PostgreSQL.
- Defina a senha do usuário padrão na instância do Cloud SQL, caso ainda não tenha feito isso:
gcloud sql users set-password postgres no-host --instance [INSTANCE_NAME] --password [PASSWORD]
- Se não quiser usar o usuário padrão para se conectar, crie um usuário.
-
Registre o nome da conexão da instância:
gcloud sql instances describe [INSTANCE_NAME]
Por exemplo:
connectionName: project1:us-central1:instance1
Você também encontra esse valor na página de Detalhes da instância no Console do Google Cloud Platform.
-
Crie um banco de dados na instância do Cloud SQL.
gcloud sql databases create [DATABASE_NAME] --instance=[INSTANCE_NAME]
Para mais informações sobre como criar e gerenciar bancos de dados, consulte a documentação do Cloud SQL.
Como configurar o ambiente local
Depois de implantado, seu aplicativo usa o Cloud SQL Proxy incorporado ao ambiente de execução do App Engine para se comunicar com a instância do Cloud SQL. No entanto, para testar o aplicativo no local, é necessário instalar e usar uma cópia local do Cloud SQL Proxy no ambiente de desenvolvimento.
Para executar tarefas administrativas básicas na instância do Cloud SQL, use o cliente de administração do banco de dados ou o Console do GCP.
Autentique a ferramenta
gcloud
para usar o proxy para se conectar a partir da máquina local:gcloud auth application-default login
Instale o Cloud SQL Proxy:
Linux de 64 bits
- Faça o download do proxy:
wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
- Torne o proxy executável:
chmod +x cloud_sql_proxy
Linux de 32 bits
- Faça o download do proxy:
wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
- Torne o proxy executável:
chmod +x cloud_sql_proxy
macOS de 64 bits
- Faça o download do proxy:
curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64
- Torne o proxy executável:
chmod +x cloud_sql_proxy
macOS de 32 bits
- Faça o download do proxy:
curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
- Torne o proxy executável:
chmod +x cloud_sql_proxy
Windows de 64 bits
Para fazer o download do proxy, clique com o botão direito em https://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe e selecione Salvar link como. Renomeie o arquivo comocloud_sql_proxy.exe
.Windows de 32 bits
Para fazer o download do proxy, clique com o botão direito em https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe e selecione Salvar link como. Renomeie o arquivo comocloud_sql_proxy.exe
.- Faça o download do proxy:
Execute o proxy:
Dependendo da linguagem e do ambiente, é possível iniciar o proxy usando os soquetes TCP ou Unix.
Soquetes TCP
Copie o nome de conexão da instância da página Detalhes da instância.
Por exemplo:
myproject:us-central1:myinstance
.- Se você estiver usando uma conta de serviço para autenticar o proxy, anote o local em que a chave privada foi criada na máquina cliente durante a criação da conta de serviço.
- Inicie o proxy.
Algumas strings possíveis de chamada do proxy:
- Usando autenticação do SDK do Cloud:
./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:5432
A porta especificada não pode estar em uso, por exemplo, por um servidor de banco de dados local. - Usando uma conta de serviço e a especificação explícita de uma instância (recomendado para ambientes de produção):
./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:5432 \ -credential_file=<PATH_TO_KEY_FILE> &
Para mais informações sobre as opções de proxy, consulte Opções para autenticar o proxy e Opções para especificar instâncias.
- Usando autenticação do SDK do Cloud:
Soquetes Unix
- Se estiver usando a especificação explícita de instâncias, copie o nome de conexão da instância da página Detalhes da instância.
- Crie o diretório em que os soquetes do proxy ficarão:
sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
- Se você estiver usando uma conta de serviço para autenticar o proxy, anote o local em que a chave privada foi criada na máquina cliente durante a criação da conta de serviço.
- Abra uma nova janela de terminal e inicie o proxy.
Algumas strings possíveis de chamada do proxy:
- Usando uma conta de serviço e a especificação explícita de uma instância (recomendado para ambientes de produção):
./cloud_sql_proxy -dir=/cloudsql -instances=<INSTANCE_CONNECTION_NAME> \ -credential_file=<PATH_TO_KEY_FILE> &
- Usando a autenticação do SDK do Cloud e a descoberta automática de instâncias:
./cloud_sql_proxy -dir=/cloudsql &
É melhor iniciar o proxy em seu próprio terminal, assim você pode monitorar as respostas dele sem misturá-las com as respostas de outros programas.
Para mais informações sobre as opções de proxy, consulte Opções para autenticar o proxy e Opções para especificar instâncias.
- Usando uma conta de serviço e a especificação explícita de uma instância (recomendado para ambientes de produção):
Para usar o cliente de administração, instale uma cópia local e conecte-se usando o proxy ou os endereços IP.
Para mais informações, consulte Como conectar o cliente psql usando o Cloud SQL Proxy e Como conectar o cliente psql usando endereços IP.
Como configurar strings de conexão e adicionar uma biblioteca
Configure o ambiente local para que seja compatível com conexões de testes locais.
Por exemplo, na amostra de código abaixo:
export POSTGRES_CONNECTION="user=[USER_NAME] password=[PASSWORD] dbname=[DATABASE_NAME] sslmode=disable
Para permitir que o aplicativo se conecte à instância do Cloud SQL no momento da implantação, adicione as variáveis do Cloud SQL de usuário, senha, banco de dados e nome de conexão da instância às variáveis de ambiente relacionadas no arquivo
app.yaml
:Adicione a seção
beta_settings
aoapp.yaml
usando o nome de conexão da instância do Cloud SQL.Faça o download de um pacote do PostgreSQL na máquina local usando a linha de comando. Por exemplo:
go get -u github.com/lib/pq
Como executar o código de amostra
A amostra abaixo grava as informações de visita no Cloud SQL. Em seguida, ela as lê e retorna as últimas dez visitas:Como testar e implantar
Para testar seu aplicativo localmente:
go run cloudsql.go
Após os testes locais, implante seu aplicativo no App Engine:
gcloud app deploy
Para iniciar o navegador e ver o aplicativo em
http://[YOUR_PROJECT_ID].appspot.com
, execute o seguinte comando:gcloud app browse
Como executar o Cloud SQL e o App Engine em projetos separados
Use uma conta de serviço para permitir o acesso do aplicativo do App Engine ao Cloud SQL caso ele e a instância do Cloud SQL estejam em projetos diferentes do Google Cloud Platform.
Essa conta de serviço representa o aplicativo do App Engine. Ela é gerada por padrão quando você cria um projeto do Google Cloud Platform.
- Se o aplicativo do App Engine estiver no mesmo projeto que a instância do Cloud SQL, ignore esta seção e vá para Como configurar o ambiente local. Caso contrário, prossiga para a próxima etapa.
-
Identifique a conta de serviço associada ao aplicativo do App Engine. A conta padrão é denominada
[PROJECT-ID]@appspot.gserviceaccount.com
.É possível verificar a conta de serviço do App Engine na página Permissões de IAM. Lembre-se de selecionar o projeto do aplicativo do App Engine, e não a instância do Cloud SQL.
- Acesse a página Projetos do IAM e do administrador no Console do Google Cloud Platform.
- Selecione o projeto que contém a instância do Cloud SQL.
- Procure o nome da conta de serviço.
-
Se a conta de serviço já estiver incluída e tiver um papel que contenha a permissão
cloudsql.instances.connect
, vá até a seção Como configurar o ambiente local.Os papéis
Cloud SQL Client
,Cloud SQL Editor
eCloud SQL Admin
fornecem a permissão necessária, assim como os papéis legadosEditor
eOwner
do projeto. - Caso contrário, clique em Adicionar para incluir a conta.
Na caixa de diálogo Adicionar membros, insira o nome da conta de serviço e selecione um papel que inclua a permissão
cloudsql.instances.connect
. Qualquer papel predefinido do Cloud SQL é aceito, exceto o de Visualizador.Também é possível usar o papel primário de Editor ao selecionar Projeto > Editor. No entanto, ele inclui permissões em todo o Google Cloud Platform.
Se esses papéis não estiverem sendo exibidos, é provável que seu usuário do Google Cloud Platform não tenha a permissão
resourcemanager.projects.setIamPolicy
. Para verificar suas permissões, acesse a página IAM no Console do Google Cloud Platform e procure seu ID do usuário.- Clique em Adicionar.
Você verá a conta de serviço listada com o papel especificado.