Se connecter à l'aide de connecteurs de langage Cloud SQL

Les connecteurs Cloud SQL sont des bibliothèques qui fournissent le chiffrement et l'autorisation basée sur IAM (Identity and Access Management) lors de la connexion à une instance Cloud SQL. Ils ne peuvent pas fournir de chemin d'accès réseau vers une instance Cloud SQL s'il n'en existe pas déjà un.

Vous pouvez également vous connecter à une instance Cloud SQL à l'aide d'un client de base de données ou du proxy d'authentification Cloud SQL. Pour plus d'informations sur la connexion à une instance Cloud SQL, consultez la page À propos des options de connexion.

Cette page traite des connecteurs Cloud SQL suivants :

  • Connecteur Java Cloud SQL
  • Connecteur Python Cloud SQL (ouvert dans Colab)
  • Connecteur Go Cloud SQL
  • Connecteur Node.js Cloud SQL

Avantages

L'utilisation d'un connecteur Cloud SQL présente les avantages suivants :

  • Autorisation IAM : utilise les autorisations IAM pour contrôler les utilisateurs et les services qui peuvent se connecter à vos instances Cloud SQL.
  • Commodité : supprime l'obligation de gérer les certificats SSL, de configurer les règles de pare-feu ou d'activer les réseaux autorisés.
  • Authentification IAM pour les bases de données : compatible avec la fonctionnalité d'authentification automatique pour les bases de données de Cloud SQL.

Avant de commencer

  • Activez l'API Cloud SQL Admin.

    Enable the API

  • Créez une instance Cloud SQL et configuré l'utilisateur par défaut.

    Pour en savoir plus sur la création d'instances, consultez la section Créer des instances.

    Pour en savoir plus sur la configuration de l'utilisateur par défaut, consultez la section Définir le mot de passe du compte utilisateur par défaut.

  • configuré les rôles et autorisations requis pour se connecter à une instance Cloud SQL.

Préparation

Java

Le connecteur Java Cloud SQL est une bibliothèque qui fournit une autorisation basée sur IAM et un chiffrement lors de la connexion à une instance Cloud SQL. Il ne peut pas fournir de chemin d'accès réseau à une instance Cloud SQL s'il n'en existe pas déjà un.

Installer

Pour obtenir des instructions sur la création et l'utilisation des pilotes pour JDBC et R2DBC avec le connecteur Java Cloud SQL, consultez les liens suivants :

Pour obtenir des exemples d'utilisation de cette bibliothèque dans le contexte d'une application, consultez ces exemples d'applications.

Authentifier

Cette bibliothèque utilise les identifiants par défaut de l'application pour authentifier la connexion au serveur Cloud SQL.

Pour activer les identifiants localement, exécutez la commande gcloud suivante :

    gcloud auth application-default login

Connexion avec IntelliJ

Pour connecter IntelliJ à votre instance Cloud SQL, vous devez ajouter la bibliothèque en tant que fichier JAR avec des dépendances dans la section Fichiers supplémentaires de la page des paramètres des pilotes. Par exemple, vous pouvez trouver des fichiers Fat JAR prédéfinis sur la page Versions du connecteur Java pour Cloud SQL à cet effet.

Python

Le connecteur Python Cloud SQL est une bibliothèque qui peut être utilisée avec un pilote de base de données pour permettre aux utilisateurs disposant des autorisations suffisantes de se connecter à une base de données Cloud SQL, sans avoir à ajouter manuellement les adresses IP à la liste d'autorisation ni à gérer les certificats SSL.

Pour obtenir des exemples interactifs d'utilisation du connecteur Python Cloud SQL, ouvrez le notebook du connecteur Python Cloud SQL.

Les pilotes compatibles avec PostgreSQL sont pg8000 et asyncpg.

Installer

Pour installer la dernière version du connecteur Python Cloud SQL, exécutez la commande pip install et spécifiez le pilote pg8000 ou asyncpg pour votre base de données :

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

ou

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

Authentifier

Cette bibliothèque utilise les identifiants par défaut de l'application pour authentifier la connexion au serveur Cloud SQL.

Pour activer les identifiants localement, exécutez la commande gcloud suivante :

    gcloud auth application-default login

Go

Cloud SQL Go est un connecteur Cloud SQL conçu pour être utilisé avec le langage Go. Pour renforcer la sécurité, ce connecteur utilise un chiffrement TLS 1.3 robuste et authentifié manuellement entre le connecteur client et le proxy côté serveur, indépendamment du protocole de base de données.

Installer

Vous pouvez installer ce dépôt à l'aide de go get :

    go get cloud.google.com/go/cloudsqlconn

Node.js

Le connecteur Node.js est une bibliothèque conçue pour être utilisée avec l'environnement d'exécution Node.js qui vous permet de vous connecter à votre instance Cloud SQL de façon sécurisée.

Installer

Vous pouvez installer la bibliothèque avec npm install :

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

Utiliser

Java

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur 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

Pour obtenir des instructions détaillées sur l'utilisation de la bibliothèque, consultez la page Utiliser ce connecteur. Affichez l'exemple de code de test de connectivité sur 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

Consultez la page Utilisation pour obtenir des instructions détaillées sur l'utilisation de la bibliothèque. Affichez l'exemple de code de test de connectivité sur 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

Pour obtenir des instructions détaillées sur l'utilisation de la bibliothèque, consultez la section Utilisation.

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

Appliquer

Grâce à l'application des connecteurs, vous pouvez n'autoriser que le proxy d'authentification Cloud SQL ou les connecteurs de langage Cloud SQL pour vous connecter aux instances Cloud SQL. Avec cette option d'imposition de connecteurs, Cloud SQL rejette les connexions directes à la base de données.

Si vous utilisez une instance avec Private Service Connect activé, vous devez tenir compte d'une limitation. Si l'instance dispose d'une application du connecteur activée, vous ne pouvez pas créer d'instances dupliquées avec accès en lecture pour l'instance. De même, si l'instance comporte des instances dupliquées avec accès en lecture, vous ne pouvez pas activer l'application des connecteurs pour l'instance.

gcloud

Pour n'autoriser que le proxy d'authentification Cloud SQL ou les connecteurs de langage Cloud SQL pour vous connecter à une instance, utilisez la commande gcloud sql instances patch:

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

Remplacez INSTANCE_NAME par le nom de votre instance Cloud SQL.

REST

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • PROJECT_ID : ID ou numéro de projet du projet Google Cloud contenant l'instance.
  • INSTANCE_NAME: nom de votre instance Cloud SQL

Méthode HTTP et URL :

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

Corps JSON de la requête :

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

Pour envoyer votre requête, développez l'une des options suivantes :

Vous devriez recevoir une réponse JSON de ce type :

{
  "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"
}

Résoudre les problèmes

Versions des pilotes

Assurez-vous que vous utilisez la dernière version des connecteurs Cloud SQL et de vos pilotes de base de données pour éviter les incompatibilités. Certaines versions anciennes de pilotes ne sont pas compatibles.

Chemins d'accès de connexion

Les connecteurs Cloud SQL fournissent l'autorisation pour les connexions, mais ils ne fournissent pas de nouveaux chemins d'accès à la connectivité. Par exemple, pour se connecter à une instance Cloud SQL à l'aide d'une adresse IP privée, votre application doit déjà disposer d'un accès VPC.

Déboguer les problèmes de connexion

Pour obtenir une aide supplémentaire concernant les problèmes de connexion, consultez les pages Dépannage et Déboguer les problèmes de connexion.

Étapes suivantes