Verbindung über AlloyDB Language Connectors herstellen

Die AlloyDB-Sprach-Connectors sind Bibliotheken, die einen vereinfachten Prozess zum Herstellen sicherer Verbindungen zu Ihrem Cluster bieten. Verwenden Sie dazu Folgendes:

  • Automatisierte mTLS-Verbindungen
  • Unterstützung für die IAM-basierte Autorisierung (Identity and Access Management)
  • Automatisierte IAM-Authentifizierung

AlloyDB-Sprach-Connectors können keinen Netzwerkpfad zu einem AlloyDB-Cluster bereitstellen, wenn noch kein solcher vorhanden ist.

Weitere Informationen zu AlloyDB-Sprach-Connectors finden Sie unter Übersicht über AlloyDB-Sprach-Connectors.

Auf dieser Seite werden die folgenden AlloyDB-Sprach-Connectors erläutert:

  • Der AlloyDB-Java-Connector
  • Der AlloyDB-Go-Connector
  • Der AlloyDB-Python-Connector

Hinweis

  1. Aktivieren Sie die AlloyDB API.

    API aktivieren

  2. Erstellen Sie eine AlloyDB-Instanz und konfigurieren Sie den Standardnutzer.

    Weitere Informationen zum Erstellen einer Instanz finden Sie unter Primäre Instanz erstellen.

    Weitere Informationen zu Nutzerrollen finden Sie unter Vordefinierte AlloyDB-IAM-Rollen.

  3. Konfigurieren Sie die folgenden Rollen und Berechtigungen, die zum Herstellen einer Verbindung zu einer AlloyDB-Instanz erforderlich sind:

    • roles/alloydb.client

    • roles/serviceusage.serviceUsageConsumer

      Weitere Informationen zu den erforderlichen Rollen und Berechtigungen finden Sie unter IAM-Authentifizierung verwalten.

AlloyDB-Sprach-Connectors installieren

Java

Der AlloyDB-Java-Connector ist eine Bibliothek, die IAM-basierte Autorisierung und Verschlüsselung bietet, wenn eine Verbindung zu einer AlloyDB-Instanz hergestellt wird. Wenn Sie Spring Boot verwenden, lesen Sie den Spring Boot AlloyDB-Starter.

Installation

Für Maven können Sie den AlloyDB-Java-Connector installieren, indem Sie der Datei pom.xml Ihres Projekts Folgendes hinzufügen:

<!-- Add the connector with the latest version -->
<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>alloydb-jdbc-connector</artifactId>
  <version>0.4.0</version>
</dependency>

<!-- Add the driver with the latest version -->
<dependency>
  <groupId>org.postgresql</groupId>
  <artifactId>postgresql</artifactId>
  <version>46.6.0<</version>
</dependency>

<!-- Add HikariCP with the latest version -->
<dependency>
  <groupId>com.zaxxer</groupId>
  <artifactId>HikariCP</artifactId>
  <version>5.1.0</version>
</dependency>

Für Gradle können Sie den AlloyDB-Java-Connector installieren, indem Sie der Datei gradle.build Ihres Projekts Folgendes hinzufügen:

// Add connector with the latest version
implementation group: 'com.google.cloud.alloydb', name: 'alloydb-jdbc-connector', version: '0.4.0'

// Add driver with the latest version
implementation group: 'org.postgresql', name: 'postgresql', version: '46.6.0'

// Add HikariCP with the latest version
implementation group: 'com.zaxxer', name: 'HikariCP', version: '5.1.0'

Python (pg8000)

Der AlloyDB-Python-Connector ist eine Bibliothek, die neben einem Datenbanktreiber verwendet werden kann, um Nutzern mit ausreichenden Berechtigungen die Verbindung zu einer AlloyDB-Datenbank zu ermöglichen, ohne dass sie manuell IPs zulassen müssen.

Installation

Sie können die AlloyDB-Python-Connector-Bibliothek mit pip install installieren.

Wenn Sie pg8000 verwenden, führen Sie den folgenden Befehl aus:

pip install "google-cloud-alloydb-connector[pg8000]" sqlalchemy

Python (asyncpg)

Der AlloyDB-Python-Connector ist eine Bibliothek, die neben einem Datenbanktreiber verwendet werden kann, um Nutzern mit ausreichenden Berechtigungen die Verbindung zu einer AlloyDB-Datenbank zu ermöglichen, ohne dass sie manuell IPs zulassen müssen.

Installation

Sie können die AlloyDB-Python-Connector-Bibliothek mit pip install installieren.

Wenn Sie asyncpg verwenden, führen Sie den folgenden Befehl aus:

Verwenden Sie für asyncpg:

pip install "google-cloud-alloydb-connector[asyncpg]" "sqlalchemy[asyncio]"

Weitere Informationen zur Verwendung des asynchronen Treibers finden Sie unter Verwendung des asynchronen Treibers.

Go (pgx)

Der AlloyDB-Go-Connector ist ein AlloyDB-Connector, der für die Verwendung mit der Go-Sprache entwickelt wurde.

Installation

Sie können den AlloyDB-Go-Connector mit go get installieren.

Wenn Sie pgx verwenden, führen Sie den folgenden Befehl aus:

go get github.com/jackc/pgx/v5
go get cloud.google.com/go/alloydbconn

Go (database/sql)

Der AlloyDB-Go-Connector ist ein AlloyDB-Connector, der für die Verwendung mit der Go-Sprache entwickelt wurde.

Installation

Sie können den AlloyDB-Go-Connector mit go get installieren.

Wenn Sie database/sql verwenden, führen Sie den folgenden Befehl aus:

go get cloud.google.com/go/alloydbconn

AlloyDB-Sprach-Connectors konfigurieren

Java

Wenn Sie den AlloyDB-Java-Connector verwenden möchten, um eine Verbindung zu Ihrem AlloyDB-Cluster herzustellen, konfigurieren Sie ihn mit den folgenden Schritten.

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;

public class AlloyDbJdbcConnectorDataSourceFactory {

  public static final String ALLOYDB_DB = System.getenv("ALLOYDB_DB");
  public static final String ALLOYDB_USER = System.getenv("ALLOYDB_USER");
  public static final String ALLOYDB_PASS = System.getenv("ALLOYDB_PASS");
  public static final String ALLOYDB_INSTANCE_NAME = System.getenv("ALLOYDB_INSTANCE_NAME");

  static HikariDataSource createDataSource() {
    HikariConfig config = new HikariConfig();

    config.setJdbcUrl(String.format("jdbc:postgresql:///%s", ALLOYDB_DB));
    config.setUsername(ALLOYDB_USER); // e.g., "postgres"
    config.setPassword(ALLOYDB_PASS); // e.g., "secret-password"
    config.addDataSourceProperty("socketFactory", "com.google.cloud.alloydb.SocketFactory");
    // e.g., "projects/my-project/locations/us-central1/clusters/my-cluster/instances/my-instance"
    config.addDataSourceProperty("alloydbInstanceName", ALLOYDB_INSTANCE_NAME);

    return new HikariDataSource(config);
  }
}

Öffentliche IP-Adresse verwenden

Wenn Sie eine öffentliche IP-Adresse verwenden, um eine Verbindung zu Ihrem AlloyDB-Cluster herzustellen, fügen Sie Folgendes hinzu:

config.addDataSourceProperty("alloydbIpType", "PUBLIC");

Private Service Connect verwenden

Wenn Sie Private Service Connect verwenden, um eine Verbindung zu Ihrer AlloyDB-Instanz herzustellen, fügen Sie Folgendes hinzu:

config.addDataSourceProperty("alloydbIpType", "PSC");

Automatische IAM-Authentifizierung

Standardmäßig verwenden AlloyDB-Sprach-Connectors die integrierte Authentifizierung. Sie können die automatische IAM-Authentifizierung mit dem AlloyDB-Java-Connector verwenden. Fügen Sie Folgendes hinzu, um sie zu aktivieren:

config.addDataSourceProperty("alloydbEnableIAMAuth", "true");

Python (pg8000)

Wenn Sie den AlloyDB-Python-Connector verwenden möchten, um eine Verbindung zu Ihrem AlloyDB-Cluster herzustellen, konfigurieren Sie den Connector mit den folgenden Schritten, wenn Sie pg8000 verwenden.

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

import sqlalchemy

from google.cloud.alloydbconnector import Connector


def create_sqlalchemy_engine(
    inst_uri: str,
    user: str,
    password: str,
    db: str,
    refresh_strategy: str = "background",
) -> tuple[sqlalchemy.engine.Engine, Connector]:
    """Creates a connection pool for an AlloyDB instance and returns the pool
    and the connector. Callers are responsible for closing the pool and the
    connector.

    A sample invocation looks like:

        engine, connector = create_sqlalchemy_engine(
            inst_uri,
            user,
            password,
            db,
        )
        with engine.connect() as conn:
            time = conn.execute(sqlalchemy.text("SELECT NOW()")).fetchone()
            conn.commit()
            curr_time = time[0]
            # do something with query result
            connector.close()

    Args:
        instance_uri (str):
            The instance URI specifies the instance relative to the project,
            region, and cluster. For example:
            "projects/my-project/locations/us-central1/clusters/my-cluster/instances/my-instance"
        user (str):
            The database user name, e.g., postgres
        password (str):
            The database user's password, e.g., secret-password
        db (str):
            The name of the database, e.g., mydb
        refresh_strategy (Optional[str]):
            Refresh strategy for the AlloyDB Connector. Can be one of "lazy"
            or "background". For serverless environments use "lazy" to avoid
            errors resulting from CPU being throttled.
    """
    connector = Connector(refresh_strategy=refresh_strategy)

    # create SQLAlchemy connection pool
    engine = sqlalchemy.create_engine(
        "postgresql+pg8000://",
        creator=lambda: connector.connect(
            inst_uri,
            "pg8000",
            user=user,
            password=password,
            db=db,
        ),
    )
    engine.dialect.description_encoding = None
    return engine, connector

Öffentliche IP-Adresse verwenden

Wenn Sie eine öffentliche IP-Adresse verwenden, um eine Verbindung zu Ihrem AlloyDB-Cluster herzustellen, ersetzen Sie Ihre Verbindungsfunktion durch Folgendes:

  def getconn() -> pg8000.dbapi.Connection:
      conn: pg8000.dbapi.Connection = connector.connect(
          inst_uri,
          "pg8000",
          user=user,
          password=password,
          db=db,
          # use ip_type to specify public IP
          ip_type=IPTypes.PUBLIC,
      )
      return conn

Private Service Connect verwenden

Wenn Sie Private Service Connect verwenden, um eine Verbindung zu Ihrer AlloyDB-Instanz herzustellen, fügen Sie Folgendes hinzu:

  def getconn() -> pg8000.dbapi.Connection:
      conn: pg8000.dbapi.Connection = connector.connect(
          inst_uri,
          "pg8000",
          user=user,
          password=password,
          db=db,
          # use ip_type to specify PSC
          ip_type=IPTypes.PSC,
        )
      return conn

Automatische IAM-Authentifizierung

Standardmäßig verwenden AlloyDB-Sprach-Connectors die integrierte Authentifizierung. Sie können die automatische IAM-Authentifizierung mit dem AlloyDB-Python-Connector verwenden. Ersetzen Sie Ihre Verbindungsfunktion durch Folgendes, um sie zu aktivieren:

  def getconn() -> pg8000.dbapi.Connection:
      conn: pg8000.dbapi.Connection = connector.connect(
          inst_uri,
          "pg8000",
          user=user,
          password=password,
          db=db,
          # use enable_iam_auth to enable IAM authentication
          enable_iam_auth=True,
      )
      return conn

Python (asyncpg)

Wenn Sie den AlloyDB-Python-Connector verwenden möchten, um eine Verbindung zu Ihrem AlloyDB-Cluster herzustellen, konfigurieren Sie den Connector mit den folgenden Schritten, wenn Sie async verwenden.

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

import asyncpg
import sqlalchemy
import sqlalchemy.ext.asyncio

from google.cloud.alloydbconnector import AsyncConnector


async def create_sqlalchemy_engine(
    inst_uri: str,
    user: str,
    password: str,
    db: str,
    refresh_strategy: str = "background",
) -> tuple[sqlalchemy.ext.asyncio.engine.AsyncEngine, AsyncConnector]:
    """Creates a connection pool for an AlloyDB instance and returns the pool
    and the connector. Callers are responsible for closing the pool and the
    connector.

    A sample invocation looks like:

        engine, connector = await create_sqlalchemy_engine(
            inst_uri,
            user,
            password,
            db,
        )
        async with engine.connect() as conn:
            time = await conn.execute(sqlalchemy.text("SELECT NOW()")).fetchone()
            curr_time = time[0]
            # do something with query result
            await connector.close()

    Args:
        instance_uri (str):
            The instance URI specifies the instance relative to the project,
            region, and cluster. For example:
            "projects/my-project/locations/us-central1/clusters/my-cluster/instances/my-instance"
        user (str):
            The database user name, e.g., postgres
        password (str):
            The database user's password, e.g., secret-password
        db (str):
            The name of the database, e.g., mydb
        refresh_strategy (Optional[str]):
            Refresh strategy for the AlloyDB Connector. Can be one of "lazy"
            or "background". For serverless environments use "lazy" to avoid
            errors resulting from CPU being throttled.
    """
    connector = AsyncConnector(refresh_strategy=refresh_strategy)

    # create SQLAlchemy connection pool
    engine = sqlalchemy.ext.asyncio.create_async_engine(
        "postgresql+asyncpg://",
        async_creator=lambda: connector.connect(
            inst_uri,
            "asyncpg",
            user=user,
            password=password,
            db=db,
        ),
        execution_options={"isolation_level": "AUTOCOMMIT"},
    )
    return engine, connector

Öffentliche IP-Adresse verwenden

Wenn Sie eine öffentliche IP-Adresse verwenden, um eine Verbindung zu Ihrem AlloyDB-Cluster herzustellen, ersetzen Sie Ihre Verbindungsfunktion durch Folgendes:

  async def getconn() -> asyncpg.Connection:
    conn: asyncpg.Connection = await connector.connect(
        inst_uri,
        "asyncpg",
        user=user,
        password=password,
        db=db,
        # use ip_type to specify public IP
        ip_type=IPTypes.PUBLIC,
    )
    return conn

Private Service Connect verwenden

Wenn Sie Private Service Connect verwenden, um eine Verbindung zu Ihrer AlloyDB-Instanz herzustellen, fügen Sie Folgendes hinzu:

    async def getconn() -> asyncpg.Connection:
      conn: asyncpg.Connection = await connector.connect(
          inst_uri,
          "asyncpg",
          user=user,
          password=password,
          db=db,
          # use ip_type to specify PSC
          ip_type=IPTypes.PSC,
      )
      return conn

Automatische IAM-Authentifizierung

Standardmäßig verwenden AlloyDB-Sprach-Connectors die integrierte Authentifizierung. Sie können die automatische IAM-Authentifizierung mit dem AlloyDB-Python-Connector verwenden. Ersetzen Sie Ihre Verbindungsfunktion durch Folgendes, um sie zu aktivieren:

  async def getconn() -> asyncpg.Connection:
    conn: asyncpg.Connection = await connector.connect(
        inst_uri,
        "asyncpg",
        user=user,
        password=password,
        db=db,
        # use enable_iam_auth to enable IAM authentication
        enable_iam_auth=True,
    )
    return conn

Go (pgx)

Wenn Sie den AlloyDB-Go-Connector verwenden möchten, um eine Verbindung zu Ihrem AlloyDB-Cluster herzustellen, konfigurieren Sie den Connector mit den folgenden Schritten, wenn Sie pgx verwenden.

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

import (
	"context"
	"fmt"
	"net"

	"cloud.google.com/go/alloydbconn"
	"github.com/jackc/pgx/v5/pgxpool"
)

// connectPgx establishes a connection to your database using pgxpool and the
// AlloyDB Go Connector (aka alloydbconn.Dialer)
//
// The function takes an instance URI, a username, a password, and a database
// name. Usage looks like this:
//
//	pool, cleanup, err := connectPgx(
//	  context.Background(),
//	  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myinstance",
//	  "postgres",
//	  "secretpassword",
//	  "mydb",
//	)
//
// In addition to a *pgxpool.Pool type, the function returns a cleanup function
// that should be called when you're done with the database connection.
func connectPgx(
	ctx context.Context, instURI, user, pass, dbname string,
	opts ...alloydbconn.Option,
) (*pgxpool.Pool, func() error, error) {
	// First initialize the dialer. alloydbconn.NewDialer accepts additional
	// options to configure credentials, timeouts, etc.
	//
	// For details, see:
	// https://pkg.go.dev/cloud.google.com/go/alloydbconn#Option
	d, err := alloydbconn.NewDialer(ctx, opts...)
	if err != nil {
		noop := func() error { return nil }
		return nil, noop, fmt.Errorf("failed to init Dialer: %v", err)
	}
	// The cleanup function will stop the dialer's background refresh
	// goroutines. Call it when you're done with your database connection to
	// avoid a goroutine leak.
	cleanup := func() error { return d.Close() }

	dsn := fmt.Sprintf(
		// sslmode is disabled, because the Dialer will handle the SSL
		// connection instead.
		"user=%s password=%s dbname=%s sslmode=disable",
		user, pass, dbname,
	)

	// Prefer pgxpool for applications.
	// For more information, see:
	// https://github.com/jackc/pgx/wiki/Getting-started-with-pgx#using-a-connection-pool
	config, err := pgxpool.ParseConfig(dsn)
	if err != nil {
		return nil, cleanup, fmt.Errorf("failed to parse pgx config: %v", err)
	}

	// Tell pgx to use alloydbconn.Dialer to connect to the instance.
	config.ConnConfig.DialFunc = func(ctx context.Context, _ string, _ string) (net.Conn, error) {
		return d.Dial(ctx, instURI)
	}

	// Establish the connection.
	pool, connErr := pgxpool.NewWithConfig(ctx, config)
	if connErr != nil {
		return nil, cleanup, fmt.Errorf("failed to connect: %s", connErr)
	}

	return pool, cleanup, nil
}

Öffentliche IP-Adresse verwenden

Wenn Sie eine öffentliche IP-Adresse verwenden, um eine Verbindung zu Ihrem AlloyDB-Cluster herzustellen, ersetzen Sie Ihre Funktion d.Dial durch Folgendes:

d.Dial(ctx, instURI, alloydbconn.WithPublicIP())

Private Service Connect verwenden

Wenn Sie Private Service Connect verwenden, um eine Verbindung zu Ihrer AlloyDB-Instanz herzustellen, fügen Sie Folgendes hinzu:

  d.Dial(ctx, instURI, alloydbconn.WithPSC())

Automatische IAM-Authentifizierung

Standardmäßig verwenden AlloyDB-Sprach-Connectors die integrierte Authentifizierung. Sie können die automatische IAM-Authentifizierung mit dem AlloyDB-Go-Connector verwenden. Ersetzen Sie die Funktion alloydbconn.NewDialer durch Folgendes, um sie zu aktivieren:

d, err := alloydbconn.NewDialer(ctx, alloydbconn.WithIAMAuthN())

Integrierte Telemetrie deaktivieren

Die Option WithOptOutOfBuiltInTelemetry deaktiviert den internen Messwert-Export. Standardmäßig werden die internen Vorgänge des Dialers 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 Telemetrie deaktivieren möchten, geben Sie beim Initialisieren eines Dialers die folgende Option an:

  d.Dial(ctx, instURI, alloydbconn.WithOptOutOfBuiltInTelemetry())

Go (database/sql)

Wenn Sie den AlloyDB-Go-Connector verwenden möchten, um eine Verbindung zu Ihrem AlloyDB-Cluster herzustellen, konfigurieren Sie den Connector mit den folgenden Schritten, wenn Sie database/sql verwenden.

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

import (
	"database/sql"
	"fmt"

	"cloud.google.com/go/alloydbconn"
	"cloud.google.com/go/alloydbconn/driver/pgxv5"
)

// connectDatabaseSQL establishes a connection to your database using the Go
// standard library's database/sql package and using the AlloyDB Go Connector
// (aka alloydbconn.Dialer)
//
// The function takes an instance URI, a username, a password, and a database
// name. Usage looks like this:
//
//	db, cleanup, err := connectDatabaseSQL(
//	  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myinstance",
//	  "postgres",
//	  "secretpassword",
//	  "mydb",
//	)
//
// In addition to a *db.SQL type, the function returns a cleanup function that
// should be called when you're done with the database connection.
func connectDatabaseSQL(
	instURI, user, pass, dbname string,
	opts ...alloydbconn.Option,
) (*sql.DB, func() error, error) {
	// First, register the AlloyDB driver. Note, the driver's name is arbitrary
	// and must only match what you use below in sql.Open. Also,
	// pgxv5.RegisterDriver accepts options to configure credentials, timeouts,
	// etc.
	//
	// For details, see:
	// https://pkg.go.dev/cloud.google.com/go/alloydbconn#Option
	//
	// The cleanup function will stop the dialer's background refresh
	// goroutines. Call it when you're done with your database connection to
	// avoid a goroutine leak.
	cleanup, err := pgxv5.RegisterDriver("alloydb", opts...)
	if err != nil {
		return nil, cleanup, err
	}

	db, err := sql.Open(
		"alloydb",
		fmt.Sprintf(
			// sslmode is disabled, because the Dialer will handle the SSL
			// connection instead.
			"host=%s user=%s password=%s dbname=%s sslmode=disable",
			instURI, user, pass, dbname,
		),
	)
	return db, cleanup, err
}

Öffentliche IP-Adresse verwenden

Wenn Sie eine öffentliche IP-Adresse verwenden, um eine Verbindung zu Ihrem AlloyDB-Cluster herzustellen, ersetzen Sie Ihre Funktion RegisterDriver durch Folgendes:

cleanup, err := pgxv5.RegisterDriver(
  "alloydb",
  alloydbconn.WithDefaultDialOptions(alloydbconn.WithPublicIP())
)

Private Service Connect verwenden

Wenn Sie Private Service Connect verwenden, um eine Verbindung zu Ihrer AlloyDB-Instanz herzustellen, fügen Sie Folgendes hinzu:

  cleanup, err := pgxv5.RegisterDriver(
    "alloydb",
    alloydbconn.WithDefaultDialOptions(alloydbconn.WithPSC())
)

Automatische IAM-Authentifizierung

Standardmäßig verwenden AlloyDB-Sprach-Connectors die integrierte Authentifizierung. Sie können die automatische IAM-Authentifizierung mit dem AlloyDB-Go-Connector verwenden. Ersetzen Sie Ihre Funktion RegisterDriver durch Folgendes, um sie zu aktivieren:

cleanup, err := pgxv5.RegisterDriver(
  "alloydb",
  alloydbconn.WithIAMAuthN()
)

Integrierte Telemetrie deaktivieren

Die Option WithOptOutOfBuiltInTelemetry deaktiviert den internen Messwert-Export. Standardmäßig werden die internen Vorgänge des Dialers 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 Telemetrie deaktivieren möchten, geben Sie beim Initialisieren eines Dialers die folgende Option an:

cleanup, err := pgxv5.RegisterDriver(
  "alloydb",
  alloydbconn.WithOptOutOfBuiltInTelemetry(),
)