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.

Vorbereitung

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

Der von SQL Server unterstützte Treiber ist pytds.

Installieren

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

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

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 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 is equivalent to setting the config options below:
    // jdbc:sqlserver://;user=<DB_USER>;password=<DB_PASS>;databaseName=<DB_NAME>;
    // socketFactoryClass=com.google.cloud.sql.sqlserver.SocketFactory;
    // socketFactoryConstructorArg=<INSTANCE_CONNECTION_NAME>

    // 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
        .setDataSourceClassName("com.microsoft.sqlserver.jdbc.SQLServerDataSource");
    config.setUsername(DB_USER); // e.g. "root", "sqlserver"
    config.setPassword(DB_PASS); // e.g. "my-password"
    config.addDataSourceProperty("databaseName", DB_NAME);

    config.addDataSourceProperty("socketFactoryClass",
        "com.google.cloud.sql.sqlserver.SocketFactory");
    config.addDataSourceProperty("socketFactoryConstructorArg", INSTANCE_CONNECTION_NAME);

    // The Java Connector provides SSL encryption, so it should be disabled
    // at the driver level.
    config.addDataSourceProperty("encrypt", "false");

    // ... 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 pytds

import sqlalchemy


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

    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.get("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

    connector = Connector(ip_type)

    connect_args = {}
    # If your SQL Server instance requires SSL, you need to download the CA
    # certificate for your instance and include cafile={path to downloaded
    # certificate} and validate_host=False. This is a workaround for a known issue.
    if os.environ.get("DB_ROOT_CERT"):  # e.g. '/path/to/my/server-ca.pem'
        connect_args = {
            "cafile": os.environ["DB_ROOT_CERT"],
            "validate_host": False,
        }

    def getconn() -> pytds.Connection:
        conn = connector.connect(
            instance_connection_name,
            "pytds",
            user=db_user,
            password=db_pass,
            db=db_name,
            **connect_args
        )
        return conn

    pool = sqlalchemy.create_engine(
        "mssql+pytds://",
        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"
	mssql "github.com/denisenkom/go-mssqldb"
)

type csqlDialer struct {
	dialer     *cloudsqlconn.Dialer
	connName   string
	usePrivate bool
}

// DialContext adheres to the mssql.Dialer interface.
func (c *csqlDialer) DialContext(ctx context.Context, network, addr string) (net.Conn, error) {
	var opts []cloudsqlconn.DialOption
	if c.usePrivate {
		opts = append(opts, cloudsqlconn.WithPrivateIP())
	}
	return c.dialer.Dial(ctx, c.connName, opts...)
}

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

	dbURI := fmt.Sprintf("user id=%s;password=%s;database=%s;", dbUser, dbPwd, dbName)
	c, err := mssql.NewConnector(dbURI)
	if err != nil {
		return nil, fmt.Errorf("mssql.NewConnector: %w", err)
	}
	dialer, err := cloudsqlconn.NewDialer(context.Background())
	if err != nil {
		return nil, fmt.Errorf("cloudsqlconn.NewDailer: %w", err)
	}
	c.Dialer = &csqlDialer{
		dialer:     dialer,
		connName:   instanceConnectionName,
		usePrivate: usePrivate != "",
	}

	dbPool := sql.OpenDB(c)
	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 {Connection} = require('tedious');
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 a TCP connection
// to a Cloud SQL instance of SQL Server.
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.getTediousOptions({
    instanceConnectionName: process.env.INSTANCE_CONNECTION_NAME,
    ipType: getIpType(),
  });
  const dbConfig = {
    // Please note that the `server` property here is not used and is only
    // defined due to a bug in the tedious driver
    // (ref: https://github.com/tediousjs/tedious/issues/1541)
    // With that in mind, do not try to change this value since it will have no
    // impact in how the connector works, this sample will be updated to remove
    // this property declaration as soon as the tedious driver bug is fixed
    server: '0.0.0.0', // e.g. '127.0.0.1'
    authentication: {
      type: 'default',
      options: {
        userName: process.env.DB_USER, // e.g. 'my-db-user'
        password: process.env.DB_PASS, // e.g. 'my-db-password'
      },
    },
    options: {
      ...clientOpts,
      // Please note that the `port` property here is not used and is only
      // defined due to a bug in the tedious driver
      // (ref: https://github.com/tediousjs/tedious/issues/1541)
      // With that in mind, do not try to change this value since it will have
      // no impact in how the connector works, this sample will be updated to
      // remove this property declaration as soon as the tedious driver bug is
      // fixed
      port: 9999,
      database: process.env.DB_NAME, // e.g. 'my-database'
      useColumnNames: true,
    },
    // ... Specify additional properties here.
    ...config,
  };

  // Establish a connection to the database.
  return new Connection(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