Conectarse mediante conectores de lenguaje de Cloud SQL

Los conectores de Cloud SQL son bibliotecas que proporcionan cifrado y autorización basada en la gestión de identidades y accesos (IAM) al conectarse a una instancia de Cloud SQL. No pueden proporcionar una ruta de red a una instancia de Cloud SQL si no existe una.

Otras formas de conectarse a una instancia de Cloud SQL incluyen usar un cliente de base de datos o el proxy de autenticación de Cloud SQL . Consulta la página "Acerca de las opciones de conexión" para obtener más información sobre cómo conectarte a una instancia de Cloud SQL.

En esta página se analizan los siguientes conectores de Cloud SQL:

  • El conector Java de Cloud SQL
  • El conector Python de Cloud SQL (abierto en Colab)
  • El conector Go de Cloud SQL
  • El conector Node.js de Cloud SQL

Beneficios

El uso de un conector de Cloud SQL proporciona los siguientes beneficios:

  • Autorización de IAM: utiliza permisos de IAM para controlar quién o qué puede conectarse a sus instancias de Cloud SQL.
  • Conveniencia: elimina el requisito de administrar certificados SSL, configurar reglas de firewall o habilitar redes autorizadas.
  • Autenticación de base de datos IAM : proporciona soporte para la función de autenticación automática de base de datos IAM de Cloud SQL .

Antes de empezar

  • Habilitar la API de administración de Cloud SQL.

    Enable the API

  • Cree una instancia de Cloud SQL, incluida la configuración del usuario predeterminado.

    Para obtener más información sobre la creación de instancias, consulte Crear instancias .

    Para obtener más información sobre cómo configurar el usuario predeterminado, consulte Establecer la contraseña para la cuenta de usuario predeterminada .

  • Configure los roles y permisos necesarios para conectarse a una instancia de Cloud SQL.

Configuración

Java

El Conector Java de Cloud SQL es una biblioteca que proporciona autorización y cifrado basados ​​en IAM al conectarse a una instancia de Cloud SQL. No puede proporcionar una ruta de red a una instancia de Cloud SQL si no existe una.

Instalar

Para obtener instrucciones sobre cómo crear y utilizar los controladores para JDBC y R2DBC con el conector Java de Cloud SQL, consulte los siguientes enlaces:

Para ver ejemplos del uso de esta biblioteca en el contexto de una aplicación, consulte estas aplicaciones de muestra .

Autenticar

Esta biblioteca utiliza credenciales predeterminadas de la aplicación para autenticar la conexión al servidor Cloud SQL.

Para activar las credenciales localmente, utilice el siguiente comando gcloud :

    gcloud auth application-default login
    

Conéctate con Intellij

Para conectar IntelliJ a su instancia de Cloud SQL, deberá agregar la biblioteca como un archivo JAR con dependencias en la sección "Archivos adicionales" de la página de configuración del controlador. Por ejemplo, puede encontrar archivos JAR precompilados en la página de versiones del conector Java de Cloud SQL para este fin.

Pitón

El conector Python de Cloud SQL es una biblioteca que se puede usar junto con un controlador de base de datos para permitir que los usuarios con permisos suficientes se conecten a una base de datos de Cloud SQL sin tener que incluir manualmente direcciones IP en la lista blanca o administrar certificados SSL.

Para obtener ejemplos interactivos del uso del Conector Python de Cloud SQL, abra el cuaderno del Conector Python de Cloud SQL .

Los controladores que admite PostgreSQL son pg8000 y asyncpg .

Instalar

Para instalar la última versión de Cloud SQL Python Connector, use el comando pip install y especifique el controlador pg8000 o asyncpg para su base de datos:

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

o

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

Autenticar

Esta biblioteca utiliza credenciales predeterminadas de la aplicación para autenticar la conexión al servidor Cloud SQL.

Para activar las credenciales localmente, utilice el siguiente comando gcloud :

    gcloud auth application-default login
    

Ir

El conector Go de Cloud SQL está diseñado para usarse con el lenguaje Go. Para mayor seguridad, utiliza un cifrado TLS 1.3 robusto y autenticado manualmente entre el conector del cliente y el proxy del servidor, independientemente del protocolo de la base de datos.

Instalar

Puedes instalar este repositorio con go get :

    go get cloud.google.com/go/cloudsqlconn
    

Node.js

El conector Node.js es una biblioteca diseñada para usarse con el entorno de ejecución Node.js que le permite conectarse de forma segura a su instancia de Cloud SQL.

Instalar

Puede instalar la biblioteca con npm install :

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

Usar

Java

Para ver este fragmento en el contexto de una aplicación web, consulte el archivo README en GitHub .

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");

    // cloudSqlRefreshStrategy set to "lazy" is used to perform a
    // refresh when needed, rather than on a scheduled interval.
    // This is recommended for serverless environments to
    // avoid background refreshes from throttling CPU.
    config.addDataSourceProperty("cloudSqlRefreshStrategy", "lazy");

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

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

Pitón

Consulta "Cómo usar este conector" para obtener instrucciones detalladas sobre el uso de la biblioteca. Consulta un ejemplo de código de prueba de conexión en GitHub.

import os

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

import sqlalchemy


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

    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["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

    # initialize Cloud SQL Python Connector object
    connector = Connector(refresh_strategy="LAZY")

    def getconn() -> pg8000.dbapi.Connection:
        conn: pg8000.dbapi.Connection = connector.connect(
            instance_connection_name,
            "pg8000",
            user=db_user,
            password=db_pass,
            db=db_name,
            ip_type=ip_type,
        )
        return conn

    # The Cloud SQL Python Connector can be used with SQLAlchemy
    # using the 'creator' argument to 'create_engine'
    pool = sqlalchemy.create_engine(
        "postgresql+pg8000://",
        creator=getconn,
        # ...
    )
    return pool

Ir

Consulta la sección "Uso" para obtener instrucciones detalladas sobre el uso de la biblioteca. Consulta un ejemplo de código de prueba de conexión en GitHub.

package cloudsql

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

	"cloud.google.com/go/cloudsqlconn"
	"github.com/jackc/pgx/v5"
	"github.com/jackc/pgx/v5/stdlib"
)

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 passwords and other 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")
	)

	dsn := fmt.Sprintf("user=%s password=%s database=%s", dbUser, dbPwd, dbName)
	config, err := pgx.ParseConfig(dsn)
	if err != nil {
		return nil, err
	}
	var opts []cloudsqlconn.Option
	if usePrivate != "" {
		opts = append(opts, cloudsqlconn.WithDefaultDialOptions(cloudsqlconn.WithPrivateIP()))
	}
	// WithLazyRefresh() Option is used to perform refresh
	// when needed, rather than on a scheduled interval.
	// This is recommended for serverless environments to
	// avoid background refreshes from throttling CPU.
	opts = append(opts, cloudsqlconn.WithLazyRefresh())
	d, err := cloudsqlconn.NewDialer(context.Background(), opts...)
	if err != nil {
		return nil, err
	}
	// Use the Cloud SQL connector to handle connecting to the instance.
	// This approach does *NOT* require the Cloud SQL proxy.
	config.DialFunc = func(ctx context.Context, network, instance string) (net.Conn, error) {
		return d.Dial(ctx, instanceConnectionName)
	}
	dbURI := stdlib.RegisterConnConfig(config)
	dbPool, err := sql.Open("pgx", dbURI)
	if err != nil {
		return nil, fmt.Errorf("sql.Open: %w", err)
	}
	return dbPool, nil
}

Node.js

Para obtener instrucciones detalladas sobre el uso de la biblioteca, consulte Uso .

const Knex = require('knex');
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 connection pool for a Cloud SQL instance
// of Postgres using the Cloud SQL Node.js Connector.
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.getOptions({
    instanceConnectionName: process.env.INSTANCE_CONNECTION_NAME,
    ipType: getIpType(),
  });
  const dbConfig = {
    client: 'pg',
    connection: {
      ...clientOpts,
      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);
};

Hacer cumplir

Al usar la aplicación de conectores , puede usar únicamente el proxy de autenticación de Cloud SQL o los conectores de lenguaje de Cloud SQL para conectarse a las instancias de Cloud SQL. Con la aplicación de conectores, Cloud SQL rechaza las conexiones directas a la base de datos.

Si utiliza una instancia con Private Service Connect habilitado , existe una limitación. Si la instancia tiene habilitada la aplicación de conectores, no podrá crear réplicas de lectura para ella. De igual forma, si la instancia tiene réplicas de lectura, tampoco podrá habilitar la aplicación de conectores para ella.

nube g

Para aplicar el uso exclusivo de Cloud SQL Auth Proxy o Cloud SQL Language Connectors para conectarse a una instancia, utilice el comando gcloud sql instances patch :

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

Reemplace INSTANCE_NAME con el nombre de su instancia de Cloud SQL.

DESCANSAR

Antes de utilizar cualquiera de los datos solicitados, realice las siguientes sustituciones:

  • PROJECT_ID : el ID o número de proyecto del Google Cloud proyecto que contiene la instancia
  • INSTANCE_NAME : el nombre de su instancia de Cloud SQL

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

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

Para enviar su solicitud, expanda una de estas opciones:

Debería recibir una respuesta JSON similar a la siguiente:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME",
  "status": "PENDING",
  "user": "[email protected]",
  "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"
}

Solucionar problemas

Versiones del controlador

Asegúrese de utilizar la versión más reciente de los conectores de Cloud SQL y del controlador de su base de datos para evitar incompatibilidades. Algunas versiones anteriores de los controladores no son compatibles.

Rutas de conexión

Los conectores de Cloud SQL autorizan las conexiones, pero no ofrecen nuevas rutas de conectividad. Por ejemplo, para conectarse a una instancia de Cloud SQL mediante una dirección IP privada, la aplicación ya debe tener acceso a la VPC.

Problemas de conexión de depuración

Para obtener ayuda adicional con problemas de conexión, consulte las páginas Solucionar problemas de conexión y Depurar problemas de conexión .

¿Qué sigue?