Verbindung über den AlloyDB Auth-Proxy herstellen

Auf dieser Seite erfahren Sie, wie Sie den AlloyDB Auth-Proxy einrichten und verwenden, um autorisierte, verschlüsselte Verbindungen zu AlloyDB-Instanzen herzustellen. Eine konzeptionelle Übersicht über den Auth-Proxy finden Sie unter AlloyDB Auth-Proxy.

Wenn Sie den AlloyDB Auth-Proxy verwenden möchten, führen Sie einige einmalige Einrichtungsschritte aus, starten Sie den Auth-Proxy-Client und stellen Sie dann über ihn eine Verbindung zu Datenbanken her:

  1. Einrichtungsschritte:
    1. Laden Sie den Auth-Proxy-Client auf Ihren Clienthost herunter.
    2. Wählen Sie das IAM-Hauptkonto (Identity and Access Management) für die Autorisierung aus, prüfen Sie, ob es die erforderlichen Berechtigungen hat, und sorgen Sie dafür, dass die Anmeldedaten auf Ihrem Clienthost verfügbar sind.
    3. Erfassen Sie die Verbindungs-URIs für die AlloyDB-Instanzen, zu denen Sie eine Verbindung herstellen möchten.
  2. Starten Sie den Auth-Proxy-Client auf Ihrem Clienthost.
  3. Verbinden Sie eine Anwendung mit einer Datenbank, indem Sie eine lokale Verbindung zum Auth-Proxy-Client herstellen.

Hinweise

    Der Clienthost muss die folgenden Anforderungen erfüllen:

    • Es muss Netzwerksichtbarkeit für das Virtual Private Cloud-Netzwerk (VPC) haben, in dem sich die Instanzen befinden, mit denen Sie eine Verbindung herstellen möchten. Clienthosts (z. B. Compute Engine-Instanzen) in diesem VPC-Netzwerk (Virtual Private Cloud) haben diese Sichtbarkeit von Natur aus. Clienthosts in externen Netzwerken (lokalen Netzwerken oder anderen VPC-Netzwerken) haben diese Sichtbarkeit, wenn das VPC-Netzwerk der AlloyDB-Instanz über einen Cloud-VPN-Tunnel oder einen VLAN-Anhang für Dedicated Interconnect oder Partner Interconnect mit dem externen Netzwerk verbunden ist.

    • Wenn der Clienthost eine Firewallrichtlinie für ausgehende Verbindungen hat, muss sie ausgehende Verbindungen zu Port 5433 auf den IP-Adressen Ihrer AlloyDB-Instanzen und ausgehende Verbindungen zu Port 443 (dem Standard-HTTPS-Port) zu allen IP-Adressen zulassen.

    • Wenn Sie eine Compute Engine-Instanz als Clienthost verwenden, muss sie den Zugriffsbereich https://www.googleapis.com/auth/cloud-platform haben, damit sie die AlloyDB Admin API verwenden kann. Ändern Sie bei Bedarf den Zugriffsbereich, um diesen Bereich einzubeziehen.

Auth-Proxyclient herunterladen

Der Computer, auf den Sie den Auth-Proxy-Client herunterladen, hängt davon ab, ob Sie eine Verbindung zu Ihren AlloyDB-Instanzen von innerhalb oder außerhalb des VPC-Netzwerks herstellen möchten.

Wenn Sie eine Verbindung zu Ihrem Cluster über den Zugriff auf private Dienste herstellen möchten, können Sie den Auth-Proxy-Client auf eine Compute Engine-VM-Instanz herunterladen, die in dem VPC-Netzwerk ausgeführt wird, das Zugriff auf private Dienste für Ihren Cluster hat.

Wenn Sie eine Verbindung zu Ihrem Cluster von außerhalb der VPC herstellen möchten, hängt die Maschine, auf der Sie die Installation vornehmen, von der verwendeten Strategie für externe Verbindungen ab. Sie können den Auth-Proxy-Client beispielsweise auf einem macOS- oder Windows-Computer installieren, der lokal für Ihre Anwendung ist, und dann einen SOCKS-Server verwenden, der in Ihrem AlloyDB-VPC-Netzwerk ausgeführt wird, als Verbindungsvermittler. Weitere Informationen finden Sie unter Verbindung zu einem Cluster von außerhalb des VPC herstellen.

Linux

64-Bit (AMD)

  1. Laden Sie den Auth-Proxy-Client herunter:

    wget https://storage.googleapis.com/alloydb-auth-proxy/v1.12.2/alloydb-auth-proxy.linux.amd64 -O alloydb-auth-proxy

  2. Machen Sie den Auth-Proxyclient ausführbar:

    chmod +x alloydb-auth-proxy

32-Bit (AMD)

  1. Laden Sie den Auth-Proxy-Client herunter:

    wget https://storage.googleapis.com/alloydb-auth-proxy/v1.12.2/alloydb-auth-proxy.linux.386 -O alloydb-auth-proxy

  2. Machen Sie den Auth-Proxyclient ausführbar:

    chmod +x alloydb-auth-proxy

64-Bit (ARM)

  1. Laden Sie den Auth-Proxy-Client herunter:

    wget https://storage.googleapis.com/alloydb-auth-proxy/v1.12.2/alloydb-auth-proxy.linux.arm64 -O alloydb-auth-proxy

  2. Machen Sie den Auth-Proxyclient ausführbar:

    chmod +x alloydb-auth-proxy

32-Bit (ARM)

  1. Laden Sie den Auth-Proxy-Client herunter:

    wget https://storage.googleapis.com/alloydb-auth-proxy/v1.12.2/alloydb-auth-proxy.linux.arm -O alloydb-auth-proxy

  2. Machen Sie den Auth-Proxyclient ausführbar:

    chmod +x alloydb-auth-proxy

macOS

M1

  1. Laden Sie den Auth-Proxy-Client herunter:

    curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.12.2/alloydb-auth-proxy.darwin.arm64

  2. Machen Sie den Auth-Proxyclient ausführbar:

    chmod +x alloydb-auth-proxy

64-Bit

  1. Laden Sie den Auth-Proxy-Client herunter:

    curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.12.2/alloydb-auth-proxy.darwin.amd64

  2. Machen Sie den Auth-Proxyclient ausführbar:

    chmod +x alloydb-auth-proxy

32-Bit

  1. Laden Sie den Auth-Proxy-Client herunter:

    curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.12.2/alloydb-auth-proxy.darwin.386

  2. Machen Sie den Auth-Proxyclient ausführbar:

    chmod +x alloydb-auth-proxy

Windows

64-Bit

Klicken Sie mit der rechten Maustaste auf https://storage.googleapis.com/alloydb-auth-proxy/v1.12.2/alloydb-auth-proxy-x64.exe und wählen Sie Link speichern unter aus, um den Auth Proxy-Client herunterzuladen. Benennen Sie die Datei in alloydb-auth-proxy.exe um.

32-Bit

Klicken Sie mit der rechten Maustaste auf https://storage.googleapis.com/alloydb-auth-proxy/v1.12.2/alloydb-auth-proxy-x86.exe und wählen Sie Link speichern unter aus, um den Auth-Proxy-Client herunterzuladen. Benennen Sie die Datei in alloydb-auth-proxy.exe um.

Docker-Image

Der Einfachheit halber sind mehrere Container-Images, die den Auth-Proxy-Client enthalten, in der Container Registry verfügbar.

Mit folgendem Befehl können Sie das neueste Image mithilfe von Docker auf Ihren lokalen Computer übertragen:

docker pull gcr.io/alloydb-connectors/alloydb-auth-proxy:latest

Andere Betriebssysteme

Bei anderen Betriebssystemen, die hier nicht aufgeführt sind, können Sie den Auth-Proxy-Client aus der Quelle kompilieren.

IAM-Hauptkonto auswählen und für die Autorisierung vorbereiten

Der AlloyDB Auth-Proxy unterstützt die Verwendung dieser Arten von IAM-Principals, um Verbindungen zwischen Ihrem Client und einer AlloyDB-Instanz zu autorisieren:

  • Ein vom Nutzer verwaltetes Dienstkonto Sie können ein IAM-Dienstkonto für Ihre Anwendung erstellen und dann Verbindungen damit autorisieren.

    Google empfiehlt dringend, in Produktionsumgebungen ein Dienstkonto für die Autorisierung zu verwenden.

  • Ihr Nutzerkonto Sie können Verbindungen mit Ihrem eigenen IAM-Nutzerkonto autorisieren.

    Die Verwendung eines eigenen Nutzerkontos ist in Entwicklungsumgebungen praktisch, in denen Sie AlloyDB-Ressourcen mit der gcloud CLI verwalten, die Datenbank mit einem Tool wie psql entwickeln und Anwendungscode auf demselben Host entwickeln.

  • Das standardmäßige Compute Engine-Dienstkonto Wenn der Clienthost eine Compute Engine-Instanz ist, können Sie das Standarddienstkonto der Compute Engine verwenden, um Verbindungen zu autorisieren.

Nachdem Sie das zu verwendende IAM-Hauptkonto ausgewählt haben, müssen Sie dafür sorgen, dass es die erforderlichen IAM-Berechtigungen hat und dass seine Anmeldedaten auf Ihrem Clienthost verfügbar sind.

Erforderliche IAM-Berechtigungen

Das IAM-Hauptkonto, das Sie zum Autorisieren von Verbindungen verwenden, muss die Berechtigungen der vordefinierten Rollen roles/alloydb.client (Cloud AlloyDB-Client) und roles/serviceusage.serviceUsageConsumer (Nutzer der Servicenutzung) haben.

So weisen Sie einem IAM-Principal die Rolle „Cloud AlloyDB-Client“ zu:

  • Die Cloud Resource Manager API muss im Google Cloud-Projekt aktiviert sein.

  • Sie benötigen die grundlegende IAM-Rolle roles/owner (Inhaber) im Google Cloud-Projekt oder eine Rolle mit den folgenden Berechtigungen:

    • resourcemanager.projects.get
    • resourcemanager.projects.getIamPolicy
    • resourcemanager.projects.setIamPolicy

    Bitten Sie Ihren Administrator, Ihnen die Rolle roles/resourcemanager.projectIamAdmin (IAM-Administrator für das Projekt) zuzuweisen, damit Sie diese Berechtigungen erhalten und dabei dem Prinzip der geringsten Berechtigung folgen.

IAM-Anmeldedaten auf dem Clienthost verfügbar machen

Wie Sie IAM-Anmeldedaten auf dem Clienthost verfügbar machen, hängt davon ab, welchen Typ von IAM-Hauptkonto Sie für die Autorisierung von Verbindungen verwenden:

  • Nutzerverwaltetes Dienstkonto

    Wenn Sie IAM-Anmeldedaten für ein nutzerverwaltetes Dienstkonto angeben möchten, erstellen Sie einen Dienstkontoschlüssel im JSON-Format und laden Sie ihn auf Ihren Clienthost herunter. Geben Sie beim Starten des Auth Proxy-Clients den Speicherort der Schlüsseldatei mit dem Flag --credentials-file an.

  • Ihr Nutzerkonto

    Wenn Sie IAM-Anmeldedaten für Ihr Nutzerkonto angeben möchten, installieren Sie die Google Cloud CLI auf Ihrem Clienthost und führen Sie den Befehl gcloud init aus, um sie mit Ihrem Nutzerkonto zu initialisieren. Wenn Sie den Auth-Proxy-Client starten, werden Ihre Nutzerkonto-Anmeldedaten automatisch erkannt und verwendet, wenn Sie keine nutzerverwalteten Dienstkonto-Anmeldedaten angeben.

  • Standardmäßiges Compute Engine-Dienstkonto

    Wenn Sie eine Compute Engine-Instanz als Clienthost verwenden, sind die Anmeldedaten für das Standarddienstkonto der Compute Engine bereits auf dem Host vorhanden. Wenn Sie den Auth Proxy-Client starten, werden diese Anmeldedaten automatisch erkannt und verwendet, wenn keine vom Nutzer verwalteten Anmeldedaten für Dienst- und Nutzerkonten verfügbar sind.

Verbindungs-URIs für die AlloyDB-Instanzen erfassen

Wenn Sie den Auth-Proxy-Client starten, geben Sie die AlloyDB-Instanz oder ‑Instanzen an, mit denen Sie eine Verbindung herstellen möchten. Verwenden Sie dazu das folgende Format für den Verbindungs-URI:

projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

Verwenden Sie den Befehl alloydb instances list der gcloud CLI, um eine Liste der Verbindungs-URIs aller Instanzen aufzurufen.

Erfassen Sie den URI der Instanzverbindung für jede Instanz, zu der Sie eine Verbindung herstellen möchten.

Auth-Proxy-Client starten

Wenn Sie den Auth-Proxy-Client starten, geben Sie Informationen dazu an, mit welchen AlloyDB-Instanzen eine Verbindung hergestellt werden soll, und gegebenenfalls Anmeldedaten, die bei der Autorisierung dieser Verbindungen verwendet werden sollen.

Beim Starten führt der Auth-Proxy-Client folgende Schritte aus:

  • Autorisiert Verbindungen zu AlloyDB-Instanzen mit den Anmeldedaten und IAM-Berechtigungen des von Ihnen konfigurierten IAM-Principals. Dabei wird eine bestimmte Abfolge von Schritten ausgeführt.
  • Autorisiert öffentliche IP-Verbindungen zum Quellnetzwerk automatisch, wenn für die Instanz die öffentliche IP-Adresse aktiviert ist.
  • Konfiguriert eine private TLS 1.3-Verbindung zum Auth-Proxy-Server jeder Instanz.
  • Es wird damit begonnen, auf lokale Clientverbindungsanfragen zu warten.

Standardmäßig wartet der Auth-Proxy-Client auf TCP-Verbindungen an der IP-Adresse 127.0.0.1, beginnend bei Port 5432 und mit einer Erhöhung der Portnummer um eins für jede AlloyDB-Instanz nach der ersten. Sie können beim Starten des Auth-Proxy-Clients eine andere Listeneradresse und andere Ports angeben.

Befehlszeile

./alloydb-auth-proxy INSTANCE_URI... \
    [ --credentials-file PATH_TO_KEY_FILE \ ]
    [ --token OAUTH_ACCESS_TOKEN \ ]
    [ --port INITIAL_PORT_NUMBER \ ]
    [ --address LOCAL_LISTENER_ADDRESS \ ]
    [ --auto-iam-authn ] \
    [ --psc] \
    [ --public-ip]

Ersetzen Sie Folgendes:

  • INSTANCE_URI: der Instanzverbindungs-URI einer AlloyDB-Instanz, mit der eine Verbindung hergestellt werden soll, im folgenden Format:

    projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

    Sie können den Standard-lokalen Listener-Port, den der Auth-Proxy-Client für die Instanz verwendet, überschreiben, indem Sie dem URI den Abfrageparameter port hinzufügen:

    "projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID?port=PORT"

  • Optional: PATH_TO_KEY_FILE: Der Pfad zur JSON-Schlüsseldatei des nutzerverwalteten Dienstkontos, das für die Verbindungsautorisierung verwendet werden soll.

  • Optional: OAUTH_ACCESS_TOKEN: Ein OAuth2-Tokenwert, der für die Verbindungsautorisierung verwendet werden soll.

  • Optional: INITIAL_PORT_NUMBER: Die Startportnummer, die anstelle des Standardports 5432 verwendet werden soll, wenn auf lokale TCP-Verbindungen gewartet wird.

  • Optional: LOCAL_LISTENER_ADDRESS: Die Listeneradresse, die anstelle der Standardadresse 127.0.0.1 verwendet werden soll, wenn auf lokale TCP-Verbindungen gewartet wird.

Mit dem optionalen Flag --auto-iam-authn wird die automatische Authentifizierung bei der Instanz ermöglicht. Dies funktioniert nur für den Datenbanknutzer, der mit dem IAM-Konto verknüpft ist, auf dem der Auth-Proxy-Client ausgeführt wird. Weitere Informationen finden Sie unter Automatische Authentifizierung über den Auth-Proxy.

Mit dem optionalen Flag --psc kann der Auth-Proxy eine Verbindung zu einer Instanz herstellen, für die Private Service Connect aktiviert ist. Weitere Informationen zum Einrichten von DNS mit Private Service Connect finden Sie unter Eine verwaltete DNS-Zone und einen DNS-Eintrag konfigurieren.

Mit dem optionalen Flag --public-ip kann der Auth-Proxy über die öffentliche IP-Adresse einer Instanz eine Verbindung zu einer Instanz herstellen, für die eine öffentliche IP-Adresse aktiviert ist. Weitere Informationen zu öffentlichen IP-Adressen finden Sie unter Verbindung über öffentliche IP-Adresse herstellen.

Docker-Container

Starten Sie den Auth-Proxy-Client mit dem Befehl docker run.

Wenn Sie die von Ihrer Compute Engine-Instanz bereitgestellten Anmeldedaten verwenden, können Sie einen Befehl wie den folgenden verwenden:

docker run \
  --publish 127.0.0.1:PORT:PORT \
  gcr.io/alloydb-connectors/alloydb-auth-proxy:latest \
  --address 0.0.0.0 \
  --port PORT \
  INSTANCE_URI

Ersetzen Sie Folgendes:

  • PORT: Der Port, der für lokale Verbindungen zum Auth-Proxy-Client verwendet werden soll. Der Standardwert ist 5432.

  • INSTANCE_URI: Der Instanzverbindungs-URI einer AlloyDB-Instanz, mit der eine Verbindung hergestellt werden soll. Er muss im folgenden Format angegeben werden:

    projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

    Sie können den Standard-lokalen Listener-Port, den der Auth-Proxy-Client für die Instanz verwendet, überschreiben, indem Sie dem URI den Abfrageparameter port hinzufügen:

    "projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID?port=PORT"

Geben Sie in --publish immer das Präfix 127.0.0.1 an, damit der Auth-Proxy-Client nicht außerhalb des lokalen Hosts bereitgestellt wird.

Der Wert 0.0.0.0 im Flag --address ist erforderlich, damit der Listener von außerhalb des Docker-Containers zugänglich ist.

Wenn Sie Anmeldedaten angeben möchten, die Sie in einer lokalen JSON-Datei gespeichert haben, fügen Sie beim Ausführen des Befehls docker run die Flags --volume und --credentials-file hinzu:

docker run \
  --volume PATH_TO_KEY_FILE:/key.json \
  --publish 127.0.0.1:PORT:PORT \
  gcr.io/alloydb-connectors/alloydb-auth-proxy:latest \
  --address 0.0.0.0 \
  --port PORT \
  --credentials-file=/key.json \
  INSTANCE_URI

Ersetzen Sie PATH_TO_KEY_FILE durch den Pfad zur JSON-Schlüsseldatei des nutzerverwalteten Dienstkontos, das für die Verbindungsautorisierung verwendet werden soll.

Beispiele für Start-ups

Die folgenden Beispiele zeigen verschiedene Möglichkeiten, den Auth-Proxy-Client zu starten. Dabei werden die folgenden Beispiel-URIs für die Instanzverbindung verwendet:

projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary

projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool

Einfacher Start

./alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary"

In diesem Beispiel autorisiert der Auth-Proxy-Client die Verbindung, indem er der normalen Abfolge der Autorisierungsschritte folgt, und beginnt dann, auf lokale Verbindungen zur myprimary-Instanz auf 127.0.0.1:5432 zu warten.

Start mit einem vom Nutzer verwalteten Dienstkonto

./alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \\
  --credentials-file "myappaccount/key.json"

In diesem Beispiel autorisiert der Auth-Proxy-Client die Verbindung mit dem JSON-Schlüssel des nutzerverwalteten Dienstkontos, der unter myappaccount/key.json gespeichert ist, und beginnt dann, auf lokale Verbindungen zur myprimary-Instanz unter 127.0.0.1:5432 zu warten.

Startzeit bei Verbindung zu mehreren Instanzen

./alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool"

In diesem Beispiel autorisiert der Auth-Proxy-Client die Verbindung, indem er der normalen Abfolge der Autorisierungsschritte folgt, und überwacht dann lokale Verbindungen zur myprimary-Instanz auf 127.0.0.1:5432 und zur myreadpool-Instanz auf 127.0.0.1:5433.

Starten und Überwachen von benutzerdefinierten Ports

Die Verwendung benutzerdefinierter Ports für den Auth-Proxy-Client kann nützlich sein, wenn Sie Port 5432 für andere PostgreSQL-Verbindungen reservieren müssen.

./alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary?port=5000" \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool?port=5001"

In diesem Beispiel autorisiert der Auth-Proxy-Client die Verbindung, indem er der normalen Abfolge der Autorisierungsschritte folgt, und überwacht dann lokale Verbindungen zur myprimary-Instanz auf 127.0.0.1:5000 und zur myreadpool-Instanz auf 127.0.0.1:5001.

Da diese benutzerdefinierten Ports sequenziell sind, kann derselbe Effekt mit diesem Startbefehl erzielt werden:

./alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool" \
  --port 5000

Starten und Zuhören auf einer benutzerdefinierten IP-Adresse

./alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
  --address "0.0.0.0"

In diesem Beispiel autorisiert der Auth-Proxy-Client die Verbindung, indem er der normalen Abfolge der Autorisierungsschritte folgt, und beginnt dann, auf lokale Verbindungen zur myprimary-Instanz auf 0.0.0.0:5432 zu warten.

Anwendung über den AlloyDB Auth-Proxy mit einer Datenbank verbinden

In den folgenden Beispielen wird gezeigt, wie Sie eine Anwendung mithilfe des AlloyDB Auth-Proxy mit einer Datenbank verbinden.

Das psql-Beispiel zeigt, wie eine Verbindung zu einem Befehlszeilentool hergestellt wird.

Das Herstellen einer Verbindung zu einer AlloyDB-Instanz über den AlloyDB Auth-Proxy entspricht für mehrere Programmiersprachen dem Herstellen einer Verbindung zu einer Cloud SQL for PostgreSQL-Instanz über den Cloud SQL Auth-Proxy. Die Sprachbeispiele hier sind daher mit denen für Cloud SQL for PostgreSQL identisch.

Diese Beispiele basieren auf einem standardmäßigen Start des Auth-Proxy-Clients, sodass er auf lokale TCP-Verbindungen an 127.0.0.1:5432 wartet.

psql

psql -h 127.0.0.1 -p 5432 -U DB_USER

Ersetzen Sie DB_USER durch den Datenbanknutzer, als der Sie eine Verbindung herstellen möchten, z. B. postgres.

Sie werden aufgefordert, das Passwort des Nutzers DB_USER einzugeben.

Python

import os

import sqlalchemy


# connect_tcp_socket initializes a TCP connection pool
# for an AlloyDB instance.
def connect_tcp_socket() -> sqlalchemy.engine.base.Engine:
    # 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_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>@<INSTANCE_HOST>:<db_port>/<db_name>
        sqlalchemy.engine.url.URL.create(
            drivername="postgresql+pg8000",
            username=db_user,
            password=db_pass,
            host=INSTANCE_HOST,
            port=db_port,
            database=db_name,
        ),
        # ...
    )
    return pool

Java


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>l

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

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

// createTcpPool initializes a TCP connection pool for an AlloyDB cluster.
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);
};

Go

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

package alloydb

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

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

// connectTCPSocket initializes a TCP connection pool for an AlloyDB cluster.
func connectTCPSocket() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Warning: %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' or IP Address of Cluster
		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: %v", 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.

development:
  adapter: postgresql
  # Configure additional properties here.
  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("DB_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.

// $username = 'your_db_user';
// $password = 'yoursupersecretpassword';
// $dbName = 'your_db_name';
// $dbHost = "127.0.0.1";

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

// Connect to the database
$conn = new PDO($dsn, $username, $password, $connConfig);