Verbindung mit dem AlloyDB Auth-Proxy herstellen

Auf dieser Seite wird beschrieben, 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 Informationen zum AlloyDB Auth-Proxy.

Wenn Sie den AlloyDB Auth-Proxy verwenden möchten, müssen Sie mehrere einmalige Einrichtungsschritte ausführen. Anschließend starten Sie den Auth-Proxy-Client und stellen dann darüber eine Verbindung zu Datenbanken her:

  1. Einrichtungsschritte:
    1. Laden Sie den Auth-Proxyclient auf Ihren Clienthost herunter.
    2. Wählen Sie das IAM-Hauptkonto (Identity and Access Management) aus, das für die Autorisierung verwendet werden soll. Achten Sie darauf, dass es die erforderlichen Berechtigungen hat und seine Anmeldedaten auf Ihrem Clienthost verfügbar sind.
    3. Rufen Sie die Verbindungs-URIs für die AlloyDB-Instanzen ab, zu denen Sie eine Verbindung herstellen möchten.
  2. Starten Sie den Auth-Proxyclient auf Ihrem Clienthost.
  3. Verbinden Sie die Anwendung mit einer Datenbank über eine lokale Verbindung zum Auth-Proxy-Client.

Hinweis

    Der Client-Host muss die folgenden Anforderungen erfüllen:

    • Er muss Netzwerkzugriff auf das Virtual Private Cloud-Netzwerk (VPC) haben, in dem sich die Instanzen befinden, mit denen Sie eine Verbindung herstellen möchten. Client-Hosts (z. B. Compute Engine-Instanzen) in diesem VPC-Netzwerk (Virtual Private Cloud) haben generell diesen Zugriff. Client-Hosts in externen Netzwerken (lokale Netzwerke oder andere VPC-Netzwerke) haben diesen Zugriff, 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 er ausgehende Verbindungen zu Port 5433 für die IP-Adressen Ihrer AlloyDB-Instanzen und ausgehende Verbindungen zu Port 443 (dem Standard-HTTPS-Port) für alle 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 API verwenden kann. Ändern Sie bei Bedarf den Zugriffsbereich so, dass er diesen umfasst.

Auth-Proxyclient herunterladen

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

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

Wenn Sie eine Verbindung zu Ihrem Cluster von außerhalb der VPC herstellen möchten, installieren Sie diese auf einer Maschine in Abhängigkeit davon, welche Strategie Sie für externe Verbindungen verwenden. Sie können den Auth-Proxy-Client beispielsweise auf einer in Ihrer App lokalen Maschine mit macOS oder Windows installieren und dann einen SOCKS-Server in Ihrem AlloyDB-VPC-Netzwerk verwenden, der als Zwischenstelle für die Verbindung fungiert. Weitere Informationen finden Sie unter Verbindung zu einem Cluster von außerhalb seiner VPC herstellen.

Linux

64-Bit (AMD)

  1. Auth-Proxy-Client herunterladen

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

  2. Auth-Proxy-Client ausführbar machen:

    chmod +x alloydb-auth-proxy

32-Bit (AMD)

  1. Auth-Proxy-Client herunterladen

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

  2. Auth-Proxy-Client ausführbar machen:

    chmod +x alloydb-auth-proxy

64-Bit (ARM)

  1. Auth-Proxy-Client herunterladen

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

  2. Auth-Proxy-Client ausführbar machen:

    chmod +x alloydb-auth-proxy

32-Bit (ARM)

  1. Auth-Proxy-Client herunterladen

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

  2. Auth-Proxy-Client ausführbar machen:

    chmod +x alloydb-auth-proxy

macOS

M1

  1. Auth-Proxy-Client herunterladen

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

  2. Auth-Proxy-Client ausführbar machen:

    chmod +x alloydb-auth-proxy

64-Bit

  1. Auth-Proxy-Client herunterladen

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

  2. Auth-Proxy-Client ausführbar machen:

    chmod +x alloydb-auth-proxy

32-Bit

  1. Auth-Proxy-Client herunterladen

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

  2. Auth-Proxy-Client ausführbar machen:

    chmod +x alloydb-auth-proxy

Windows

64-Bit

Klicken Sie mit der rechten Maustaste auf https://storage.googleapis.com/alloydb-auth-proxy/v1.13.9/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.13.9/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 Artifact Registry verfügbar.

Mit dem folgenden Befehl übertragen Sie das neueste Image mit Docker auf Ihre lokale Maschine:

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

Anderes Betriebssystem

Für andere Betriebssysteme, 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-Hauptkonten, 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, für die Autorisierung in Produktionsumgebungen ein Dienstkonto zu verwenden.

  • Ihr Nutzerkonto Sie können Ihr eigenes IAM-Nutzerkonto verwenden, um Verbindungen zu autorisieren.

    Die Verwendung Ihres 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.

  • Compute Engine-Standarddienstkonto Wenn der Client-Host eine Compute Engine-Instanz ist, können Sie das Compute Engine-Standarddienstkonto verwenden, um Verbindungen zu autorisieren.

Nachdem Sie ausgewählt haben, welches IAM-Hauptkonto verwendet werden soll, müssen Sie dafür sorgen, dass es die erforderlichen IAM-Berechtigungen hat und dass die Anmeldedaten auf Ihrem Clienthost verfügbar sind.

Erforderliche IAM-Berechtigungen

Das zum Autorisieren von Verbindungen verwendete IAM-Hauptkonto muss die Berechtigungen der vordefinierten Rollen roles/alloydb.client (Cloud AlloyDB Client) und roles/serviceusage.serviceUsageConsumer (Service Usage Consumer) 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 (Owner) im Google Cloud -Projekt oder eine Rolle, die diese Berechtigungen gewährt:

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

    Berechtigungen nach dem Prinzip der geringsten Berechtigung erhalten Sie, wenn der Admin Ihnen die Rolle roles/resourcemanager.projectIamAdmin (Project IAM Admin) zuweist.

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 zum Autorisieren von Verbindungen verwenden:

  • Nutzerverwaltetes Dienstkonto

    Erstellen Sie einen Dienstkontoschlüssel im JSON-Format und laden Sie ihn auf Ihren Clienthost herunter, um IAM-Anmeldedaten für ein vom Nutzer verwaltetes Dienstkonto bereitzustellen. Wenn Sie den Auth-Proxy-Client starten, geben Sie den Speicherort der Schlüsseldatei mit dem Flag --credentials-file an.

  • Ihr Nutzerkonto

    Wenn Sie IAM-Anmeldedaten für Ihr Nutzerkonto bereitstellen möchten, installieren Sie die Google Cloud CLI auf Ihrem Clienthost und führen Sie dann 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, sofern 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 Compute Engine-Standarddienstkonto bereits auf dem Host vorhanden. Wenn Sie den Auth-Proxy-Client starten, werden diese Anmeldedaten automatisch erkannt und verwendet, wenn keine Anmeldedaten für vom Nutzer verwaltete Dienstkonten und Nutzerkonten verfügbar sind.

Verbindungs-URIs für die AlloyDB-Instanzen erfassen

Wenn Sie den Auth-Proxy-Client starten, geben Sie die AlloyDB-Instanzen an, zu denen Sie eine Verbindung herstellen möchten. Verwenden Sie dazu das folgende Verbindungs-URI-Format:

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

Wenn Sie eine Liste aller Verbindungs-URIs Ihrer Instanzen aufrufen möchten, verwenden Sie den gcloud CLI-Befehl alloydb instances list.

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

Auth-Proxy-Client starten

Geben Sie beim Start des Auth-Proxy-Client Informationen dazu an, mit welchen AlloyDB-Instanzen eine Verbindung hergestellt werden soll, und bei Bedarf Anmeldedaten, die zur Autorisierung dieser Verbindungen verwendet werden sollen.

Wenn der Auth-Proxy-Client gestartet wird, führt er folgende Schritte aus:

  • Autorisiert Verbindungen zu AlloyDB-Instanzen mit den Anmeldedaten und IAM-Berechtigungen des konfigurierten IAM-Hauptkontos. Dabei wird in einer bestimmten Abfolge von Schritten nach Anmeldedaten gesucht.
  • Autorisiert automatisch öffentliche IP-Verbindungen zum Quellnetzwerk, wenn für die Instanz die öffentliche IP-Adresse aktiviert ist.
  • Konfiguriert eine private mTLS 1.3-Verbindung zum Auth-Proxy-Server jeder Instanz.
  • Beginnt mit dem Empfang von Verbindungsanfragen von lokalen Clients.

Standardmäßig überwacht der Auth-Proxy-Client TCP-Verbindungen auf der IP-Adresse 127.0.0.1. Er beginnt mit Port 5432 und erhöht die Portnummer für jede AlloyDB-Instanz nach der ersten um eins. Sie können beim Starten des Auth-Proxy-Clients eine andere Listener-Adresse 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 \ ]
    [ --disable-built-in-telemetry ]

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 Standardport für den lokalen Listener, den der Auth-Proxy-Client für die Instanz verwendet, überschreiben, indem Sie den Abfrageparameter port dem URI 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 vom Nutzer verwalteten 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 Listener-Adresse, die anstelle der Standardadresse 127.0.0.1 verwendet werden soll, wenn auf lokale TCP-Verbindungen gewartet wird.

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

Mit dem optionalen Flag --psc kann der Auth-Proxy eine Verbindung zu einer Instanz mit aktiviertem Private Service Connect herstellen. Weitere Informationen zum Einrichten von DNS mit Private Service Connect finden Sie unter DNS-verwaltete Zone und DNS-Eintrag konfigurieren.

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

Mit dem optionalen Flag --disable-built-in-telemetry wird der interne Messwertmelder, den der Auth-Proxy verwendet, um Informationen zum Verbindungs- und Netzwerkstatus zu melden, deaktiviert. Standardmäßig werden die internen Vorgänge des Auth-Proxys unter dem Systemmesswert-Präfix alloydb.googleapis.com gemeldet. Mithilfe dieser Messwerte kann AlloyDB die Leistung verbessern und Probleme mit der Clientverbindung erkennen. Diese Option ist nützlich beim Ausführen von Apps in Umgebungen, in denen der Export von Messwerten nach außen eingeschränkt ist. Wenn Sie diese Telemetriedaten deaktivieren möchten, verwenden Sie dieses Flag.

Docker-Container

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

Mit den von Ihrer Compute Engine-Instanz bereitgestellten Anmeldedaten 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 wird im folgenden Format angegeben:

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

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

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

Geben Sie im --publish-Flag 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 aus zugänglich ist.

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

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 vom Nutzer verwalteten Dienstkontos, das für die Verbindungsautorisierung verwendet werden soll.

Beispiele für den Start

Die folgenden Beispiele zeigen verschiedene Möglichkeiten, den Auth-Proxy-Client zu starten. Dabei werden die folgenden Beispiel-Verbindungs-URIs für Instanzen 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 die normale Folge von Autorisierungsschritten durchläuft. Anschließend wartet er auf lokale Verbindungen zur myprimary-Instanz auf 127.0.0.1:5432.

Starten 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 vom Nutzer verwalteten Dienstkontos, der unter myappaccount/key.json gespeichert ist. Anschließend wartet er auf lokale Verbindungen zur myprimary-Instanz auf 127.0.0.1:5432.

Start mit Verbindungen 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 die normale Folge von Autorisierungsschritten durchläuft. Anschließend wartet er auf lokale Verbindungen zur Instanz myprimary auf 127.0.0.1:5432 und zur Instanz myreadpool auf 127.0.0.1:5433.

Start mit Überwachung an 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 die normale Folge von Autorisierungsschritten durchläuft. Anschließend wartet er auf lokale Verbindungen zur Instanz myprimary auf 127.0.0.1:5000 und zur Instanz myreadpool 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

Start mit Überwachung 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 die normale Folge von Autorisierungsschritten durchläuft. Anschließend wartet er auf lokale Verbindungen zur myprimary-Instanz auf 0.0.0.0:5432.

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

Die folgenden Beispiele zeigen, wie Sie eine Anwendung mithilfe des AlloyDB Auth-Proxys mit einer Datenbank verbinden können.

Im psql-Beispiel wird gezeigt, wie Sie ein Befehlszeilentool verbinden.

Die Verbindung zu einer AlloyDB-Instanz mit dem AlloyDB Auth-Proxy funktioniert für mehrere Programmiersprachen identisch zur Verbindung einer Cloud SQL for PostgreSQL-Instanz mit dem Cloud SQL Auth-Proxy. Die Sprachbeispiele hier sind also dieselben wie für Cloud SQL for PostgreSQL.

Diese Beispiele basieren auf einem Standardstart des Auth-Proxy-Clients, sodass er auf lokale TCP-Verbindungen zu 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, mit dem 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);