Como usar o Cloud SQL para PostgreSQL

Python |Java |Node.js |Go |Ruby |PHP |.NET

Nesta página, mostramos como se conectar a uma instância do Cloud SQL para PostgreSQL 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 Engine
O Painel será aberto se houver um aplicativo do App Engine no projeto e o faturamento estiver ativado. Caso contrário, siga as instruções para escolher uma região e ativar o faturamento.
{% dynamic endif %}{% dynamic if setvar.api_list %}{% dynamic if setvar.in_henhouse_no_auth_whitelist or setvar.in_henhouse_service_account_whitelist %} Configure um projeto do Console do GCP.
Configurar um projeto
Clique para:
- criar ou selecionar um projeto;
- ativar {% dynamic if setvar.api_names %}{% dynamic print setvar.api_names %}{% dynamic else %}obrigatória{% dynamic endif %}{% dynamic if "," in setvar.api_list %} APIs{% dynamic elif "API" in setvar.api_names %}{% dynamic else %} API{% dynamic endif %} para o projeto;
- criar uma conta de serviço;
- fazer o download de uma chave privada como JSON.
É possível ver e gerenciar esses recursos a qualquer momento no Console do GCP.
{% dynamic else %}{% dynamic if "no_text" not in setvar.task_params %} Ativar {% dynamic if setvar.api_names %}{% dynamic print setvar.api_names %}{% dynamic else %}obrigatória{% dynamic endif %}{% dynamic if "," in setvar.api_list %} APIs{% dynamic elif "API" in setvar.api_names %}{% dynamic else %} API{% dynamic endif %}. {% dynamic endif %}
Ativar {% dynamic if "," in setvar.api_list %} as APIs{% dynamic else %} a API{% dynamic endif %}
{% dynamic endif %}{% dynamic endif %}{% dynamic if "no_steps" not in setvar.task_params %}

Para implantar o aplicativo com a ferramenta gcloud, você precisa fazer o download, instalar e inicializar o Cloud SDK:
Fazer o download do SDK
Se você já tiver a ferramenta gcloud instalada e quiser configurá-la para usar um código do projeto do GCP diferente do inicializado, consulte Como gerenciar configurações do Cloud SDK.

Como configurar a instância do Cloud SQL

Para criar e configurar uma instância do Cloud SQL, siga estes passos:

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]

Para se conectar com um usuário diferente do padrão, crie-o.
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, o 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 localmente, é 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 para o banco de dados ou o console do GCP.

Autentique a ferramenta gcloud para usar o proxy a fim de se conectar da sua máquina local:
```
gcloud auth application-default login
```
Instale o Cloud SQL Proxy:
Linux de 64 bits
1. Faça o download do proxy:
```
wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
```
2. Torne o proxy executável:
```
chmod +x cloud_sql_proxy
```
Linux de 32 bits
1. Faça o download do proxy:
```
wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
```
2. Torne o proxy executável:
```
chmod +x cloud_sql_proxy
```
macOS de 64 bits
1. Faça o download do proxy:
```
curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64
```
2. Torne o proxy executável:
```
chmod +x cloud_sql_proxy
```
macOS de 32 bits
1. Faça o download do proxy:
```
curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
```
2. Torne o proxy executável:
```
chmod +x cloud_sql_proxy
```
Windows de 64 bits
Clique com o botão direito do mouse em https://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe e selecione "Salvar link como..." para fazer o download do proxy, renomeando-o como cloud_sql_proxy.exe.

Windows de 32 bits
Clique com o botão direito do mouse em https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe e selecione "Salvar link como…" para fazer o download do proxy, renomeando-o como cloud_sql_proxy.exe.
Caso seu sistema operacional não esteja incluído aqui, compile o proxy com base na origem.
Execute o proxy:

Dependendo da linguagem e do ambiente, inicie o proxy usando os soquetes TCP ou Unix.
Soquetes TCP
1. Copie o nome de conexão da instância na página Detalhes da instância.
2. 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.
3. Inicie o proxy.
  Algumas strings possíveis de chamada do proxy:
  - Usando autenticação do Cloud SDK:
    ./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.
Soquetes Unix
1. 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.
2. Crie o diretório em que os soquetes do proxy ficarão:
```
sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
```
3. 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.
4. 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 Cloud SDK 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 a saída dele sem misturá-la com a saída 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.
Para usar o cliente de administração, instale uma cópia local e conecte-se usando o proxy ou 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 definir strings de conexão e adicionar uma biblioteca

Configure o ambiente local para oferecer suporte a 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 quando ele é implantado, adicione as variáveis de usuário, senha, banco de dados e nome de conexão da instância do Cloud SQL às variáveis de ambiente relacionadas no arquivo app.yaml:

appengine_flexible/cloudsql_postgres/app.yaml

Ver no GitHub

env_variables:
  # See https://godoc.org/github.com/lib/pq
  #
  # Replace INSTANCE_CONNECTION_NAME with the same value as in the
  # beta_settings section below.
  POSTGRES_CONNECTION: "user=postgres password=pw dbname=db host=/cloudsql/INSTANCE_CONNECTION_NAME"
  #
  # If you're testing locally using the Cloud SQL proxy with TCP,
  # instead set this environment variable:
  # POSTGRES_CONNECTION="user=postgres password=pw dbname=db sslmode=disable"

Adicione a seção beta_settings ao app.yaml usando o nome de conexão da instância do Cloud SQL.

appengine_flexible/cloudsql_postgres/app.yaml

Ver no GitHub
```
beta_settings:
  cloud_sql_instances: INSTANCE_CONNECTION_NAME
```
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 seguinte amostra grava informações de visita no Cloud SQL. Depois, ela lê e retorna as últimas dez visitas:

appengine_flexible/cloudsql_postgres/cloudsql.go

Ver no GitHub

// Copyright 2015 Google Inc. All rights reserved.
// Use of this source code is governed by the Apache 2.0
// license that can be found in the LICENSE file.

// +build go1.8

// Sample cloudsql demonstrates usage of Cloud SQL from App Engine flexible environment.
package main

import (
	"database/sql"
	"fmt"
	"log"
	"net/http"
	"os"
	"time"

	"google.golang.org/appengine"

	_ "github.com/lib/pq"
)

var db *sql.DB

func main() {
	// Set this in app.yaml when running in production.
	datastoreName := os.Getenv("POSTGRES_CONNECTION")

	var err error
	db, err = sql.Open("postgres", datastoreName)
	if err != nil {
		log.Fatal(err)
	}

	// Ensure the table exists.
	// Running an SQL query also checks the connection to the PostgreSQL server
	// is authenticated and valid.
	if err := createTable(); err != nil {
		log.Fatal(err)
	}

	http.HandleFunc("/", handle)
	appengine.Main()
}

func createTable() error {
	stmt := `CREATE TABLE IF NOT EXISTS visits (
			timestamp  BIGINT,
			userip     VARCHAR(255)
		)`
	_, err := db.Exec(stmt)
	return err
}

func handle(w http.ResponseWriter, r *http.Request) {
	if r.URL.Path != "/" {
		http.NotFound(w, r)
		return
	}

	// Get a list of the most recent visits.
	visits, err := queryVisits(10)
	if err != nil {
		msg := fmt.Sprintf("Could not get recent visits: %v", err)
		http.Error(w, msg, http.StatusInternalServerError)
		return
	}

	// Record this visit.
	if err := recordVisit(time.Now().UnixNano(), r.RemoteAddr); err != nil {
		msg := fmt.Sprintf("Could not save visit: %v", err)
		http.Error(w, msg, http.StatusInternalServerError)
		return
	}

	fmt.Fprintln(w, "Previous visits:")
	for _, v := range visits {
		fmt.Fprintf(w, "[%s] %s\n", time.Unix(0, v.timestamp), v.userIP)
	}
	fmt.Fprintln(w, "\nSuccessfully stored an entry of the current request.")
}

type visit struct {
	timestamp int64
	userIP    string
}

func recordVisit(timestamp int64, userIP string) error {
	stmt := "INSERT INTO visits (timestamp, userip) VALUES ($1, $2)"
	_, err := db.Exec(stmt, timestamp, userIP)
	return err
}

func queryVisits(limit int64) ([]visit, error) {
	rows, err := db.Query("SELECT timestamp, userip FROM visits ORDER BY timestamp DESC LIMIT $1", limit)
	if err != nil {
		return nil, fmt.Errorf("Could not get recent visits: %v", err)
	}
	defer rows.Close()

	var visits []visit
	for rows.Next() {
		var v visit
		if err := rows.Scan(&v.timestamp, &v.userIP); err != nil {
			return nil, fmt.Errorf("Could not get timestamp/user IP out of row: %v", err)
		}
		visits = append(visits, v)
	}

	return visits, rows.Err()
}

Como testar e implantar

Para testar o aplicativo no local:
```
go run cloudsql.go
```
Após os testes locais, implante o 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 esse aplicativo 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.

Acessar a página "Permissões de IAM"
Acesse a página Projetos do IAM e do administrador no Console do Google Cloud Platform.
Acessar a página "Projetos do IAM e do administrador"
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á existir e tiver um papel que inclua a permissão cloudsql.instances.connect, prossiga para Como configurar o ambiente local.

Os papéis Cloud SQL Client, Cloud SQL Editor e Cloud SQL Admin concedem a permissão necessária, assim como os papéis legados Editor e Owner 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 funcionará, exceto Leitor.

Também é possível usar o papel primitivo de editor ao selecionar Projeto > Editor. No entanto, ele inclui permissões no 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 de IAM no Console do Google Cloud Platform e procure sua ID de usuário.
Clique em Adicionar.
Você verá a conta de serviço listada com o papel especificado.

Antes de começar

Como configurar a instância do Cloud SQL

Como configurar o ambiente local

Linux de 64 bits

Linux de 32 bits

macOS de 64 bits

macOS de 32 bits

Windows de 64 bits

Windows de 32 bits

Soquetes TCP

Soquetes Unix

Como definir strings de conexão e adicionar uma biblioteca

Como executar o código de amostra

Como testar e implantar

Como executar o Cloud SQL e o App Engine em projetos separados

Enviar comentários sobre…