Verbindungen mithilfe von Cloud SQL-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 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 in der Verbindungsübersicht. .

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

  • Der Cloud SQL-Java-Connector
  • Der Cloud SQL-Python-Connector

Hinweis

Damit Sie eine Verbindung zu einer Cloud SQL-Instanz herstellen können, muss Folgendes gegeben sein:

  • Cloud SQL Admin API aktiviert

    Aktivieren Sie die API

  • Eine Cloud SQL-Instanz, in der der Standardnutzer konfiguriert ist.

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

    Weitere Informationen zur Konfiguration des Standardnutzers finden Sie unter Standardnutzerkonto konfigurieren.

  • Die Rollen und Berechtigungen konfiguriert sein, die zum Herstellen einer Verbindung zu einer Cloud SQL-Instanz erforderlich sind.
  • Weitere Informationen zum Herstellen einer Verbindung zu einer Cloud SQL-Instanz finden Sie auf der Seite Verbindungsübersicht.

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 keiner vorhanden ist.

Installation

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

JDBC: Verbindung zu Postgres über JDBC herstellen.

R2DBC: Verbindung zu Postgres über R2DBC herstellen.

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 Python-Connector von Cloud SQL ist eine Bibliothek, die zusammen mit einem Datenbanktreiber verwendet werden kann, damit Nutzer mit ausreichenden Berechtigungen eine Verbindung zu einer Cloud SQL-Datenbank herstellen können, ohne IP-Adressen manuell auf die Zulassungsliste setzen oder SSL-Zertifikate verwalten zu müssen.

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

Nutzung

Java

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

cloud-sql/postgres/servlet/src/main/java/com/example/cloudsql/ConnectionPoolContextListener.java 
// Note: For Java users, the Cloud SQL JDBC Socket Factory can provide authenticated connections
// which is preferred to using the Cloud SQL Proxy with Unix sockets.
// See https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory for details.

// 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=<CLOUD_SQL_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", CLOUD_SQL_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.
DataSource pool = new HikariDataSource(config);

Python

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

tests/system/test_pg8000_connection.py 
# The Cloud SQL Python Connector can be used along with SQLAlchemy using the
# 'creator' argument to 'create_engine'
def init_connection_engine() -> sqlalchemy.engine.Engine:
    def getconn() -> pg8000.dbapi.Connection:
        conn: pg8000.dbapi.Connection = connector.connect(
            os.environ["POSTGRES_CONNECTION_NAME"],
            "pg8000",
            user=os.environ["POSTGRES_USER"],
            password=os.environ["POSTGRES_PASS"],
            db=os.environ["POSTGRES_DB"],
        )
        return conn

    engine = sqlalchemy.create_engine(
        "postgresql+pg8000://",
        creator=getconn,
    )
    engine.dialect.description_encoding = None
    return engine

Fehlerbehebung

Firewallkonfiguration

Der Cloud SQL-Auth-Proxy stellt Verbindungen zu Cloud SQL-Instanzen über Port 3307 her. Durch eine Firewall geschützte Anwendungen müssen möglicherweise so konfiguriert werden, dass ausgehende Verbindungen über TCP-Port 3307 zugelassen sind. Eine von einer Firewall blockierte Verbindung führt in der Regel zu einem Verbindungsfehler, z. B. com.mysql.jdbc.exceptions.jdbc4.CommunicationsException: Communications link failure.

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. Damit Sie eine Verbindung zu einer Cloud SQL-Instanz mithilfe einer öffentlichen IP-Adresse herstellen können, muss sich Ihre Anwendung in einem autorisierten Netzwerk befinden.

Debugging von Verbindungsproblemen

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

Nächste Schritte