Conéctate mediante conectores de lenguaje de Cloud SQL

MySQL   |  PostgreSQL   |  SQL Server

Los conectores de Cloud SQL son bibliotecas que proporcionan encriptación y autorización basada en Identity and Access Management (IAM) cuando se conectan a una instancia de Cloud SQL. No pueden proporcionar una ruta de red a una instancia de Cloud SQL, si aún no hay una.

Otras formas de conectarse a una instancia de Cloud SQL son el uso de un cliente de base de datos o el proxy de autenticación de Cloud SQL. Consulta la página 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 de Java de Cloud SQL
• El conector de Python de Cloud SQL (Abrir en Colab)
• El conector de Go de Cloud SQL
• El conector de Node.js para Cloud SQL

Ventajas

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

• Autorización de IAM: Usa permisos de IAM para controlar quién o qué puede conectarse a tus instancias de Cloud SQL.
• Conveniencia: Quita el requisito de administrar certificados SSL, configurar reglas de firewall o habilitar redes autorizadas.
• Autenticación de la base de datos de IAM: Proporciona compatibilidad con la autenticación automática de la base de datos de IAM de Cloud SQL.

Antes de comenzar

• Habilita la API de Administrador de Cloud SQL

  Enable the API

• Crea una instancia de Cloud SQL y configura el usuario predeterminado.
  

  Para obtener más información sobre la creación de instancias, consulta Crea instancias.

  Para obtener más información sobre la configuración del usuario predeterminado, consulta Configura la contraseña de la cuenta de usuario predeterminada.

• Configura las funciones y permisos necesarios para conectarte a una instancia de Cloud SQL.
  Nota: Si el principal de IAM de autorización pertenece a un proyecto diferente al que contiene la instancia de Cloud SQL, debes hacer lo siguiente:

  • Habilita la API de Cloud SQL Admin en ambos proyectos.
  • Agrega los permisos de IAM para la principal de IAM en el proyecto que contiene la instancia de Cloud SQL.

Configuración

Java

El conector de Java de Cloud SQL es una biblioteca que proporciona encriptación y autorización basadas en IAM cuando se conecta a una instancia de Cloud SQL. No puede proporcionar una ruta de red a una instancia de Cloud SQL si aún no hay una.

Instalar

Si deseas obtener instrucciones para desarrollar y usar los controladores para JDBC y R2DBC con el conector de Java de Cloud SQL, consulta los siguientes vínculos:

• JDBC: conéctate a Cloud SQL con JDBC.
• R2DBC: conéctate a Cloud SQL con R2DBC.

Para ver ejemplos de esta biblioteca que se usa en el contexto de una aplicación, consulta estas aplicaciones de muestra.

Autenticar

Esta biblioteca usa las credenciales predeterminadas de la aplicación para autenticar la conexión con el servidor de Cloud SQL.

Para activar las credenciales de forma local, usa el siguiente comando de gcloud:

    gcloud auth application-default login
    

Conéctate con IntelliJ

Para conectar IntelliJ a tu instancia de Cloud SQL, debes agregar la biblioteca como un JAR con dependencias en la sección Archivos adicionales en la página de configuración del controlador. Por ejemplo, los archivos de fat JAR precompilados se pueden encontrar en la página Versiones del conector de Java de Cloud SQL para este propósito.

Python

El conector de Python de Cloud SQL es una biblioteca que se puede usar junto con un controlador de base de datos para permitir a los usuarios con permisos suficientes conectarse a una base de datos de Cloud SQL sin tener que incluir IPs en la lista de entidades permitidas ni administrar certificados SSL de forma manual.

Si deseas ver ejemplos interactivos sobre el uso del conector de Python de Cloud SQL, abre el notebook de conectores de Python de Cloud SQL.

Los controladores que admite PostgreSQL son pg8000 y asyncpg.

Instalar

Para instalar la versión más reciente del conector de Python de Cloud SQL, usa el comando pip install y especifica el controlador pg8000 o asyncpg para tu base de datos:

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

o

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

Autenticar

Esta biblioteca usa las credenciales predeterminadas de la aplicación para autenticar la conexión con el servidor de Cloud SQL.

Para activar las credenciales de forma local, usa el siguiente comando de gcloud:

    gcloud auth application-default login
    

Go

El conector de Cloud SQL para Go es un conector de Cloud SQL diseñado para usarse con el lenguaje Go. Para mejorar la seguridad, este conector usa la encriptación sólida TLS 1.3 autenticada de forma manual entre el conector del cliente y el proxy del servidor, independientemente del protocolo de base de datos.

Instalar

Puedes instalar este repositorio con go get:

    go get cloud.google.com/go/cloudsqlconn
    

Node.js

El conector de Node.js es una biblioteca diseñada para usarse con el entorno de ejecución de Node.js que te permite conectarte de manera segura a tu instancia de Cloud SQL.

Instalar

Puedes 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, consulta 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");


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

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

Python

Consulta Cómo usar este conector para obtener instrucciones detalladas sobre cómo usar la biblioteca. Consulta el 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()

    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

Go

Consulta Uso para obtener instrucciones detalladas sobre el uso de la biblioteca. Consulta el 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()))
	}
	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, consulta 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);
};

Aplicar

Con la aplicación forzosa de conectores, puedes aplicar el uso exclusivo del proxy de autenticación de Cloud SQL o los conectores de lenguaje de Cloud SQL para conectarte a instancias de Cloud SQL. Con la aplicación del conector, Cloud SQL rechaza las conexiones directas a la base de datos.

Si usas una instancia habilitada para Private Service Connect, existe una limitación. Si la instancia tiene habilitada la aplicación forzosa de conectores, no puedes crear réplicas de lectura para ella. Del mismo modo, si la instancia tiene réplicas de lectura, no puedes habilitar la aplicación forzosa de conectores para la instancia.

gcloud

Para aplicar el uso exclusivo del proxy de autenticación de Cloud SQL o los conectores de lenguaje de Cloud SQL para conectarse a una instancia, usa el comando gcloud sql instances patch:

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

Reemplaza INSTANCE_NAME por el nombre de tu instancia de Cloud SQL.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

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

Nota: Si estableces el valor del parámetro connectorEnforcement en REQUIRED, todas las conexiones deben usar los conectores de lenguaje de Cloud SQL, incluido el proxy de autenticación de Cloud SQL y los conectores de Java, Python, Go y Node.js.

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 tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME"

PowerShell (Windows)

Nota: El siguiente comando supone que accediste a la CLI de gcloud con tu cuenta de usuario mediante la ejecución de gcloud init o gcloud auth login. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME",
  "status": "PENDING",
  "user": "[e-mail]",
  "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úrate de usar la versión más reciente de los conectores de Cloud SQL y el controlador de base de datos para evitar incompatibilidades. Algunas versiones anteriores de controladores no son compatibles.

Rutas de conexión

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

Depurar problemas de conexión

Para obtener más ayuda sobre problemas de conexión, consulta las páginas Soluciona problemas y Depura problemas de conexión.

¿Qué sigue?

• Consulta la página principal del conector de Java de Cloud SQL en GitHub.
• Consulta la página principal del conector de Python de Cloud SQL en GitHub.
• Obtén más información sobre el proxy de Cloud SQL Auth.
• Obtén más información sobre IAM.
• Obtén información sobre opciones de asistencia.