Conectar usando conectores do Cloud SQL

Os conectores do Cloud SQL são bibliotecas que fornecem autorização com base em IAM e criptografia ao se conectar a uma instância do Cloud SQL. Não é possível fornecer um caminho de rede para uma instância do Cloud SQL caso ainda não exista uma.

Outras maneiras de se conectar a uma instância do Cloud SQL são usando um cliente de banco de dados ou o proxy do Cloud SQL Auth. Consulte a Visão geral da conexão para mais informações sobre como se conectar a uma instância do Cloud SQL.

Nesta página, você conhecerá os seguintes conectores do Cloud SQL:

Antes de começar

  • Ative a API Cloud SQL Admin.

    Ative a API

  • Crie uma instância do Cloud SQL, incluindo a configuração do usuário padrão.

    Para mais informações sobre como criar instâncias, consulte Como criar instâncias.

    Para mais informações sobre como configurar o usuário padrão, consulte Como configurar a conta de usuário padrão.

  • Configurou os papéis e permissões necessários para se conectar a uma instância do Cloud SQL.

Configuração

Java

O conector Java do Cloud SQL é uma biblioteca que fornece autorização e criptografia baseadas em IAM ao se conectar a uma instância do Cloud SQL. Ela não pode fornecer um caminho de rede para uma instância do Cloud SQL se ainda não houver um.

Instalação

Para instruções sobre como criar e usar os drivers para JDBC e R2DBC com o conector Java do Cloud SQL, consulte os seguintes links:

JDBC: como se conectar ao Postgres usando JDBC.

R2DBC: como se conectar ao Postgres usando o R2DBC.

Para exemplos dessa biblioteca que está sendo usada no contexto de um aplicativo, confira estes aplicativos de amostra.

Autenticação

Essa biblioteca usa o Application Default Credentials para autenticar a conexão com o servidor do Cloud SQL.

Para ativar as credenciais localmente, use o seguinte comando do gcloud:

    gcloud auth application-default login

Conectar-se com o IntelliJ

Para conectar o IntelliJ à instância do Cloud SQL, você precisará adicionar a biblioteca como um jar com dependências na seção Outros arquivos da página de configurações do driver. Por exemplo, fat jars pré-criados podem ser encontrados na página Versões do conector Java do Cloud SQL para essa finalidade.

Python

O conector do Cloud SQL para Python é uma biblioteca que pode ser usada com um driver de banco de dados para permitir que usuários com permissões suficientes se conectem a um banco de dados do Cloud SQL sem precisar incluir IPs manualmente ou gerenciar certificados SSL.

Para ver exemplos interativos do uso do conector Python do Cloud SQL, abra o notebook do conector Python do Cloud SQL.

O driver compatível atualmente com o PostgreSQL é pg8000.

Instalação

Para instalar a versão mais recente, siga estas instruções.

Authentication

Essa biblioteca usa o Application Default Credentials para autenticar a conexão com o servidor do Cloud SQL.

Para ativar as credenciais localmente, use o seguinte comando do gcloud:

    gcloud auth application-default login

Uso

Java

Para ver esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub (em inglês).

cloud-sql/postgres/servlet/src/main/java/com/example/cloudsql/ConnectorConnectionPoolFactory.java 
import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;

public class ConnectorConnectionPoolFactory 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 INSTANCE_CONNECTION_NAME =
      System.getenv("INSTANCE_CONNECTION_NAME");
  private static final String INSTANCE_UNIX_SOCKET = System.getenv("INSTANCE_UNIX_SOCKET");
  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");

  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:///<DB_NAME>?cloudSqlInstance=<INSTANCE_CONNECTION_NAME>&
    // socketFactory=com.google.cloud.sql.postgres.SocketFactory&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", DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", _postgres"
    config.setPassword(DB_PASS); // e.g. "my-password"

    config.addDataSourceProperty("socketFactory", "com.google.cloud.sql_postgres.SocketFactory");
    config.addDataSourceProperty("cloudSqlInstance", INSTANCE_CONNECTION_NAME);

    // The ipTypes argument can be used to specify a comma delimited list of preferred IP types
    // for connecting to a Cloud SQL instance. The argument ipTypes=PRIVATE will force the
    // SocketFactory to connect with an instance's associated private IP.
    config.addDataSourceProperty("ipTypes", "PUBLIC,PRIVATE");

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

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

Python

Consulte Como usar o conector para instruções detalhadas sobre como usar a biblioteca. Veja um exemplo de código de teste de conexão no GitHub.

tests/system/test_pg8000_connection.py 
import pg8000
import sqlalchemy
from google.cloud.sql.connector import Connector

# The Cloud SQL Python Connector can be used along with SQLAlchemy using the
# 'creator' argument to 'create_engine'
def init_connection_engine() -> sqlalchemy.engine.Engine:
    def getconn() -> pg8000.dbapi.Connection:
        # initialize Connector object for connections to Cloud SQL
        with Connector() as connector:
            conn: pg8000.dbapi.Connection = connector.connect(
                os.environ["POSTGRES_CONNECTION_NAME"],
                "pg8000",
                user=os.environ["POSTGRES_USER"],
                password=os.environ["POSTGRES_PASS"],
                db=os.environ["POSTGRES_DB"],
            )
            return conn

    # create SQLAlchemy connection pool
    pool = sqlalchemy.create_engine(
        "postgresql+pg8000://",
        creator=getconn,
    )
    pool.dialect.description_encoding = None
    return pool

Resolver problemas

Versões do driver

Verifique se você está usando a versão mais recente dos conectores do Cloud SQL e do driver do banco de dados para evitar incompatibilidades. Algumas versões mais antigas dos drivers não são compatíveis

Caminhos de conexão

Os conectores do Cloud SQL fornecem autorização para conexões, mas não fornecem novos caminhos para a conectividade. Por exemplo, para se conectar a uma instância do Cloud SQL usando um endereço IP privado, o aplicativo já precisa ter acesso à VPC. Para se conectar a uma instância do Cloud SQL usando um endereço IP público, seu aplicativo precisa estar em uma rede autorizada.

Depurar problemas de conexão

Se precisar de mais ajuda com problemas de conexão, consulte as páginas Solução de problemas e Como depurar problemas de conexão.

A seguir