Verbindung über den Cloud SQL Auth-Proxy herstellen

MySQL   |  PostgreSQL   |  SQL Server

Auf dieser Seite wird gezeigt, wie Sie mithilfe des Cloud SQL Auth-Proxys eine Verbindung zu Ihrer Cloud SQL-Instanz herstellen.

Weitere Informationen über die Funktionsweise des Cloud SQL Auth-Proxys finden Sie unter Informationen zum Cloud SQL Auth-Proxy.

Überblick

Für die Verbindung mit einer Cloud SQL-Instanz wird die Verwendung des Cloud SQL Auth-Proxys empfohlen. Der Cloud SQL Auth-Proxy:

• Funktioniert mit öffentlichen wie mit privaten IP-Endpunkten
• Validiert Verbindungen mithilfe von Anmeldedaten für einen Nutzer oder ein Dienstkonto
• Verpackt die Verbindung in einer SSL/TLS-Ebene, die für eine Cloud SQL-Instanz autorisiert ist

Einige Google Cloud-Dienste und -Anwendungen verwenden den Cloud SQL Auth-Proxy, um Verbindungen für öffentliche IP-Pfade mit Verschlüsselung und Autorisierung bereitzustellen, darunter:

• App Engine-Standardumgebung
• Flexible App Engine-Umgebung
• Cloud Functions
• Cloud Run

In Google Kubernetes Engine ausgeführte Anwendungen können eine Verbindung über den Cloud SQL Auth-Proxy herstellen.

Hinweis: Für die Verbindung von Google Kubernetes Engine empfehlen wir, den Cloud SQL Auth-Proxy in einem sidecar-Muster als zusätzlichen Container auszuführen, der einen Pod mit Ihrer Anwendung teilt. Weitere Informationen finden Sie in der zugehörigen Kurzanleitung.

Eine kurze Einführung in die Verwendung des Cloud SQL Auth-Proxys finden Sie unter Kurzanleitung.

Sie können die Verbindung auch mit oder ohne den Cloud SQL Auth-Proxy über einen psql-Client von einem lokalen Computer oder von Compute Engine herstellen.

Hinweise

Bevor Sie eine Verbindung zu einer Cloud SQL-Instanz herstellen können, müssen Sie Folgendes tun:

1. • Achten Sie darauf, dass das Konto für einen Nutzer oder ein Dienstkonto die Rolle "Cloud SQL-Client" hat. Diese Rolle enthält die Berechtigung cloudsql.instances.connect, mit der ein Hauptkonto autorisiert wird, zu allen Cloud SQL-Instanzen in einem Projekt eine Verbindung herzustellen.

     Zur IAM-Seite

   • Sie können optional eine IAM-Bedingung in die IAM-Richtlinienbindung aufnehmen, die dem Konto die Berechtigung erteilt, eine Verbindung nur zu einer bestimmten Cloud SQL-Instanz herzustellen.

2. Enable the Cloud SQL Admin API.

   Enable the API

3. Installieren und initialisieren Sie die gcloud CLI.
4. Optional. Installieren Sie den Cloud SQL Auth-Proxy-Docker-Client.

Laden Sie den Cloud SQL Auth-Proxy herunter

Linux 64-Bit

1. Laden Sie den Cloud SQL Auth-Proxy herunter:

   curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.2/cloud-sql-proxy.linux.amd64
   

2. Machen Sie den Cloud SQL Auth-Proxy ausführbar:

   chmod +x cloud-sql-proxy
   

Linux 32-Bit

1. Laden Sie den Cloud SQL Auth-Proxy herunter:

   curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.2/cloud-sql-proxy.linux.386
   

2. Wenn der Befehl curl nicht gefunden wird, führen Sie sudo apt install curl aus und wiederholen Sie den Downloadbefehl.
3. Machen Sie den Cloud SQL Auth-Proxy ausführbar:

   chmod +x cloud-sql-proxy
   

macOS 64-Bit

1. Laden Sie den Cloud SQL Auth-Proxy herunter:

   curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.2/cloud-sql-proxy.darwin.amd64
   

2. Machen Sie den Cloud SQL Auth-Proxy ausführbar:

   chmod +x cloud-sql-proxy
   

Mac M1

1. Laden Sie den Cloud SQL Auth-Proxy herunter:

     curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.2/cloud-sql-proxy.darwin.arm64
     

2. Machen Sie den Cloud SQL Auth-Proxy ausführbar:

     chmod +x cloud-sql-proxy
     

Windows 64-Bit

Klicken Sie mit der rechten Maustaste auf https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.2/cloud-sql-proxy.x64.exe und wählen Sie Link speichern unter aus, um den Cloud SQL Auth-Proxy herunterzuladen. Benennen Sie die Datei in cloud-sql-proxy.exe um.

Windows 32-Bit

Klicken Sie mit der rechten Maustaste auf https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.2/cloud-sql-proxy.x86.exe und wählen Sie Link speichern unter aus, um den Cloud SQL Auth-Proxy herunterzuladen. Benennen Sie die Datei in cloud-sql-proxy.exe um.

Docker-Image des Cloud SQL Auth-Proxys

Der Cloud SQL Auth-Proxy hat verschiedene Container-Images, z. B. distroless, alpine und buster. Das standardmäßige Cloud SQL Auth-Proxy-Container-Image verwendet distroless, das keine Shell enthält. Wenn Sie eine Shell oder verwandte Tools benötigen, laden Sie ein auf alpine oder buster basierendes Image herunter. Weitere Informationen finden Sie unter Container-Images von Cloud SQL Auth-Proxy.

Sie können das neueste Image mithilfe von Docker mit dem folgenden Befehl auf Ihren lokalen Computer übertragen:

docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.2

Hinweis: Der Cloud SQL Auth-Proxy verwendet ein Repository, das die Domain gcr.io unterstützt, aber Images aus Artifact Registry bereitstellt. Weitere Informationen finden Sie unter Von Container Registry wechseln.

Andere Betriebssysteme

Für andere Betriebssysteme, die hier nicht aufgeführt sind, können Sie den Cloud SQL Auth-Proxy aus der Quelle kompilieren.

Cloud SQL Auth-Proxy starten

Je nach verwendeter Programmiersprache und Umgebung können Sie den Cloud SQL Auth-Proxy entweder mit TCP-Sockets, mit Unix-Sockets oder mit dem Cloud SQL Auth-Docker-Proxy-Image starten. Das Cloud SQL Auth-Proxy-Binärprogramm stellt eine Verbindung zu einer oder mehreren Cloud SQL-Instanzen her, die in der Befehlszeile angegeben sind, und öffnet eine lokale Verbindung als TCP- oder Unix-Socket. Andere Anwendungen und Dienste, z. B. Ihre Anwendungscode- oder Datenbankverwaltungs-Clienttools, können über diese TCP- oder Unix-Socket-Verbindungen eine Verbindung zu Cloud SQL-Instanzen herstellen.

Warnung: Seien Sie vorsichtig, wenn Sie den Cloud SQL-Auth-Proxy an eine externe Schnittstelle binden. Jeder mit Zugriff auf die Schnittstelle/den Port ist dann berechtigt, eine Verbindung zu Ihrer Instanz herzustellen.

TCP-Sockets

Bei TCP-Verbindungen beobachtet der Cloud SQL Auth-Proxy standardmäßig localhost(127.0.0.1). Wenn Sie also --port PORT_NUMBER für eine Instanz angeben, befindet sich die lokale Verbindung auf 127.0.0.1:PORT_NUMBER.

Alternativ können Sie eine andere Adresse für die lokale Verbindung angeben. So können Sie zum Beispiel den Cloud SQL-Auth-Proxy dazu bringen, die lokale Verbindung auf 0.0.0.0:1234 zu beobachten:

./cloud-sql-proxy --address 0.0.0.0 --port 1234 INSTANCE_CONNECTION_NAME

1. Kopieren Sie Ihren INSTANCE_CONNECTION_NAME. Sie finden ihn in der Google Cloud Console auf der Seite Übersicht für Ihre Instanz oder über den folgenden Befehl:

       gcloud sql instances describe INSTANCE_NAME --format='value(connectionName)'

   .

   Beispiel: myproject:myregion:myinstance.

2. Wenn für die Instanz sowohl eine öffentliche als auch eine private IP-Adresse konfiguriert ist und der Cloud SQL Auth-Proxy die private IP-Adresse verwenden soll, müssen Sie beim Starten des Cloud SQL Auth-Proxys folgende Option angeben:

   --private-ip

3. Wenn Sie ein Dienstkonto zur Authentifizierung des Cloud SQL Auth-Proxys verwenden, notieren Sie den Speicherort der Datei mit dem privaten Schlüssel, die zusammen mit dem Dienstkonto erstellt wurde, auf Ihrem Clientcomputer.
4. Starten Sie den Cloud SQL Auth-Proxy.

   Einige mögliche Strings zum Aufrufen des Cloud SQL Auth-Proxys:

   • Mit Cloud SDK-Authentifizierung:

     ./cloud-sql-proxy --port 5432 INSTANCE_CONNECTION_NAME
     

     Der angegebene Port darf nicht belegt sein (etwa durch einen lokalen Datenbankserver).
   • Mit einem Dienstkonto und unter expliziter Angabe des Namens der Instanzverbindung (empfohlen für Produktionsumgebungen):

     ./cloud-sql-proxy \
     --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &
     
     

   Weitere Informationen über Cloud SQL Auth-Proxyoptionen finden Sie unter Authentifizierungsoptionen für den Cloud SQL Auth-Proxy sowie Spezifikationsoptionen für Instanzen.

Unix-Sockets

Hinweis: Der Cloud SQL Auth-Proxy unterstützt derzeit keine Unix-Sockets unter Windows, daher ist diese Option nur für Linux- und macOS-Plattformen verfügbar.

Der Cloud SQL Auth-Proxy kann einen Unix-Socket beobachten. Dies ist ein POSIX-Standardverfahren für die Verwendung eines Ordners zur Verwaltung der Kommunikation zwischen zwei Prozessen, die auf demselben Host ausgeführt werden. Vorteile der Verwendung von Unix-Sockets sind höhere Sicherheit und geringere Latenz. Sie können jedoch nicht von einem externen Computer aus auf einen Unix-Socket zugreifen.

Hinweis: Für den PostgreSQL-Standard ist das Suffix „.s.PGSQL.5432“ im Socket-Pfad erforderlich. Einige Bibliotheken wenden dieses Suffix automatisch an, bei anderen müssen Sie den Socket-Pfad jedoch so angeben: .

  /cloudsql/INSTANCE_CONNECTION_NAME/.s.PGSQL.5432
  

Zum Erstellen und Verwenden eines Unix-Sockets muss das Zielverzeichnis vorhanden sein und sowohl der Cloud SQL Auth-Proxy als auch die Anwendung müssen Lese- und Schreibzugriff darauf haben.

1. Wenn Sie eine explizite Instanzspezifikation verwenden, kopieren Sie Ihren INSTANCE_CONNECTION_NAME. Sie finden ihn auf der Seite Übersicht Ihrer Instanz in der Google Cloud Console oder ermitteln ihn über folgenden Befehl:

   gcloud sql instances describe INSTANCE_NAME  --format='value(connectionName)'

   Beispiel: myproject:myregion:myinstance.

2. Erstellen Sie das Verzeichnis für die Cloud SQL Auth-Proxy-Sockets:

   sudo mkdir /cloudsql; sudo chmod 777 /cloudsql

3. Wenn Sie ein Dienstkonto zur Authentifizierung des Cloud SQL Auth-Proxys verwenden, notieren Sie den Speicherort der Datei mit dem privaten Schlüssel, die zusammen mit dem Dienstkonto erstellt wurde, auf Ihrem Clientcomputer.
4. Öffnen Sie ein neues Cloud Shell-Terminalfenster und starten Sie den Cloud SQL Auth-Proxy.

   Einige mögliche Strings zum Aufrufen des Cloud SQL Auth-Proxys:

   • Mit einem Dienstkonto und unter expliziter Angabe des Namens der Instanzverbindung (empfohlen für Produktionsumgebungen):

     ./cloud-sql-proxy --unix-socket /cloudsql
     --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &

   • Mit Cloud SDK-Authentifizierung und automatischer Instanzerkennung:

     ./cloud-sql-proxy --unix-socket /cloudsql &

   Starten Sie den Cloud SQL Auth-Proxy in einem eigenen Cloud Shell-Terminal. So können Sie seine Ausgabe beobachten, ohne dass sie mit der Ausgabe anderer Programme vermischt wird.

   Weitere Informationen über Cloud SQL Auth-Proxyoptionen finden Sie unter Authentifizierungsoptionen für den Cloud SQL Auth-Proxy sowie Spezifikationsoptionen für Instanzen.

HINWEIS: Wenn Sie mit einem Unix-Socket eine Verbindung zu Cloud SQL über den Cloud SQL Auth-Proxy herstellen, darf die Länge des Socket-Dateinamens das Limit des Systems nicht überschreiten. Dieses Limit hängt vom System ab, liegt aber in der Regel zwischen 91 und 108 Zeichen. Unter Linux beträgt die maximale Länge normalerweise 108 Zeichen. Mit folgendem Befehl können Sie die Länge prüfen:

cat /usr/include/linux/un.h | grep "define UNIX_PATH_MAX"

Docker

Verwenden Sie zum Ausführen des Cloud SQL Auth-Proxys in einem Docker-Container das Cloud SQL Auth-Proxy-Docker-Image, das in der Google Container Registry verfügbar ist.

Sie können den Cloud SQL Auth-Proxy entweder mit TCP-Sockets oder mit Unix-Sockets starten. Dafür werden die folgenden Befehle verwendet. Die Optionen verwenden einen INSTANCE_CONNECTION_NAME als Verbindungsstring, um eine Cloud SQL-Instanz zu identifizieren. Sie finden den INSTANCE_CONNECTION_NAME auf der Seite Übersicht Ihrer Instanz in der Google Cloud Console oder ermitteln ihn über folgenden Befehl:

gcloud sql instances describe INSTANCE_NAME

.

Beispiel: myproject:myregion:myinstance.

Hinweis: Der Cloud SQL Auth-Proxy unterstützt keine Beobachtung von Unix-Domain-Sockets unter Windows.

Je nach Ihrer Programmiersprache und Umgebung können Sie den Cloud SQL Auth-Proxy entweder mit TCP-Sockets oder mit Unix-Sockets starten. Allerdings werden Unix-Sockets nicht für Anwendungen unterstützt, die in der Programmiersprache Java oder für die Windows-Umgebung geschrieben sind.

TCP-Sockets verwenden

docker run -d \\
  -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \\
  -p 127.0.0.1:5432:5432 \\
  gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.2 \\
  --address 0.0.0.0 --port 5432 \\
  --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME

Wenn Sie die von Ihrer Compute Engine-Instanz bereitgestellten Anmeldedaten verwenden, geben Sie den Parameter --credentials-file und die Zeile -v PATH_TO_KEY_FILE:/path/to/service-account-key.json nicht an.

Geben Sie in -p immer das Präfix 127.0.0.1 an, damit der Cloud SQL Auth-Proxy nicht außerhalb des lokalen Hosts bereitgestellt wird. Die Angabe "0.0.0.0" im Instanzparameter ist erforderlich, damit von außerhalb des Docker-Containers auf den Port zugegriffen werden kann.

Unix-Sockets verwenden

docker run -d -v /cloudsql:/cloudsql \\
  -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \\
  gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.2 --unix-socket=/cloudsql \\
  --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME

Wenn Sie die von Ihrer Compute Engine-Instanz bereitgestellten Anmeldedaten verwenden, geben Sie den Parameter --credentials-file und die Zeile -v PATH_TO_KEY_FILE:/path/to/service-account-key.json nicht an.

Wenn Sie ein containeroptimiertes Image verwenden, ersetzen Sie /cloudsql durch ein beschreibbares Verzeichnis. Beispiel:

-v /mnt/stateful_partition/cloudsql:/cloudsql

Sie können mehrere durch Kommas getrennte Instanzen angeben. Außerdem haben Sie die Möglichkeit, mithilfe von Compute Engine-Metadaten dynamisch die Instanzen zu bestimmen, zu denen eine Verbindung hergestellt werden soll. Weitere Informationen zu Cloud SQL Auth-Proxy-Parametern.

Verbindung mit dem psql-Client herstellen

Debian/Ubuntu

Installieren Sie den psql-Client aus dem Paketmanager:

sudo apt-get update
sudo apt-get install postgresql-client

CentOS/RHEL

Installieren Sie den psql-Client aus dem Paketmanager:

sudo yum install postgresql

openSUSE

Installieren Sie den psql-Client aus dem Paketmanager:

sudo zypper install postgresql

Andere Plattformen

1. Laden Sie die PostgreSQL Core Distribution für Ihre Plattform von der PostgreSQL-Downloadseite herunter.
   Der psql-Client ist in der Core Distribution enthalten.
2. Installieren Sie die PostgreSQL-Datenbank nach den Anweisungen auf der Downloadseite.

Der verwendete Verbindungsstring hängt davon ab, ob Sie den Cloud SQL Auth-Proxy mit einem TCP-Socket, einem UNIX-Socket oder einem Docker gestartet haben.

TCP-Sockets

1. Starten Sie den psql-Client:

   psql "host=127.0.0.1 sslmode=disable dbname=DB_NAME user=USERNAME"
   

   Obwohl der Parameter sslmode auf disable gesetzt ist, stellt der Cloud SQL Auth-Proxy eine verschlüsselte Verbindung her.

   Wenn Sie die Verbindung mithilfe von TCP-Sockets herstellen, greifen Sie über 127.0.0.1 auf den Cloud SQL Auth-Proxy zu.

2. Geben Sie das Passwort ein, wenn Sie dazu aufgefordert werden.
3. Die psql-Eingabeaufforderung wird angezeigt.

Unix-Sockets verwenden

1. Starten Sie den psql-Client:

   psql "sslmode=disable host=/cloudsql/INSTANCE_CONNECTION_NAME dbname=DB_NAME user=USERNAME"
   

   Obwohl der Parameter sslmode auf disable gesetzt ist, stellt der Cloud SQL Auth-Proxy eine verschlüsselte Verbindung her.

2. Geben Sie das Passwort ein.
3. Die psql-Eingabeaufforderung wird angezeigt.

Benötigen Sie Hilfe? Informationen zur Fehlerbehebung für den Proxy finden Sie unter Fehlerbehebung bei Cloud SQL Auth-Proxyverbindungen oder auf der Seite Cloud SQL-Support.

Verbindung mit einer Anwendung herstellen

Sie können eine Verbindung zum Cloud SQL Auth-Proxy mit jeder Sprache herstellen, die eine Verbindung zu Unix- oder TCP-Sockets ermöglicht. Im Folgenden finden Sie einige Code-Snippets aus vollständigen Beispielen auf GitHub, die das Zusammenwirken in der Anwendung veranschaulichen.

Verbindung mit TCP herstellen

Anweisung zum Aufrufen des Cloud SQL Auth-Proxys:

./cloud-sql-proxy INSTANCE_CONNECTION_NAME &

Python

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

import os
import ssl

import sqlalchemy

def connect_tcp_socket() -> sqlalchemy.engine.base.Engine:
    """Initializes a TCP connection pool for a Cloud SQL instance of Postgres."""
    # 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.
    db_host = os.environ[
        "INSTANCE_HOST"
    ]  # e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
    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'
    db_port = os.environ["DB_PORT"]  # e.g. 5432

    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # postgresql+pg8000://<db_user>:<db_pass>@<db_host>:<db_port>/<db_name>
        sqlalchemy.engine.url.URL.create(
            drivername="postgresql+pg8000",
            username=db_user,
            password=db_pass,
            host=db_host,
            port=db_port,
            database=db_name,
        ),
        # ...
    )
    return pool

Java

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

Hinweis:

• CLOUD_SQL_CONNECTION_NAME sollte als <MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME> dargestellt werden.
• Die Verwendung des Arguments ipTypes=PRIVATE erzwingt, dass die SocketFactory eine Verbindung zur zugeordneten privaten IP-Adresse einer Instanz herstellen kann.
• Die Anforderungen für die JDBC Socket Factory-Version der pom.xml-Datei finden Sie hier.

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;

public class TcpConnectionPoolFactory 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 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");

  private static final String INSTANCE_HOST = System.getenv("INSTANCE_HOST");
  private static final String DB_PORT = System.getenv("DB_PORT");

  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://<INSTANCE_HOST>:<DB_PORT>/<DB_NAME>?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:%s/%s", INSTANCE_HOST, DB_PORT, DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", "postgres"
    config.setPassword(DB_PASS); // e.g. "my-password"

    // ... Specify additional connection properties here.
    // ...

    // Initialize the connection pool using the configuration object.
    return new HikariDataSource(config);
  }
}

Node.js

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

const Knex = require('knex');
const fs = require('fs');

// createTcpPool initializes a TCP connection pool for a Cloud SQL
// instance of Postgres.
const createTcpPool = 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 dbConfig = {
    client: 'pg',
    connection: {
      host: process.env.INSTANCE_HOST, // e.g. '127.0.0.1'
      port: process.env.DB_PORT, // e.g. '5432'
      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);
};

Einfach loslegen (Go)

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

package cloudsql

import (
	"database/sql"
	"fmt"
	"log"
	"os"

	// Note: If connecting using the App Engine Flex Go runtime, use
	// "github.com/jackc/pgx/stdlib" instead, since v5 requires
	// Go modules which are not supported by App Engine Flex.
	_ "github.com/jackc/pgx/v5/stdlib"
)

// connectTCPSocket initializes a TCP connection pool for a Cloud SQL
// instance of Postgres.
func connectTCPSocket() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Fatal Error in connect_tcp.go: %s environment variable not set.", 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'
		dbTCPHost = mustGetenv("INSTANCE_HOST") // e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
		dbPort    = mustGetenv("DB_PORT")       // e.g. '5432'
		dbName    = mustGetenv("DB_NAME")       // e.g. 'my-database'
	)

	dbURI := fmt.Sprintf("host=%s user=%s password=%s port=%s database=%s",
		dbTCPHost, dbUser, dbPwd, dbPort, dbName)

	// dbPool is the pool of database connections.
	dbPool, err := sql.Open("pgx", dbURI)
	if err != nil {
		return nil, fmt.Errorf("sql.Open: %w", err)
	}

	// ...

	return dbPool, nil
}

C#

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

using Npgsql;
using System;

namespace CloudSql
{
    public class PostgreSqlTcp
    {
        public static NpgsqlConnectionStringBuilder NewPostgreSqlTCPConnectionString()
        {
            // Equivalent connection string:
            // "Uid=<DB_USER>;Pwd=<DB_PASS>;Host=<INSTANCE_HOST>;Database=<DB_NAME>;"
            var connectionString = new NpgsqlConnectionStringBuilder()
            {
                // 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.
                Host = Environment.GetEnvironmentVariable("INSTANCE_HOST"),     // e.g. '127.0.0.1'
                // Set Host to 'cloudsql' when deploying to App Engine Flexible environment
                Username = Environment.GetEnvironmentVariable("DB_USER"), // e.g. 'my-db-user'
                Password = Environment.GetEnvironmentVariable("DB_PASS"), // e.g. 'my-db-password'
                Database = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'

                // The Cloud SQL proxy provides encryption between the proxy and instance.
                SslMode = SslMode.Disable,
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;
        }
    }
}

Ruby

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

tcp: &tcp
  adapter: postgresql
  # Configure additional properties here.
  # 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.
  username: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_development" } %>
  host: <%= ENV.fetch("INSTANCE_HOST") { "127.0.0.1" }%> # '172.17.0.1' if deployed to GAE Flex
  port: <%= ENV.fetch("DB_PORT") { 5432 }%>

PHP

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

namespace Google\Cloud\Samples\CloudSQL\Postgres;

use PDO;
use PDOException;
use RuntimeException;
use TypeError;

class DatabaseTcp
{
    public static function initTcpDatabaseConnection(): PDO
    {
        try {
            // 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.
            $username = getenv('DB_USER'); // e.g. 'your_db_user'
            $password = getenv('DB_PASS'); // e.g. 'your_db_password'
            $dbName = getenv('DB_NAME'); // e.g. 'your_db_name'
            $instanceHost = getenv('INSTANCE_HOST'); // e.g. '127.0.0.1' ('172.17.0.1' for GAE Flex)

            // Connect using TCP
            $dsn = sprintf('pgsql:dbname=%s;host=%s', $dbName, $instanceHost);

            // Connect to the database
            $conn = new PDO(
                $dsn,
                $username,
                $password,
                # ...
            );
        } catch (TypeError $e) {
            throw new RuntimeException(
                sprintf(
                    'Invalid or missing configuration! Make sure you have set ' .
                        '$username, $password, $dbName, and $instanceHost (for TCP mode). ' .
                        'The PHP error was %s',
                    $e->getMessage()
                ),
                $e->getCode(),
                $e
            );
        } catch (PDOException $e) {
            throw new RuntimeException(
                sprintf(
                    'Could not connect to the Cloud SQL Database. Check that ' .
                        'your username and password are correct, that the Cloud SQL ' .
                        'proxy is running, and that the database exists and is ready ' .
                        'for use. For more assistance, refer to %s. The PDO error was %s',
                    'https://cloud.google.com/sql/docs/postgres/connect-external-app',
                    $e->getMessage()
                ),
                $e->getCode(),
                $e
            );
        }

        return $conn;
    }
}

Verbindung mit Unix Domain Sockets herstellen

Anweisung zum Aufrufen des Cloud SQL Auth-Proxys:

./cloud-sql-proxy --unix-socket /cloudsql INSTANCE_CONNECTION_NAME &

Python

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

import os

import sqlalchemy

def connect_unix_socket() -> sqlalchemy.engine.base.Engine:
    """Initializes a Unix socket connection pool for a Cloud SQL instance of Postgres."""
    # 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.
    db_user = os.environ["DB_USER"]  # e.g. 'my-database-user'
    db_pass = os.environ["DB_PASS"]  # e.g. 'my-database-password'
    db_name = os.environ["DB_NAME"]  # e.g. 'my-database'
    unix_socket_path = os.environ[
        "INSTANCE_UNIX_SOCKET"
    ]  # e.g. '/cloudsql/project:region:instance'

    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # postgresql+pg8000://<db_user>:<db_pass>@/<db_name>
        #                         ?unix_sock=<INSTANCE_UNIX_SOCKET>/.s.PGSQL.5432
        # Note: Some drivers require the `unix_sock` query parameter to use a different key.
        # For example, 'psycopg2' uses the path set to `host` in order to connect successfully.
        sqlalchemy.engine.url.URL.create(
            drivername="postgresql+pg8000",
            username=db_user,
            password=db_pass,
            database=db_name,
            query={"unix_sock": f"{unix_socket_path}/.s.PGSQL.5432"},
        ),
        # ...
    )
    return pool

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

    // Unix sockets are not natively supported in Java, so it is necessary to use the Cloud SQL
    // Java Connector to connect. When setting INSTANCE_UNIX_SOCKET, the connector will
    // call an external package that will enable Unix socket connections.
    // Note: For Java users, the Cloud SQL Java Connector can provide authenticated connections
    // which is usually preferable to using the Cloud SQL Proxy with Unix sockets.
    // See https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory for details.
    if (INSTANCE_UNIX_SOCKET != null) {
      config.addDataSourceProperty("unixSocketPath", INSTANCE_UNIX_SOCKET);
    }

    // ... Specify additional connection properties here.
    // ...

    // Initialize the connection pool using the configuration object.
    return new HikariDataSource(config);
  }
}

Node.js

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

const Knex = require('knex');

// createUnixSocketPool initializes a Unix socket connection pool for
// a Cloud SQL instance of Postgres.
const createUnixSocketPool = 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.
  return Knex({
    client: 'pg',
    connection: {
      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'
      host: process.env.INSTANCE_UNIX_SOCKET, // e.g. '/cloudsql/project:region:instance'
    },
    // ... Specify additional properties here.
    ...config,
  });
};

C#

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

using Npgsql;
using System;

namespace CloudSql
{
    public class PostgreSqlUnix
    {
        public static NpgsqlConnectionStringBuilder NewPostgreSqlUnixSocketConnectionString()
        {
            // Equivalent connection string:
            // "Server=<INSTANCE_UNIX_SOCKET>;Uid=<DB_USER>;Pwd=<DB_PASS>;Database=<DB_NAME>"
            var connectionString = new NpgsqlConnectionStringBuilder()
            {
                // The Cloud SQL proxy provides encryption between the proxy and instance.
                SslMode = SslMode.Disable,

                // 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.
                Host = Environment.GetEnvironmentVariable("INSTANCE_UNIX_SOCKET"), // e.g. '/cloudsql/project:region:instance'
                Username = Environment.GetEnvironmentVariable("DB_USER"), // e.g. 'my-db-user
                Password = Environment.GetEnvironmentVariable("DB_PASS"), // e.g. 'my-db-password'
                Database = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;
        }
    }
}

Einfach loslegen (Go)

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

package cloudsql

import (
	"database/sql"
	"fmt"
	"log"
	"os"

	// Note: If connecting using the App Engine Flex Go runtime, use
	// "github.com/jackc/pgx/stdlib" instead, since v5 requires
	// Go modules which are not supported by App Engine Flex.
	_ "github.com/jackc/pgx/v5/stdlib"
)

// connectUnixSocket initializes a Unix socket connection pool for
// a Cloud SQL instance of Postgres.
func connectUnixSocket() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Fatal Error in connect_unix.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'
		unixSocketPath = mustGetenv("INSTANCE_UNIX_SOCKET") // e.g. '/cloudsql/project:region:instance'
		dbName         = mustGetenv("DB_NAME")              // e.g. 'my-database'
	)

	dbURI := fmt.Sprintf("user=%s password=%s database=%s host=%s",
		dbUser, dbPwd, dbName, unixSocketPath)

	// dbPool is the pool of database connections.
	dbPool, err := sql.Open("pgx", dbURI)
	if err != nil {
		return nil, fmt.Errorf("sql.Open: %w", err)
	}

	// ...

	return dbPool, nil
}

Ruby

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

unix: &unix
  adapter: postgresql
  # Configure additional properties here.
  # 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.
  username: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_development" } %>
  # Specify the Unix socket path as host
  host: "<%= ENV["INSTANCE_UNIX_SOCKET"] %>"

PHP

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

namespace Google\Cloud\Samples\CloudSQL\Postgres;

use PDO;
use PDOException;
use RuntimeException;
use TypeError;

class DatabaseUnix
{
    public static function initUnixDatabaseConnection(): PDO
    {
        try {
            // 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.
            $username = getenv('DB_USER'); // e.g. 'your_db_user'
            $password = getenv('DB_PASS'); // e.g. 'your_db_password'
            $dbName = getenv('DB_NAME'); // e.g. 'your_db_name'
            $instanceUnixSocket = getenv('INSTANCE_UNIX_SOCKET'); // e.g. '/cloudsql/project:region:instance'

            // Connect using UNIX sockets
            $dsn = sprintf(
                'pgsql:dbname=%s;host=%s',
                $dbName,
                $instanceUnixSocket
            );

            // Connect to the database.
            $conn = new PDO(
                $dsn,
                $username,
                $password,
                # ...
            );
        } catch (TypeError $e) {
            throw new RuntimeException(
                sprintf(
                    'Invalid or missing configuration! Make sure you have set ' .
                        '$username, $password, $dbName, ' .
                        'and $instanceUnixSocket (for UNIX socket mode). ' .
                        'The PHP error was %s',
                    $e->getMessage()
                ),
                (int) $e->getCode(),
                $e
            );
        } catch (PDOException $e) {
            throw new RuntimeException(
                sprintf(
                    'Could not connect to the Cloud SQL Database. Check that ' .
                        'your username and password are correct, that the Cloud SQL ' .
                        'proxy is running, and that the database exists and is ready ' .
                        'for use. For more assistance, refer to %s. The PDO error was %s',
                    'https://cloud.google.com/sql/docs/postgres/connect-external-app',
                    $e->getMessage()
                ),
                (int) $e->getCode(),
                $e
            );
        }

        return $conn;
    }
}

Weitere Informationen

Befehlszeilenargumente des Cloud SQL Auth-Proxys

Die obigen Beispiele decken die häufigsten Anwendungsfälle ab. Der Cloud SQL Auth-Proxy bietet aber auch weitere Konfigurationsoptionen, die mit Befehlszeilenargumenten festgelegt werden können. Wenn Sie Hilfe zu Befehlszeilenargumenten benötigen, rufen Sie mit dem Flag --help die aktuelle Dokumentation auf:

./cloud-sql-proxy --help

Weitere Beispiele zur Verwendung der Befehlszeilenoptionen des Cloud SQL Auth-Proxys finden Sie in der README-Datei im Cloud SQL Auth-Proxy-GitHub-Repository.

Authentifizierungsoptionen für Cloud SQL Auth-Proxy

Wenn Sie den Cloud SQL Auth-Proxy authentifizieren, aktivieren Sie ihn für den Zugriff auf Google Cloud im Namen Ihrer Anwendung unter Verwendung einer Reihe von Google-Anmeldedaten. Dies geschieht unabhängig von der Authentifizierung eines Datenbanknutzers. Die Authentifizierung der IAM-Nutzerdatenbank ist in den Cloud SQL-Auth-Proxy integriert.

Alle diese Optionen verwenden einen INSTANCE_CONNECTION_NAME als Verbindungsstring, um eine Cloud SQL-Instanz zu identifizieren. Sie finden den INSTANCE_CONNECTION_NAME auf der Seite Übersicht Ihrer Instanz in der Google Cloud Console oder ermitteln ihn über folgenden Befehl:

gcloud sql instances describe --project PROJECT_ID INSTANCE_CONNECTION_NAME

Beispiel: gcloud sql instances describe --project myproject myinstance .

Einige dieser Optionen verwenden eine JSON-Datei mit Anmeldedaten, die den privaten RSA-Schlüssel für das Konto enthält. Eine Anleitung zum Erstellen einer JSON-Datei mit Anmeldedaten für ein Dienstkonto finden Sie unter Dienstkonto erstellen und Schlüsseldatei generieren.

Der Cloud SQL Auth-Proxy bietet abhängig von der Umgebung mehrere alternative Authentifizierungsoptionen. Der Cloud SQL Auth-Proxy prüft das Vorhandensein der folgenden Elemente in der unten angeführten Reihenfolge und verwendet das erste Element, das er findet, für die Authentifizierung:

1. Vom Flag credentials-file bereitgestellte Anmeldedaten

   Erstellen Sie mit einem Dienstkonto die zugehörige JSON-Datei, laden Sie sie herunter und setzen Sie das Flag --credentials-file auf den Pfad der Datei, wenn Sie den Cloud SQL Auth-Proxy starten. Das Dienstkonto muss die erforderlichen Berechtigungen für die Cloud SQL-Instanz haben.

   Wenn Sie diese Option in der Befehlszeile verwenden möchten, rufen Sie den Befehl cloud-sql-proxy auf, wobei das Flag --credentials-file auf den Pfad und den Dateinamen einer JSON-Anmeldedatendatei festgelegt ist. Der Pfad kann absolut oder relativ zum aktuellen Arbeitsverzeichnis sein. Beispiele:

   ./cloud-sql-proxy --credentials-file PATH_TO_KEY_FILE \
   INSTANCE_CONNECTION_NAME
     

   Eine ausführliche Anleitung zum Hinzufügen von IAM-Rollen zu einem Dienstkonto finden Sie unter Dienstkonten Rollen zuweisen.

   Weitere Informationen zu den von Cloud SQL unterstützten Rollen finden Sie unter IAM-Rollen für Cloud SQL.

2. Von einem Zugriffstoken bereitgestellte Anmeldedaten

   Erstellen Sie ein Zugriffstoken und rufen Sie den Befehl cloud-sql-proxy mit dem auf ein OAuth 2.0-Zugriffstoken gesetzten Flag --token auf. Beispiele:

   ./cloud-sql-proxy --token ACCESS_TOKEN \
   INSTANCE_CONNECTION_NAME
     

3. Von einer Umgebungsvariable bereitgestellte Anmeldedaten.

   Diese Option ähnelt der Verwendung des Flags --credentials-file, mit dem Unterschied, dass Sie die JSON-Anmeldedatendatei angeben, die Sie in der Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS festgelegt haben, anstatt das Befehlszeilenargument --credentials-file zu verwenden.

4. Anmeldedaten eines authentifizierten gcloud CLI-Clients.

   Wenn Sie die gcloud CLI installiert und sich mit Ihrem persönlichen Konto authentifiziert haben, kann der Cloud SQL Auth-Proxy dieselben Anmeldedaten verwenden. Diese Methode ist besonders hilfreich, um eine Entwicklungsumgebung einzurichten und auszuführen.

   Damit der Cloud SQL Auth-Proxy Ihre gcloud CLI-Anmeldedaten verwenden kann, authentifizieren Sie die gcloud CLI mit folgendem Befehl:

   gcloud auth application-default login

5. Zur Compute Engine-Instanz gehörende Anmeldedaten

   Wenn Sie eine Verbindung zu Cloud SQL von einer Compute Engine-Instanz herstellen, kann der Cloud SQL Auth-Proxy das Dienstkonto verwenden, das mit der Compute Engine-Instanz verknüpft ist. Wenn das Dienstkonto die erforderlichen Berechtigungen für die Cloud SQL-Instanz hat, wird der Cloud SQL Auth-Proxy erfolgreich authentifiziert.

   Wenn sich die Compute Engine-Instanz im selben Projekt wie die Cloud SQL-Instanz befindet, hat das standardmäßige Dienstkonto die erforderlichen Berechtigungen zur Authentifizierung des Cloud SQL Auth-Proxys. Wenn sich die beiden Instanzen in verschiedenen Projekten befinden, müssen Sie das Dienstkonto der Compute Engine-Instanz dem Projekt hinzufügen, das die Cloud SQL-Instanz enthält.

6. Standarddienstkonto der Umgebung

   Wenn der Cloud SQL Auth-Proxy keine Anmeldedaten an einem der zuvor erwähnten Orte finden kann, folgt er der Vorgehensweise, die unter Authentifizierung für Server-zu-Server-Produktionsanwendungen einrichten dokumentiert ist. Einige Umgebungen (z. B. Compute Engine, App Engine und andere) bieten ein Standarddienstkonto, mit dem sich Ihre Anwendung standardmäßig authentifizieren kann. Wenn Sie ein Standarddienstkonto verwenden, muss es die Berechtigungen enthalten, die unter Rollen und Berechtigungen aufgeführt sind. Weitere Informationen über den Google Cloud-Authentifizierungsansatz finden Sie unter Authentifizierung – Übersicht.

Dienstkonto erstellen

Wenn Sie eine Verbindung über Compute Engine herstellen, müssen Sie darauf achten, dass für Ihre VM der richtige Wert für scope festgelegt ist, um eine Verbindung über die Cloud SQL Admin API herzustellen.

Konfigurieren Sie das Dienstkonto mit einem der folgenden Zugriffsbereiche:

• https://www.googleapis.com/auth/sqlservice.admin
• https://www.googleapis.com/auth/cloud-platform

1. Rufen Sie in der Google Cloud Console die Seite Dienstkonten auf:

   Zur Seite „Dienstkonten“

2. Wählen Sie das Projekt aus, in dem sich die Cloud SQL-Instanz befindet.
3. Klicken Sie auf Dienstkonto erstellen.
4. Geben Sie im Feld Name des Dienstkontos einen Namen für das Dienstkonto ein.
5. Ändern Sie die Dienstkonto-ID in einen eindeutigen, leicht erkennbaren Wert und klicken Sie dann auf Erstellen und fortfahren.
6. Klicken Sie auf das Feld Rolle auswählen und wählen Sie eine der folgenden Rollen aus:
   • Cloud SQL > Cloud SQL-Client
   • Cloud SQL > Cloud SQL-Bearbeiter
   • Cloud SQL > Cloud SQL-Administrator
   Hinweis: Zum Erstellen eines Dienstkontos mit den erforderlichen Berechtigungen benötigen Sie die Berechtigung resourcemanager.projects.setIamPolicy. Diese Berechtigung ist in der Rolle des Projektinhabers, des Projekt-IAM-Administrators und des Organisationsadministrators enthalten.
   Außerdem muss die Cloud SQL Admin API aktiviert sein. Wenn Sie die Legacy-Projektrollen („Betrachter“, „Bearbeiter“, „Inhaber“) verwenden, muss das Dienstkonto mindestens die Rolle „Bearbeiter“ haben.
7. Klicken Sie auf Fertig, um das Erstellen des Dienstkontos abzuschließen.
8. Klicken Sie auf das Aktionsmenü für das neue Dienstkonto und wählen Sie Schlüssel verwalten aus.
9. Klicken Sie auf das Drop-down-Menü Schlüssel hinzufügen und dann auf Neuen Schlüssel erstellen.
10. Prüfen Sie, ob der Schlüsseltyp JSON ist, und klicken Sie dann auf Erstellen.

    Die Datei mit dem privaten Schlüssel wird auf Ihren Computer heruntergeladen. Sie können die Datei an einen anderen Speicherort verschieben. Bewahren Sie die Schlüsseldatei sicher auf.

Cloud SQL Auth-Proxy mit privater IP-Adresse verwenden

Wenn Sie eine Verbindung zu einer Cloud SQL-Instanz mithilfe einer privaten IP-Adresse herstellen möchten, muss sich der Cloud SQL Auth-Proxy auf einer Ressource befinden, die Zugriff auf dasselbe VPC-Netzwerk wie die Instanz hat.

Der Cloud SQL Auth-Proxy verwendet IP-Adressen, um eine Verbindung zu Ihrer Cloud SQL-Instanz herzustellen. Standardmäßig versucht der Cloud SQL Auth-Proxy eine Verbindung über eine öffentliche IPv4-Adresse herzustellen.

Wenn Ihre Cloud SQL-Instanz nur eine private IP-Adresse hat oder für die Instanz sowohl eine öffentliche als auch eine private IP konfiguriert ist und der Cloud SQL Auth-Proxy die private IP-Adresse verwenden soll, müssen Sie die folgende Option angeben, wenn Sie den Cloud SQL Auth-Proxy starten:

--private-ip

Cloud SQL Auth-Proxy mit Instanzen verwenden, für die Private Service Connect aktiviert ist

Sie können den Cloud SQL Auth-Proxy verwenden, um eine Verbindung zu einer Cloud SQL-Instanz mit aktiviertem Private Service Connect herzustellen.

Der Cloud SQL Auth-Proxy ist ein Connector, der einen sicheren Zugriff auf diese Instanz ermöglicht, ohne dass autorisierte Netzwerke erforderlich sind oder SSL konfiguriert werden muss.

Um Cloud SQL Auth-Proxy-Clientverbindungen zuzulassen, müssen Sie einen DNS-Eintrag einrichten, der dem empfohlenen DNS-Namen für die Instanz entspricht. Der DNS-Eintrag ist eine Zuordnung zwischen einer DNS-Ressource und einem Domainnamen.

Weitere Informationen zur Verwendung des Cloud SQL Auth-Proxys zum Herstellen einer Verbindung zu Instanzen mit aktiviertem Private Service Connect finden Sie unter Verbindung über den Cloud SQL Auth-Proxy herstellen.

Cloud SQL Auth-Proxy in einem separaten Prozess ausführen

Das Ausführen des Cloud SQL Auth-Proxys in einem separaten Cloud Shell-Terminal kann nützlich sein, um zu vermeiden, dass die Konsolenausgabe mit der Ausgabe anderer Programme vermischt wird. Verwenden Sie die unten dargestellte Syntax, um den Cloud SQL Auth-Proxy in einem separaten Prozess aufzurufen.

Linux

Verwenden Sie unter Linux oder macOS ein nachgestelltes & in der Befehlszeile, um den Cloud SQL Auth-Proxy in einem separaten Prozess zu starten:

./cloud-sql-proxy INSTANCE_CONNECTION_NAME
  --credentials-file PATH_TO_KEY_FILE &

Windows

Verwenden Sie in Windows PowerShell den Befehl Start-Process, um den Cloud SQL Auth-Proxy in einem separaten Prozess zu starten:

Start-Process --filepath "cloud-sql-proxy.exe"
  --ArgumentList "
  --credentials-file PATH_TO_KEY_FILEINSTANCE_CONNECTION_NAME"

Cloud SQL Auth-Proxy in einem Docker-Container ausführen

Verwenden Sie zum Ausführen des Cloud SQL Auth-Proxys in einem Docker-Container das Cloud SQL Auth-Proxy-Docker-Image, das in der Google Container Registry verfügbar ist. Sie können das Docker-Image des Cloud SQL Auth-Proxys mit diesem gcloud-Befehl installieren:

docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.2

Sie können den Cloud SQL Auth-Proxy entweder mit TCP-Sockets oder mit Unix-Sockets starten. Dafür werden die folgenden Befehle verwendet.

Hinweis: Allerdings werden Unix-Sockets nicht für Anwendungen unterstützt, die in der Programmiersprache Java oder für die Windows-Umgebung geschrieben sind.

TCP-Sockets

    docker run -d \
      -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \
      -p 127.0.0.1:5432:5432 \
      gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.2 \
      --address 0.0.0.0 \
      --credentials-file /path/to/service-account-key.json \
      INSTANCE_CONNECTION_NAME

Unix-Sockets

    docker run -d \
      -v /PATH_TO_HOST_TARGET:/PATH_TO_GUEST_TARGET \
      -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \
      gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.2 --unix-socket /cloudsql \
      --credentials-file /path/to/service-account-key.json/PATH_TO_KEY_FILE \
      INSTANCE_CONNECTION_NAME

Wenn Sie ein containeroptimiertes Image verwenden, ersetzen Sie /cloudsql durch ein beschreibbares Verzeichnis. Beispiel:

v /mnt/stateful_partition/cloudsql:/cloudsql

Wenn Sie die von Ihrer Compute Engine-Instanz bereitgestellten Anmeldedaten verwenden, geben Sie den Parameter credential_file und die Zeile -v PATH_TO_KEY_FILE:/path/to/service-account-key.json nicht an.

Cloud SQL Auth-Proxy als Dienst ausführen

Die Ausführung des Cloud SQL Auth-Proxys als Hintergrunddienst ist eine Option für lokale Entwicklungs- und Produktionsarbeitslasten. Wenn Sie in der Entwicklung auf Ihre Cloud SQL-Instanz zugreifen müssen, können Sie den Dienst im Hintergrund starten und beenden, wenn Sie fertig sind.

Der Cloud SQL Auth-Proxy bietet derzeit keine integrierte Unterstützung für die Ausführung als Windows-Dienst. Es können aber Drittanbieter-Dienstmanager verwendet werden, um ihn als Dienst auszuführen. Beispielsweise können Sie NSSM verwenden, um den Cloud SQL Auth-Proxy als Windows-Dienst zu konfigurieren. NSSM überwacht dann den Cloud SQL Auth-Proxy und startet ihn automatisch neu, wenn er nicht mehr reagiert. Weitere Informationen finden Sie in der NSSM-Dokumentation.

Hinweis: Wenn Sie den Cloud SQL Auth-Proxy als Dienst ausführen, beachten Sie, dass er für die Kommunikation mit Cloud SQL-Instanzen eine sichere Verbindung verwendet. Verbindungen von Ihrer Anwendung zum Cloud SQL Auth-Proxy werden aber nicht verschlüsselt. Daher müssen Sie darauf achten, dass nur vertrauenswürdige Nutzer auf die Adresse und auf den Port zugreifen können, den der Cloud SQL Auth-Proxy überwacht.

Verwendung des Cloud SQL Auth-Proxys erzwingen

Aktivieren Sie die Verwendung des Cloud SQL Auth-Proxys in Cloud SQL mit ConnectorEnforcement.

gcloud

Der folgende Befehl erzwingt die Verwendung von Cloud SQL-Connectors

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

Verwenden Sie die folgende Codezeile, um die Erzwingung zu deaktivieren: --connector-enforcement NOT_REQUIRED Das Update löst keinen Neustart aus.

REST Version 1

Der folgende Befehl erzwingt die Verwendung von Cloud SQL-Connectors

Ersetzen Sie dabei folgende Werte für die Anfragedaten:

• project-id: die Projekt-ID
• instance-id: Die Instanz-ID.

HTTP-Methode und URL:

PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

JSON-Text anfordern:

{
  "settings": {
    "connectorEnforcement": "REQUIRED"
  }
}

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

curl (Linux, macOS oder Cloud Shell)

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto in der gcloud CLI angemeldet haben. Dazu haben Sie gcloud init oder gcloud auth login ausgeführt oder die Cloud Shell genutzt, die Sie automatisch in der gcloud CLI anmeldet. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id"

PowerShell (Windows)

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto in der gcloud-Befehlszeile angemeldet haben. Dazu führen Sie gcloud init oder gcloud auth login aus. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id" | Select-Object -Expand Content

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

Verwenden Sie stattdessen "connectorEnforcement": "NOT_REQUIRED", um die Erzwingung zu deaktivieren. Das Update löst keinen Neustart aus.

REST v1beta4

Der folgende Befehl erzwingt die Verwendung von Cloud SQL-Connectors

Ersetzen Sie dabei folgende Werte für die Anfragedaten:

• project-id: die Projekt-ID
• instance-id: Die Instanz-ID.

HTTP-Methode und URL:

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

JSON-Text anfordern:

{
  "settings": {
    "connectorEnforcement": "REQUIRED"
  }
}

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

curl (Linux, macOS oder Cloud Shell)

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto in der gcloud CLI angemeldet haben. Dazu haben Sie gcloud init oder gcloud auth login ausgeführt oder die Cloud Shell genutzt, die Sie automatisch in der gcloud CLI anmeldet. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id"

PowerShell (Windows)

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto in der gcloud-Befehlszeile angemeldet haben. Dazu führen Sie gcloud init oder gcloud auth login aus. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id" | Select-Object -Expand Content

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

Verwenden Sie stattdessen "connectorEnforcement": "NOT_REQUIRED", um die Erzwingung zu deaktivieren. Das Update löst keinen Neustart aus.

Tipps für die Arbeit mit dem Cloud SQL Auth-Proxy

Cloud SQL Auth-Proxy aufrufen

Alle Beispiel-Proxyaufrufe starten den Cloud SQL Auth-Proxy im Hintergrund, wofür eine Meldung ausgegeben wird. Reservieren Sie das Cloud Shell-Terminal für den Cloud SQL-Auth-Proxy, damit die Ausgabe nicht mit der Ausgabe anderer Programme vermischt wird. Die Ausgabe des Cloud SQL-Auth-Proxys kann bei der Diagnose von Verbindungsproblemen hilfreich sein. Darum bietet es sich an, sie in einer Logdatei zu erfassen. Wenn Sie den Cloud SQL-Auth-Proxy nicht im Hintergrund starten, wird die Ausgabe an stdout übergeben, sofern sie nicht weitergeleitet wird.

Sie müssen /cloudsql nicht als Verzeichnis für die Cloud SQL-Auth-Proxy-Sockets verwenden. (Dieser Verzeichnisname wurde gewählt, um die Unterschiede zu App Engine-Verbindungsstrings so gering wie möglich zu halten.) Wenn Sie den Verzeichnisnamen ändern, halten Sie ihn so kurz wie möglich. Er ist Teil eines längeren Strings, der einer Längenbeschränkung durch das Betriebssystem unterliegt. Dieses Limit hängt vom System ab, liegt aber in der Regel zwischen 91 und 108 Zeichen. Unter Linux beträgt die maximale Länge normalerweise 108 Zeichen. Mit folgendem Befehl können Sie die Länge prüfen:

cat /usr/include/linux/un.h | grep "define UNIX_PATH_MAX"

Cloud SQL Auth-Proxy für das Herstellen von Verbindungen zu mehreren Instanzen verwenden

Sie können mithilfe eines lokalen Cloud SQL Auth-Proxy-Clients eine Verbindung zu mehreren Cloud SQL-Instanzen herstellen. Die Vorgehensweise hängt dabei davon ab, ob Sie Unix-Sockets oder TCP verwenden.

Unix-Sockets

Um den Cloud SQL Auth-Proxy mit mehreren Instanzen zu verbinden, geben Sie die Namen jeder Instanzverbindung als Argument an den Cloud SQL Auth-Proxy in einer durch Leerzeichen getrennten Liste an. Der Cloud SQL-Auth-Proxy stellt beim Start eine Verbindung zu jeder Instanz her.

Eine Verbindung zu den einzelnen Instanzen stellen Sie über den jeweiligen Socket im angegebenen Verzeichnis her.

Beispiele:

      ./cloud-sql-proxy --unix-socket /cloudsql \
      myProject:us-central1:myInstance myProject:us-central1:myInstance2 &
      psql -U myUser -h /cloudsql/myProject:us-central1:myInstance2
  

TCP-Sockets

Wenn Sie eine Verbindung zu TCP herstellen, geben Sie einen Port auf Ihrem Computer an, der vom Cloud SQL-Auth-Proxy auf jede Cloud SQL-Instanz überwacht werden soll. Wenn Sie eine Verbindung zu mehreren Cloud SQL-Instanzen herstellen, muss jeder angegebene Port eindeutig und auf Ihrem Computer verfügbar sein.

Beispiel:

    # Start the Cloud SQL Auth Proxy to connect to two different Cloud SQL instances
    # Give the Cloud SQL Auth Proxy a unique port on your machine to use for each Cloud SQL instance.

    ./cloud-sql-proxy "myProject:us-central1:myInstance?port=5432" \
    "myProject:us-central1:myInstance2?port=1234"

    # Connect to "myInstance" using port 5432 on your machine:
    psql -U myUser -h 127.0.0.1  --port 5432

    # Connect to "myInstance2" using port 1234 on your machine:
    psql -U myUser -h 127.0.0.1  --port 1234
  

Cloud SQL-Auth-Proxy-Aufrufe und psql-Client-Verbindungsstrings

Sie können Cloud SQL Auth-Proxy-Aufrufe und Verbindungsstrings verwenden, z. B. in Befehlen für einen PostgreSQL-Nutzer myUser und für die Instanz myInstance in der Region us-central1 im Projekt myProject.

Automatische Instanzerkennung mit gcloud CLI-Anmeldedaten verwenden:

    ./cloud-sql-proxy --unix-socket /cloudsql &
    psql -U myUser -h /cloudsql/myProject:us-central1:myInstance
 

Projekterkennung mit gcloud CLI-Anmeldedaten verwenden:

    ./cloud-sql-proxy --unix-socket /cloudsql &
    psql -U myUser -h /cloudsql/myProject:us-central1:myInstance

Für eine Compute Engine-Instanz mit expliziter Instanzspezifikation:

    ./cloud-sql-proxy --unix-socket /cloudsql myProject:us-central1:myInstance &
    psql -U myUser -h /cloudsql/myProject:us-central1:myInstance

Für Unix mit TCP:

    ./cloud-sql-proxy "myProject:us-central1:myInstance?port=5432" &
    psql -U myUser -h 127.0.0.1

Für Windows (in der Eingabeaufforderung):

    cloud-sql-proxy.exe "myProject:us-central1:myInstance?port=5432"
    psql -U myUser -h 127.0.0.1

Hinweis: 5432 ist der Standardport für den psql-Client. Bei einer anderen Portnummer ist es erforderlich, dass Sie diese beim Starten des psql-Clients mit dem Parameter --port angeben.

Weitere Informationen über die Cloud SQL Auth-Proxyoptionen finden Sie auf der GitHub-Seite zum Cloud SQL Auth-Proxy.

Fehlerbehebung bei Cloud SQL-Auth-Proxy-Verbindungen

Das Docker-Image des Cloud SQL Auth-Proxys basiert auf einer bestimmten Version des Cloud SQL Auth-Proxys. Wenn eine neue Version des Cloud SQL Auth-Proxys verfügbar ist, rufen Sie die neue Version des zugehörigen Docker-Image ab, damit Ihre Umgebung auf dem neuesten Stand ist. Die aktuelle Version des Cloud SQL Auth-Proxys finden Sie auf der GitHub-Seite mit Cloud SQL Auth-Proxyversionen.

Wenn Sie Probleme damit haben, über den Cloud SQL Auth-Proxy eine Verbindung mit der Cloud SQL-Instanz herzustellen, versuchen Sie Folgendes, um die Problemursache zu ermitteln.

• Prüfen Sie die Ausgabe des Cloud SQL Auth-Proxys.

  Die Ausgabe des Cloud SQL Auth-Proxys ist häufig hilfreich, um die Ursache des Problems zu ermitteln und um eine Lösung dafür zu finden. Leiten Sie die Ausgabe in eine Datei oder beobachten Sie das Cloud Shell-Terminal, in dem Sie den Cloud SQL Auth-Proxy gestartet haben.

• Wenn Sie den Fehler 403 notAuthorized erhalten und das Dienstkonto zum Authentifizieren des Cloud SQL Auth-Proxys verwenden, müssen Sie dafür sorgen, dass das Dienstkonto die richtigen Berechtigungen hat.

  Sie können das Dienstkonto überprüfen. Suchen Sie dazu auf der IAM-Seite nach seiner ID. Das Konto muss die Berechtigung cloudsql.instances.connect haben. Die vordefinierten Rollen Cloud SQL Admin, Client und Editor haben diese Berechtigung.

• Wenn Sie eine Verbindung von App Engine aus herstellen und einen 403 notAuthorized-Fehler erhalten, prüfen Sie den app.yaml-Wert cloud_sql_instances auf einen falsch geschriebenen oder falschen Instanzverbindungsnamen. Namen von Instanzverbindungen haben immer das Format PROJECT:REGION:INSTANCE.

  Überprüfen Sie außerdem, ob das App Engine-Dienstkonto (z. B. $[e-mail]) die Cloud SQL-Client-IAM-Rolle hat.

  Wenn sich der App Engine-Dienst in einem Projekt (Projekt A) und die Datenbank in einem anderen Projekt (Projekt B) befindet, weist dieser Fehler darauf hin, dass dem App Engine-Dienstkonto nicht die Cloud SQL-Client-IAM-Rolle zugewiesen wurde im Projekt mit der Datenbank (Projekt B)

• Achten Sie darauf, dass die Cloud SQL Admin API aktiviert ist.

  Ist dies nicht der Fall, wird in Ihren Cloud SQL-Proxy-Logs eine Meldung wie z. B. Error 403: Access Not Configured ausgegeben.

• Wenn Sie in der Instanzliste mehrere Instanzen angeben, achten Sie darauf, ein Komma als Trennzeichen zu verwenden. Wenn Sie TCP verwenden, geben Sie für alle Instanzen unterschiedliche Ports an.

• Wenn Sie eine Verbindung über UNIX-Sockets herstellen, prüfen Sie, ob die Sockets erstellt wurden. Rufen Sie dazu das Verzeichnis auf, das Sie beim Start des Cloud SQL Auth-Proxys angegeben haben.

• Wenn Sie eine Firewallrichtlinie für ausgehende Verbindungen haben, müssen Sie darauf achten, dass sie Verbindungen zu Port 3307 auf der Ziel-Cloud SQL-Instanz zulässt.

  Hinweis: Der Cloud SQL Auth-Proxy verwendet 3307, um eine Verbindung zum Cloud SQL Auth-Proxyserver herzustellen. Port 5432 ist der Standardport für das PostgreSQL Auth-Protokoll über eine direkte TCP-Verbindung (ohne Verwendung des Cloud SQL Auth-Proxys).

• Sie können prüfen, ob der Cloud SQL Auth-Proxy ordnungsgemäß gestartet wurde. Sehen Sie sich dazu in den Logs im Abschnitt Vorgänge > Logging > Log-Explorer der Google Cloud Console die Logs an. Ein erfolgreicher Vorgang sieht so aus:

  2021/06/14 15:47:56 Listening on /cloudsql/$PROJECT_ID:$REGION:$INSTANCE_NAME/5432 for $PROJECT_ID:$REGION:$INSTANCE_NAME
  2021/06/14 15:47:56 Ready for new connections
  

• Kontingentprobleme: Wenn das Kontingent für die Cloud SQL Admin API überschritten wird, wird der Cloud SQL Auth-Proxy mit der folgenden Fehlermeldung gestartet:

  There was a problem when parsing a instance configuration but ignoring due
  to the configuration. Error: googleapi: Error 429: Quota exceeded for quota
  metric 'Queries' and limit 'Queries per minute per user' of service
  'sqladmin.googleapis.com' for consumer 'project_number:$PROJECT_ID.,
  rateLimitExceeded
  

  Sobald eine Anwendung die Verbindung zum Proxy herstellt, meldet der Proxy den folgenden Fehler:

  failed to refresh the ephemeral certificate for $INSTANCE_CONNECTION_NAME:
  googleapi: Error 429: Quota exceeded for quota metric 'Queries' and limit
  'Queries per minute per user' of service 'sqladmin.googleapis.com' for
  consumer 'project_number:$PROJECT_ID., rateLimitExceeded
  

  Lösung: Identifizieren Sie entweder die Quelle des Kontingentproblems, z. B. wenn eine Anwendung den Connector missbraucht und unnötigerweise neue Verbindungen erstellt, oder wenden Sie sich an den Support, um eine Erhöhung des Cloud SQL Admin API-Kontingents zu beantragen. Wenn der Kontingentfehler beim Start angezeigt wird, müssen Sie die Anwendung noch einmal bereitstellen, um den Proxy neu zu starten. Wenn der Kontingentfehler nach dem Start angezeigt wird, ist eine erneute Bereitstellung nicht erforderlich.

Nächste Schritte

• Weitere Informationen zum Cloud SQL Auth-Proxy
• Identitäts- und Zugriffsverwaltung (IAM)
• Dienstkonten
• Die zwei Ebenen der Zugriffssteuerung für Cloud SQL-Instanzen.
• Nutzer erstellen und Datenbanken erstellen.
• Verbindung zwischen der Anwendung und der Instanz herstellen.
• Der psql-Client.
• Supportoptionen