Conectar usando os conectores do Cloud SQL Language

Os conectores do Cloud SQL são bibliotecas que fornecem criptografia e autorização com base em Identity and Access Management (IAM) 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 incluem o uso de um cliente de banco de dados ou o proxy do Cloud SQL Auth. Consulte a página Sobre opções de 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:

  • O conector Java do Cloud SQL
  • O conector Python do Cloud SQL (aberto no Colab)
  • Conector do Cloud SQL para Go
  • Conector do Cloud SQL para Node.js

Benefícios

O uso de um conector do Cloud SQL oferece os seguintes benefícios:

  • Autorização do IAM: usa permissões de IAM para controlar quem ou o que pode se conectar às instâncias do Cloud SQL.
  • Conveniência: remove o requisito para gerenciar certificados SSL, configurar regras de firewall ou ativar redes autorizadas.

Antes de começar

  • Ative a API Cloud SQL Admin.

    Enable the 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 Criar instâncias.

    Para mais informações sobre como configurar o usuário padrão, consulte Definir a senha da 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.

Instalar

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:

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

Autenticar

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 com o SQL Server é pytds.

Instalar

Para instalar a versão mais recente do conector do Python para Cloud SQL, use o comando pip install e especifique o driver pytds para seu banco de dados:

    pip install "cloud-sql-python-connector[pytds]"

Autenticar

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

Go

O conector do Cloud SQL para Go é projetado para uso com essa linguagem. Para melhorar a segurança, esse conector usa criptografia TLS 1.3 robusta e autenticada manualmente entre o conector do cliente e o proxy do lado do servidor, independentemente do protocolo do banco de dados.

Instalar

É possível instalar este repositório com go get:

    go get cloud.google.com/go/cloudsqlconn

Node.js

O conector para Node.js é uma biblioteca projetada para uso com o ambiente de execução Node.js, que permite a conexão segura com sua instância do Cloud SQL.

Instalar

É possível instalar a biblioteca com npm install:

    npm install @google-cloud/cloud-sql-connector

Usar

Java

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


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 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 is equivalent to setting the config options below:
    // jdbc:sqlserver://;user=<DB_USER>;password=<DB_PASS>;databaseName=<DB_NAME>;
    // socketFactoryClass=com.google.cloud.sql.sqlserver.SocketFactory;
    // socketFactoryConstructorArg=<INSTANCE_CONNECTION_NAME>

    // 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
        .setDataSourceClassName("com.microsoft.sqlserver.jdbc.SQLServerDataSource");
    config.setUsername(DB_USER); // e.g. "root", "sqlserver"
    config.setPassword(DB_PASS); // e.g. "my-password"
    config.addDataSourceProperty("databaseName", DB_NAME);

    config.addDataSourceProperty("socketFactoryClass",
        "com.google.cloud.sql.sqlserver.SocketFactory");
    config.addDataSourceProperty("socketFactoryConstructorArg", INSTANCE_CONNECTION_NAME);

    // The Java Connector provides SSL encryption, so it should be disabled
    // at the driver level.
    config.addDataSourceProperty("encrypt", "false");

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

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

Python

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

import os

from google.cloud.sql.connector import Connector, IPTypes
import pytds

import sqlalchemy


def connect_with_connector() -> sqlalchemy.engine.base.Engine:
    """
    Initializes a connection pool for a Cloud SQL instance of SQL Server.

    Uses the Cloud SQL Python Connector package.
    """
    # 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.

    instance_connection_name = os.environ[
        "INSTANCE_CONNECTION_NAME"
    ]  # e.g. 'project:region:instance'
    db_user = os.environ.get("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'

    ip_type = IPTypes.PRIVATE if os.environ.get("PRIVATE_IP") else IPTypes.PUBLIC

    connector = Connector(ip_type)

    connect_args = {}
    # If your SQL Server instance requires SSL, you need to download the CA
    # certificate for your instance and include cafile={path to downloaded
    # certificate} and validate_host=False. This is a workaround for a known issue.
    if os.environ.get("DB_ROOT_CERT"):  # e.g. '/path/to/my/server-ca.pem'
        connect_args = {
            "cafile": os.environ["DB_ROOT_CERT"],
            "validate_host": False,
        }

    def getconn() -> pytds.Connection:
        conn = connector.connect(
            instance_connection_name,
            "pytds",
            user=db_user,
            password=db_pass,
            db=db_name,
            **connect_args
        )
        return conn

    pool = sqlalchemy.create_engine(
        "mssql+pytds://",
        creator=getconn,
        # ...
    )
    return pool

Go

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

package cloudsql

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

	"cloud.google.com/go/cloudsqlconn"
	mssql "github.com/denisenkom/go-mssqldb"
)

type csqlDialer struct {
	dialer     *cloudsqlconn.Dialer
	connName   string
	usePrivate bool
}

// DialContext adheres to the mssql.Dialer interface.
func (c *csqlDialer) DialContext(ctx context.Context, network, addr string) (net.Conn, error) {
	var opts []cloudsqlconn.DialOption
	if c.usePrivate {
		opts = append(opts, cloudsqlconn.WithPrivateIP())
	}
	return c.dialer.Dial(ctx, c.connName, opts...)
}

func connectWithConnector() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Fatal Error in connect_connector.go: %s environment variable not set.\n", 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'
		dbName                 = mustGetenv("DB_NAME")                  // e.g. 'my-database'
		instanceConnectionName = mustGetenv("INSTANCE_CONNECTION_NAME") // e.g. 'project:region:instance'
		usePrivate             = os.Getenv("PRIVATE_IP")
	)

	dbURI := fmt.Sprintf("user id=%s;password=%s;database=%s;", dbUser, dbPwd, dbName)
	c, err := mssql.NewConnector(dbURI)
	if err != nil {
		return nil, fmt.Errorf("mssql.NewConnector: %w", err)
	}
	dialer, err := cloudsqlconn.NewDialer(context.Background())
	if err != nil {
		return nil, fmt.Errorf("cloudsqlconn.NewDailer: %w", err)
	}
	c.Dialer = &csqlDialer{
		dialer:     dialer,
		connName:   instanceConnectionName,
		usePrivate: usePrivate != "",
	}

	dbPool := sql.OpenDB(c)
	if err != nil {
		return nil, fmt.Errorf("sql.Open: %w", err)
	}
	return dbPool, nil
}

Node.js

Para instruções detalhadas sobre como usar a biblioteca, consulte Uso.

const {Connection} = require('tedious');
const {Connector} = require('@google-cloud/cloud-sql-connector');

// In case the PRIVATE_IP environment variable is defined then we set
// the ipType=PRIVATE for the new connector instance, otherwise defaults
// to public ip type.
const getIpType = () =>
  process.env.PRIVATE_IP === '1' || process.env.PRIVATE_IP === 'true'
    ? 'PRIVATE'
    : 'PUBLIC';

// connectWithConnector initializes a TCP connection
// to a Cloud SQL instance of SQL Server.
const connectWithConnector = 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 connector = new Connector();
  const clientOpts = await connector.getTediousOptions({
    instanceConnectionName: process.env.INSTANCE_CONNECTION_NAME,
    ipType: getIpType(),
  });
  const dbConfig = {
    // Please note that the `server` property here is not used and is only
    // defined due to a bug in the tedious driver
    // (ref: https://github.com/tediousjs/tedious/issues/1541)
    // With that in mind, do not try to change this value since it will have no
    // impact in how the connector works, this sample will be updated to remove
    // this property declaration as soon as the tedious driver bug is fixed
    server: '0.0.0.0', // e.g. '127.0.0.1'
    authentication: {
      type: 'default',
      options: {
        userName: process.env.DB_USER, // e.g. 'my-db-user'
        password: process.env.DB_PASS, // e.g. 'my-db-password'
      },
    },
    options: {
      ...clientOpts,
      // Please note that the `port` property here is not used and is only
      // defined due to a bug in the tedious driver
      // (ref: https://github.com/tediousjs/tedious/issues/1541)
      // With that in mind, do not try to change this value since it will have
      // no impact in how the connector works, this sample will be updated to
      // remove this property declaration as soon as the tedious driver bug is
      // fixed
      port: 9999,
      database: process.env.DB_NAME, // e.g. 'my-database'
      useColumnNames: true,
    },
    // ... Specify additional properties here.
    ...config,
  };

  // Establish a connection to the database.
  return new Connection(dbConfig);
};

Aplicar

Com a aplicação de conectores, é possível usar apenas o proxy de autenticação do Cloud SQL ou os conectores de linguagem do Cloud SQL para se conectar a instâncias do Cloud SQL. Com a aplicação do conector, o Cloud SQL rejeita conexões diretas ao banco de dados.

Se você estiver usando uma instância com o Private Service Connect ativado, haverá uma limitação. Se a instância tiver a aplicação de conector ativada, não será possível criar réplicas de leitura para ela. Da mesma forma, se a instância tiver réplicas de leitura, não será possível ativar a aplicação do conector nela.

gcloud

Para forçar o uso apenas do proxy de autenticação do Cloud SQL ou dos conectores de linguagem do Cloud SQL para se conectar a uma instância, use o comando gcloud sql instances patch:

gcloud sql instances patch INSTANCE_NAME \
--connector-enforcement=REQUIRED

Substitua INSTANCE_NAME pelo nome da instância do Cloud SQL.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID ou número do projeto do Google Cloud que contém a instância
  • INSTANCE_NAME: o nome da sua instância do Cloud SQL

Método HTTP e URL: 

PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

Corpo JSON da solicitação:

{
  "kind": "sql#instance",
  "name": INSTANCE_NAME,
  "project": PROJECT_ID,
  "settings": {
  "connectorEnforcement": "REQUIRED",
  "kind": "sql#settings"
  }
}

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

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.

Depurar problemas de conexão

Para receber mais ajuda com problemas de conexão, consulte as páginas Resolver problemas e Depurar problemas de conexão.

A seguir