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-basierte 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.

Installieren

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.

Authentifizieren

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.

PostgreSQL unterstützt die Treiber pg8000 und asyncpg.

Installieren

Wenn Sie die neueste Version des Cloud SQL Python-Connectors installieren möchten, verwenden Sie den Befehl pip install und geben Sie entweder den Treiber pg8000 oder asyncpg für Ihre Datenbank an:

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

oder

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

Authentifizieren

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.

Installieren

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.

Installieren

So installieren Sie die Bibliothek mit npm install:

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

Verwenden

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

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

Erzwingen

Mit der Erzwung von Verbindungen können Sie festlegen, dass nur der Cloud SQL Auth-Proxy oder Cloud SQL Language Connectors für die Verbindung zu Cloud SQL-Instanzen verwendet werden dürfen. Bei der Connector-Erzwingung werden direkte Verbindungen zur Datenbank von Cloud SQL abgelehnt.

Wenn Sie eine Instanz mit aktiviertem Private Service Connect verwenden, gibt es eine Einschränkung. Wenn für die Instanz die Connector-Erzwigung aktiviert ist, können Sie keine Lesereplikate für die Instanz erstellen. Wenn die Instanz Lesereplikate hat, können Sie die Connector-Erzwigung für die Instanz nicht aktivieren.

gcloud

Wenn Sie erzwingen möchten, dass nur der Cloud SQL Auth-Proxy oder Cloud SQL Language Connectors für die Verbindung zu einer Instanz verwendet werden, verwenden Sie den Befehl gcloud sql instances patch:

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

Ersetzen Sie INSTANCE_NAME durch den Namen Ihrer Cloud SQL-Instanz.

REST

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • PROJECT_ID: die ID oder Projektnummer des Google Cloud-Projekts, das die Instanz enthält
  • INSTANCE_NAME: Der Name Ihrer Cloud SQL-Instanz

HTTP-Methode und URL:

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

JSON-Text anfordern:

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

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie sollten in etwa folgende JSON-Antwort erhalten:

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

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