Verbindung über Cloud SQL Language Connectors herstellen

Die Cloud SQL-Connectors sind Bibliotheken, die für das Herstellen einer Verbindung zu einer Cloud SQL-Instanz eine Verschlüsselung sowie eine IAM-Autorisierung (Identity and Access Management) ermöglichen. Sie können keinen Netzwerkpfad zu einer Cloud SQL-Instanz bereitstellen, wenn noch kein solcher vorhanden ist.

Eine andere Möglichkeit, eine Verbindung zu einer Cloud SQL-Instanz herzustellen, ist die Verwendung eines Datenbankclients oder des Cloud SQL Auth-Proxys. Weitere Informationen zum Herstellen einer Verbindung zu einer Cloud SQL-Instanz finden Sie auf der Seite Informationen zu Verbindungsoptionen.

Auf dieser Seite werden die folgenden Cloud SQL-Connectors erläutert:

  • Der Cloud SQL-Java-Connector
  • Der Cloud SQL-Python-Connector (in Colab öffnen)
  • Der Cloud SQL-Go-Connector
  • Der Cloud SQL-Node.js-Connector

Vorteile

Die Verwendung eines Cloud SQL-Connectors bietet folgende Vorteile:

  • IAM-Autorisierung: Verwendet IAM-Berechtigungen, um zu steuern, wer oder was eine Verbindung zu Ihren Cloud SQL-Instanzen herstellen kann.
  • Weniger Aufwand: Es ist nicht mehr erforderlich, SSL-Zertifikate zu verwalten, Firewallregeln zu konfigurieren oder autorisierte Netzwerke zu aktivieren.
  • IAM-Datenbankauthentifizierung: Bietet Unterstützung für die automatische IAM-Datenbankauthentifizierungsfunktion von Cloud SQL.

Hinweise

  • Cloud SQL Admin API aktivieren.

    Enable the API

  • Cloud SQL-Instanz erstellen und den Standardnutzer konfigurieren.

    Weitere Informationen zum Erstellen von Instanzen finden Sie unter Instanzen erstellen.

    Weitere Informationen zum Konfigurieren des Standardnutzers finden Sie unter Passwort für das Standardnutzerkonto festlegen.

  • Die Rollen und Berechtigungen konfigurieren, die zum Herstellen einer Verbindung zu einer Cloud SQL-Instanz erforderlich sind.

Einrichtung

Java

Der Cloud SQL-Java-Connector ist eine Bibliothek, die IAM-basierte Autorisierung und Verschlüsselung bietet, wenn eine Verbindung zu einer Cloud SQL-Instanz hergestellt wird. Sie können keinen Netzwerkpfad zu einer Cloud SQL-Instanz bereitstellen, falls noch keine vorhanden ist.

Installation

Eine Anleitung zum Erstellen und Verwenden der Treiber für JDBC und R2DBC mit dem Cloud SQL-Java-Connector finden Sie unter den folgenden Links:

Beispiele für die Verwendung dieser Bibliothek im Kontext einer Anwendung finden Sie in diesen Beispielanwendungen.

Authentifizierung

Diese Bibliothek verwendet Standardanmeldedaten für Anwendungen, um die Verbindung zum Cloud SQL-Server zu authentifizieren.

Um Anmeldedaten lokal zu aktivieren, führen Sie den folgenden gcloud-Befehl aus:

    gcloud auth application-default login

Mit IntelliJ verbinden

Um IntelliJ mit Ihrer Cloud SQL-Instanz zu verbinden, müssen Sie die Bibliothek als JAR-Datei mit Abhängigkeiten im Abschnitt Zusätzliche Dateien der Seite mit den Treibereinstellungen hinzufügen. Für diesen Zweck finden Sie z. B. vordefinierte FAT-JAR-Dateien auf der Seite Versionen von Cloud SQL-Java-Connectors.

Python

Der Cloud SQL-Python-Connector ist eine Bibliothek, die neben einem Datenbanktreiber verwendet werden kann, um Nutzern mit ausreichenden Berechtigungen die Verbindung zu einer Cloud SQL-Datenbank zu ermöglichen, ohne dass sie manuell IPs zulassen oder SSL-Zertifikate verwalten müssen.

Wenn Sie interaktive Beispiele für die Verwendung des Cloud SQL-Python-Connectors sehen möchten, öffnen Sie das Cloud SQL-Python-Connector-Notebook.

Der derzeit unterstützte Treiber für PostgreSQL ist pg8000.

Installation

Folgen Sie dieser Anleitung, um den neuesten Release zu installieren.

Authentication

Diese Bibliothek verwendet Standardanmeldedaten für Anwendungen, um die Verbindung zum Cloud SQL-Server zu authentifizieren.

Um Anmeldedaten lokal zu aktivieren, führen Sie den folgenden gcloud-Befehl aus:

    gcloud auth application-default login

Go

Der Cloud SQL-Go-Connector ist ein Cloud SQL-Connector, der für die Verwendung mit der Go-Sprache entwickelt wurde. Zur Verbesserung der Sicherheit verwendet dieser Connector unabhängig vom Datenbankprotokoll eine robuste, manuell authentifizierte TLS 1.3-Verschlüsselung zwischen dem Client-Connector und dem serverseitigen Proxy.

Installation

Sie können dieses Repository mit go get installieren:

    go get cloud.google.com/go/cloudsqlconn

Node.js

Der Node.js-Connector ist eine Bibliothek, die für die Verwendung mit der Node.js-Laufzeit entwickelt wurde und mit der Sie eine sichere Verbindung zu Ihrer Cloud SQL-Instanz herstellen können.

Installation

Sie können die Bibliothek mit npm install installieren:

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

Nutzung

Java

Wenn Sie dieses Snippet im Kontext einer Webanwendung sehen möchten, rufen Sie die README-Datei auf GitHub auf.

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

Eine ausführliche Anleitung zur Verwendung der Bibliothek finden Sie unter Connector verwenden. Beispielcode für Verbindungstests auf GitHub ansehen.

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

Einfach loslegen (Go)

Ausführliche Informationen zur Verwendung der Bibliothek finden Sie unter Nutzung. Beispielcode für Verbindungstests auf GitHub ansehen.

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

Eine ausführliche Anleitung zur Verwendung der Bibliothek finden Sie unter Nutzung.

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

Fehlerbehebung

Treiberversionen

Sie müssen die neueste Version der Cloud SQL-Connectors und Ihres Datenbanktreibers verwenden, um Inkompatibilitäten zu vermeiden. Einige ältere Versionen der Treiber werden nicht unterstützt.

Verbindungspfade

Die Cloud SQL-Connectors bieten eine Autorisierung für Verbindungen, stellen jedoch keine neuen Pfade für die Konnektivität bereit. Wenn Sie beispielsweise eine Verbindung zu einer Cloud SQL-Instanz mithilfe einer privaten IP-Adresse herstellen möchten, muss Ihre Anwendung bereits VPC-Zugriff haben.

Verbindungsprobleme beheben

Weitere Informationen zu Verbindungsproblemen finden Sie auf den Seiten Fehlerbehebung und Verbindungsprobleme beheben.

Nächste Schritte