Conectar-se pelo ambiente padrão do App Engine

Esta página contém informações e exemplos para se conectar a uma instância do Cloud SQL a partir de um serviço em execução no ambiente padrão do App Engine.

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 App Engine é uma plataforma sem servidor totalmente gerenciada para desenvolver e hospedar aplicativos da Web em escala. É possível escolher entre várias linguagens, frameworks e bibliotecas conhecidos para desenvolver seus apps e, em seguida, permitir que o App Engine provisione os servidores e escalone as instâncias de app com base na demanda.

Configurar uma instância do Cloud SQL

  1. Ative a API Cloud SQL Admin no projeto do Google Cloud do qual você está se conectando, caso ainda não tenha feito isso:

    Enable the API

  2. 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 ambiente padrão do App Engine

As etapas para configurar o ambiente padrão do App Engine dependem do tipo de endereço IP atribuído à instância do Cloud SQL.

IP público (padrão)

Para configurar o ambiente padrão do App Engine para ativar conexões com uma instância do Cloud SQL usando IP público:

  • Verifique se a instância criada acima 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. Isso 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 [INSTANCE_NAME].
  • Verifique se a conta de serviço usada pelo app para autenticar chamadas para o Cloud SQL tem o papel e as permissões apropriados do Cloud SQL.
    • A conta de serviço do seu serviço precisa de um dos seguintes papéis do IAM:
      • Cloud SQL Client (recomendável)
      • Cloud SQL Editor
      • Cloud SQL Admin
      Também é possível atribuir manualmente as seguintes permissões do IAM:
      • cloudsql.instances.connect
      • cloudsql.instances.get
      Para receber instruções detalhadas sobre como adicionar papéis do IAM a uma conta de serviço, consulte Como conceder papéis a contas de serviço.

    Por padrão, o app autoriza as conexões usando uma conta de serviço do App Engine. A identidade da conta de serviço está no formato PROJECT_ID@appspot.gserviceaccount.com.

    Se a conta de serviço de autorização pertencer a um projeto diferente da instância do Cloud SQL, as permissões da API Cloud SQL Admin e do IAM precisarão ser adicionadas aos dois projetos.

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.
Um conector de acesso VPC sem servidor usa endereços IP particulares para processar a comunicação com a rede VPC. Para se conectar diretamente com endereços IP particulares, faça isto:
  1. Verifique se a instância do Cloud SQL criada anteriormente tem um endereço IP particular. Se você precisar adicionar um, consulte Configurar IP particular para ver instruções.
  2. Crie um conector de acesso VPC sem servidor na mesma rede VPC da sua instância do Cloud SQL. Observe as seguintes condições:
    • A menos que você esteja usando a VPC compartilhada, é necessário que um conector esteja no mesmo projeto e na mesma região do recurso que o utiliza, mas ele pode enviar tráfego para recursos em regiões diferentes.
    • O acesso VPC sem servidor é compatível com a comunicação com redes VPC conectadas usando o Cloud VPN e o peering de rede VPC.
    • O acesso VPC sem servidor não é compatível com redes legadas.
  3. Configure o ambiente padrão do App Engine para usar o conector.
  4. Conecte-se usando o endereço IP particular e a porta 5432 da instância.

Conecte-se ao Cloud SQL

Depois de configurar o ambiente padrão do App Engine, conecte-se à instância do Cloud SQL.

IP público (padrão)

Para caminhos de IP público, o ambiente padrão do App Engine fornece criptografia e conexões usando o proxy de autenticação do Cloud SQL de duas maneiras:

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 conferir esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.

import os
import ssl

import sqlalchemy

def connect_tcp_socket() -> sqlalchemy.engine.base.Engine:
    """Initializes a TCP connection pool for a Cloud SQL instance of Postgres."""
    # Note: Saving credentials in environment variables is convenient, but not
    # secure - consider a more secure solution such as
    # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
    # keep secrets safe.
    db_host = os.environ[
        "INSTANCE_HOST"
    ]  # e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
    db_user = os.environ["DB_USER"]  # e.g. 'my-db-user'
    db_pass = os.environ["DB_PASS"]  # e.g. 'my-db-password'
    db_name = os.environ["DB_NAME"]  # e.g. 'my-database'
    db_port = os.environ["DB_PORT"]  # e.g. 5432

    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # postgresql+pg8000://<db_user>:<db_pass>@<db_host>:<db_port>/<db_name>
        sqlalchemy.engine.url.URL.create(
            drivername="postgresql+pg8000",
            username=db_user,
            password=db_pass,
            host=db_host,
            port=db_port,
            database=db_name,
        ),
        # ...
    )
    return pool

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. 


import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;

public class TcpConnectionPoolFactory extends ConnectionPoolFactory {

  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  private static final String DB_USER = System.getenv("DB_USER");
  private static final String DB_PASS = System.getenv("DB_PASS");
  private static final String DB_NAME = System.getenv("DB_NAME");

  private static final String INSTANCE_HOST = System.getenv("INSTANCE_HOST");
  private static final String DB_PORT = System.getenv("DB_PORT");

  public static DataSource createConnectionPool() {
    // The configuration object specifies behaviors for the connection pool.
    HikariConfig config = new HikariConfig();

    // The following URL is equivalent to setting the config options below:
    // jdbc:postgresql://<INSTANCE_HOST>:<DB_PORT>/<DB_NAME>?user=<DB_USER>&password=<DB_PASS>
    // See the link below for more info on building a JDBC URL for the Cloud SQL JDBC Socket Factory
    // https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory#creating-the-jdbc-url

    // Configure which instance and what database user to connect with.
    config.setJdbcUrl(String.format("jdbc:postgresql://%s:%s/%s", INSTANCE_HOST, DB_PORT, DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", "postgres"
    config.setPassword(DB_PASS); // e.g. "my-password"

    // ... Specify additional connection properties here.
    // ...

    // Initialize the connection pool using the configuration object.
    return new HikariDataSource(config);
  }
}

Node.js

Para conferir esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.

const Knex = require('knex');
const fs = require('fs');

// createTcpPool initializes a TCP connection pool for a Cloud SQL
// instance of Postgres.
const createTcpPool = async config => {
  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  const dbConfig = {
    client: 'pg',
    connection: {
      host: process.env.INSTANCE_HOST, // e.g. '127.0.0.1'
      port: process.env.DB_PORT, // e.g. '5432'
      user: process.env.DB_USER, // e.g. 'my-user'
      password: process.env.DB_PASS, // e.g. 'my-user-password'
      database: process.env.DB_NAME, // e.g. 'my-database'
    },
    // ... Specify additional properties here.
    ...config,
  };
  // Establish a connection to the database.
  return Knex(dbConfig);
};

Go

Para conferir esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.

package cloudsql

import (
	"database/sql"
	"fmt"
	"log"
	"os"

	// Note: If connecting using the App Engine Flex Go runtime, use
	// "github.com/jackc/pgx/stdlib" instead, since v5 requires
	// Go modules which are not supported by App Engine Flex.
	_ "github.com/jackc/pgx/v5/stdlib"
)

// connectTCPSocket initializes a TCP connection pool for a Cloud SQL
// instance of Postgres.
func connectTCPSocket() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Fatal Error in connect_tcp.go: %s environment variable not set.", k)
		}
		return v
	}
	// Note: Saving credentials in environment variables is convenient, but not
	// secure - consider a more secure solution such as
	// Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
	// keep secrets safe.
	var (
		dbUser    = mustGetenv("DB_USER")       // e.g. 'my-db-user'
		dbPwd     = mustGetenv("DB_PASS")       // e.g. 'my-db-password'
		dbTCPHost = mustGetenv("INSTANCE_HOST") // e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
		dbPort    = mustGetenv("DB_PORT")       // e.g. '5432'
		dbName    = mustGetenv("DB_NAME")       // e.g. 'my-database'
	)

	dbURI := fmt.Sprintf("host=%s user=%s password=%s port=%s database=%s",
		dbTCPHost, dbUser, dbPwd, dbPort, dbName)

	// dbPool is the pool of database connections.
	dbPool, err := sql.Open("pgx", dbURI)
	if err != nil {
		return nil, fmt.Errorf("sql.Open: %w", err)
	}

	// ...

	return dbPool, nil
}

C#

Para conferir esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.

using Npgsql;
using System;

namespace CloudSql
{
    public class PostgreSqlTcp
    {
        public static NpgsqlConnectionStringBuilder NewPostgreSqlTCPConnectionString()
        {
            // Equivalent connection string:
            // "Uid=<DB_USER>;Pwd=<DB_PASS>;Host=<INSTANCE_HOST>;Database=<DB_NAME>;"
            var connectionString = new NpgsqlConnectionStringBuilder()
            {
                // Note: Saving credentials in environment variables is convenient, but not
                // secure - consider a more secure solution such as
                // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
                // keep secrets safe.
                Host = Environment.GetEnvironmentVariable("INSTANCE_HOST"),     // e.g. '127.0.0.1'
                // Set Host to 'cloudsql' when deploying to App Engine Flexible environment
                Username = Environment.GetEnvironmentVariable("DB_USER"), // e.g. 'my-db-user'
                Password = Environment.GetEnvironmentVariable("DB_PASS"), // e.g. 'my-db-password'
                Database = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'

                // The Cloud SQL proxy provides encryption between the proxy and instance.
                SslMode = SslMode.Disable,
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;
        }
    }
}

Ruby

Para conferir esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.

tcp: &tcp
  adapter: postgresql
  # Configure additional properties here.
  # Note: Saving credentials in environment variables is convenient, but not
  # secure - consider a more secure solution such as
  # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  # keep secrets safe.
  username: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_development" } %>
  host: <%= ENV.fetch("INSTANCE_HOST") { "127.0.0.1" }%> # '172.17.0.1' if deployed to GAE Flex
  port: <%= ENV.fetch("DB_PORT") { 5432 }%>

PHP

Para conferir esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.

namespace Google\Cloud\Samples\CloudSQL\Postgres;

use PDO;
use PDOException;
use RuntimeException;
use TypeError;

class DatabaseTcp
{
    public static function initTcpDatabaseConnection(): PDO
    {
        try {
            // Note: Saving credentials in environment variables is convenient, but not
            // secure - consider a more secure solution such as
            // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
            // keep secrets safe.
            $username = getenv('DB_USER'); // e.g. 'your_db_user'
            $password = getenv('DB_PASS'); // e.g. 'your_db_password'
            $dbName = getenv('DB_NAME'); // e.g. 'your_db_name'
            $instanceHost = getenv('INSTANCE_HOST'); // e.g. '127.0.0.1' ('172.17.0.1' for GAE Flex)

            // Connect using TCP
            $dsn = sprintf('pgsql:dbname=%s;host=%s', $dbName, $instanceHost);

            // Connect to the database
            $conn = new PDO(
                $dsn,
                $username,
                $password,
                # ...
            );
        } catch (TypeError $e) {
            throw new RuntimeException(
                sprintf(
                    'Invalid or missing configuration! Make sure you have set ' .
                        '$username, $password, $dbName, and $instanceHost (for TCP mode). ' .
                        'The PHP error was %s',
                    $e->getMessage()
                ),
                $e->getCode(),
                $e
            );
        } catch (PDOException $e) {
            throw new RuntimeException(
                sprintf(
                    'Could not connect to the Cloud SQL Database. Check that ' .
                        'your username and password are correct, that the Cloud SQL ' .
                        'proxy is running, and that the database exists and is ready ' .
                        'for use. For more assistance, refer to %s. The PDO error was %s',
                    'https://cloud.google.com/sql/docs/postgres/connect-external-app',
                    $e->getMessage()
                ),
                $e->getCode(),
                $e
            );
        }

        return $conn;
    }
}

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.

Pools de conexões

As conexões aos bancos de dados subjacentes podem ser descartadas pelo próprio servidor de banco de dados ou pela infraestrutura subjacente. Para atenuar isso, recomendamos que você use uma biblioteca de cliente que ofereça suporte a pools de conexão e à reconexão automática.

Limites de conexão

Cada instância do App Engine executada em um ambiente padrão não pode ter mais de 100 conexões simultâneas com uma instância. Nos apps em PHP 5.5, o limite é de 60 conexões simultâneas. Esse limite é aplicado por instância do aplicativo. Isso significa que cada instância do aplicativo do App Engine pode ter muitas conexões com o banco de dados e, à medida que ela cresce, o número total de conexões por implantação pode aumentar. Para mais informações, consulte os Elementos de escalonamento.

É possível limitar 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.

Os aplicativos do App Engine estão sujeitos a limites de tempo de solicitação, dependendo do uso e do ambiente. Para mais informações, veja como as instâncias são gerenciadas nos ambientes padrão e flexível do App Engine.

Limites de cota da API

O App Engine fornece um mecanismo que se conecta usando o proxy do Cloud SQL Auth, que usa a API Cloud SQL Admin. Os limites de cota da API se aplicam ao proxy do Cloud SQL Auth. Quando a API Cloud SQL Admin é iniciada, ela usa uma cota de dois e, depois, uma média de duas por hora. A cota padrão é de 180 por minuto por usuário. Os aplicativos do App Engine também estão sujeitos a outras cotas e limites, conforme descrito na página Cotas do App Engine.