Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

חיבור באמצעות מחברי השפה של AlloyDB

‫AlloyDB Language Connectors הן ספריות שמספקות תהליך פשוט ליצירת חיבורים מאובטחים לאשכול באמצעות:

חיבורי mTLS אוטומטיים
תמיכה בהרשאה שמבוססת על ניהול זהויות והרשאות גישה (IAM)
אימות אוטומטי של IAM

אם לא קיים נתיב רשת, אי אפשר להשתמש ב-AlloyDB Language Connectors כדי לספק נתיב רשת לאשכול AlloyDB.

מידע נוסף על AlloyDB Language Connectors זמין במאמר סקירה כללית של AlloyDB Language Connectors.

בדף הזה מפורטים מחברי השפה הבאים של AlloyDB:

מחבר Java ל-AlloyDB
המחבר של AlloyDB Go
המחבר של AlloyDB Python

לפני שמתחילים

מפעילים את AlloyDB API.

הפעלת ה-API
יוצרים מכונת AlloyDB ומגדירים את משתמש ברירת המחדל.

מידע נוסף על יצירת מופע זמין במאמר יצירת מופע ראשי.

מידע נוסף על תפקידי משתמשים זמין במאמר תפקידים מוגדרים מראש ב-IAM של AlloyDB.
צריך להגדיר את התפקידים וההרשאות הבאים שנדרשים כדי להתחבר למופע AlloyDB:
- roles/alloydb.client
- roles/serviceusage.serviceUsageConsumer
  
  מידע נוסף על התפקידים וההרשאות הנדרשים זמין במאמר ניהול אימות IAM.

התקנה של AlloyDB Language Connectors

Java

‫AlloyDB Java Connector היא ספרייה שמספקת הרשאה והצפנה מבוססות IAM כשמתחברים למופע AlloyDB. אם אתם משתמשים ב-Spring Boot, כדאי לעיין ב-Spring Boot AlloyDB starter.

התקנה

ב-Maven, אפשר להתקין את AlloyDB Java Connector על ידי הוספת הקוד הבא לקובץ pom.xml של הפרויקט:

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

ב-Gradle, אפשר להתקין את AlloyDB Java Connector על ידי הוספת הקוד הבא לקובץ gradle.build של הפרויקט:

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

המחבר של AlloyDB Python הוא ספרייה שאפשר להשתמש בה לצד מנהל התקן של מסד נתונים כדי לאפשר למשתמשים עם הרשאות מתאימות להתחבר למסד נתונים של AlloyDB בלי להוסיף כתובות IP לרשימת ההיתרים באופן ידני.

התקנה

אפשר להתקין את ספריית AlloyDB Python Connector באמצעות pip install.

אם אתם משתמשים ב-pg8000, מריצים את הפקודה הבאה:

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

Python (asyncpg)

התקנה

אפשר להתקין את ספריית AlloyDB Python Connector באמצעות pip install.

אם אתם משתמשים ב-asyncpg, מריצים את הפקודה הבאה:

כדי להשתמש ב-asyncpg:

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

מידע נוסף על שימוש בדרייבר אסינכרוני זמין במאמר שימוש בדרייבר אסינכרוני.

‫Go ‏ (pgx)

‫AlloyDB Go Connector הוא מחבר AlloyDB שנועד לשימוש בשפת Go.

התקנה

אפשר להתקין את AlloyDB Go Connector באמצעות go get.

אם משתמשים ב-pgx, מריצים את הפקודה הבאה:

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

‫Go (database/sql)

‫AlloyDB Go Connector הוא מחבר AlloyDB שנועד לשימוש בשפת Go.

התקנה

אפשר להתקין את AlloyDB Go Connector באמצעות go get.

אם משתמשים ב-database/sql, מריצים את הפקודה הבאה:

go get cloud.google.com/go/alloydbconn

הגדרת מחברי השפה של AlloyDB

Java

כדי להשתמש ב-AlloyDB Java Connector כדי להתחבר לאשכול AlloyDB, צריך להגדיר אותו באמצעות השלבים הבאים.

כדי להשתמש בקטע הקוד הזה בהקשר של אפליקציית אינטרנט, אפשר לעיין בקובץ README ב-GitHub.


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

שימוש בכתובת IP ציבורית

אם אתם משתמשים בכתובת IP ציבורית כדי להתחבר לאשכול AlloyDB, צריך לכלול את הפרטים הבאים:

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

שימוש ב-Private Service Connect

אם אתם משתמשים ב-Private Service Connect כדי להתחבר למופע AlloyDB, צריך לכלול את הפרטים הבאים:

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

אימות אוטומטי של IAM

כברירת מחדל, מחברי השפה של AlloyDB משתמשים באימות מובנה. אפשר להשתמש באימות אוטומטי של IAM עם AlloyDB Java Connector. כדי להפעיל את האפשרות, צריך לכלול את השורות הבאות:

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

Python ‏ (pg8000)

כדי להשתמש ב-AlloyDB Python Connector כדי להתחבר לאשכול AlloyDB, צריך להגדיר את המחבר באמצעות השלבים הבאים, אם משתמשים ב-pg8000.

כדי להשתמש בקטע הקוד הזה בהקשר של אפליקציית אינטרנט, אפשר לעיין בקובץ README ב-GitHub.

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

שימוש בכתובת IP ציבורית

אם אתם משתמשים בכתובת IP ציבורית כדי להתחבר לאשכול AlloyDB, צריך להחליף את פונקציית החיבור בפונקציה הבאה:

  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

אם אתם משתמשים ב-Private Service Connect כדי להתחבר למופע AlloyDB, צריך לכלול את הפרטים הבאים:

  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

אימות אוטומטי של IAM

כברירת מחדל, מחברי השפה של AlloyDB משתמשים באימות מובנה. אפשר להשתמש באימות אוטומטי של IAM עם AlloyDB Python Connector. כדי להפעיל, מחליפים את פונקציית החיבור בפונקציה הבאה:

  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)

כדי להשתמש ב-AlloyDB Python Connector כדי להתחבר לאשכול AlloyDB, צריך להגדיר את המחבר באמצעות השלבים הבאים, אם משתמשים ב-async.

כדי להשתמש בקטע הקוד הזה בהקשר של אפליקציית אינטרנט, אפשר לעיין בקובץ README ב-GitHub.

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

שימוש בכתובת IP ציבורית

אם אתם משתמשים בכתובת IP ציבורית כדי להתחבר לאשכול AlloyDB, צריך להחליף את פונקציית החיבור בפונקציה הבאה:

  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

אם אתם משתמשים ב-Private Service Connect כדי להתחבר למופע AlloyDB, צריך לכלול את הפרטים הבאים:

    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

אימות אוטומטי של IAM

  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)

כדי להשתמש ב-AlloyDB Go Connector כדי להתחבר לאשכול AlloyDB, צריך להגדיר את המחבר באמצעות השלבים הבאים, אם משתמשים ב-pgx.

כדי להשתמש בקטע הקוד הזה בהקשר של אפליקציית אינטרנט, אפשר לעיין בקובץ README ב-GitHub.

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
}

שימוש בכתובת IP ציבורית

אם אתם משתמשים בכתובת IP ציבורית כדי להתחבר לאשכול AlloyDB, צריך להחליף את הפונקציה d.Dial בפונקציה הבאה:

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

שימוש ב-Private Service Connect

אם אתם משתמשים ב-Private Service Connect כדי להתחבר למופע AlloyDB, צריך לכלול את הפרטים הבאים:

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

אימות אוטומטי של IAM

כברירת מחדל, מחברי השפה של AlloyDB משתמשים באימות מובנה. אפשר להשתמש באימות אוטומטי של IAM עם AlloyDB Go Connector. כדי להפעיל את ההגדרה, מחליפים את הפונקציה alloydbconn.NewDialer בפונקציה הבאה:

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

השבתת טלמטריה מובנית

האפשרות WithOptOutOfBuiltInTelemetry משביתה את הייצוא של המדדים הפנימיים. כברירת מחדל, חיוג Google מדווח על הפעולות הפנימיות שלו באמצעות קידומת המדד של המערכת alloydb.googleapis.com. המדדים האלה עוזרים ל-AlloyDB לשפר את הביצועים ולזהות בעיות בקישוריות של הלקוח. האפשרות הזו שימושית לאפליקציות שפועלות בסביבות שבהן ייצוא מדדים יוצאים מוגבל. כדי להשבית את הטלמטריה הזו, צריך לספק את האפשרות הבאה כשמפעילים את Dialer:

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

‫Go (database/sql)

כדי להשתמש ב-AlloyDB Go Connector כדי להתחבר לאשכול AlloyDB, צריך להגדיר את המחבר באמצעות השלבים הבאים, אם משתמשים ב-database/sql.

כדי להשתמש בקטע הקוד הזה בהקשר של אפליקציית אינטרנט, אפשר לעיין בקובץ README ב-GitHub.

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
}

שימוש בכתובת IP ציבורית

אם אתם משתמשים בכתובת IP ציבורית כדי להתחבר לאשכול AlloyDB, צריך להחליף את הפונקציה RegisterDriver בפונקציה הבאה:

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

שימוש ב-Private Service Connect

אם אתם משתמשים ב-Private Service Connect כדי להתחבר למופע AlloyDB, צריך לכלול את הפרטים הבאים:

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

אימות אוטומטי של IAM

כברירת מחדל, מחברי השפה של AlloyDB משתמשים באימות מובנה. אפשר להשתמש באימות אוטומטי של IAM עם AlloyDB Go Connector. כדי להפעיל את התכונה, מחליפים את הפונקציה RegisterDriver בפונקציה הבאה:

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

השבתת טלמטריה מובנית

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

חיבור באמצעות מחברי השפה של AlloyDB קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

לפני שמתחילים

התקנה של AlloyDB Language Connectors

Java

התקנה

Python ‏ (pg8000)

התקנה

Python (asyncpg)

התקנה

‫Go ‏ (pgx)

התקנה

‫Go (database/sql)

התקנה

הגדרת מחברי השפה של AlloyDB

Java

Python ‏ (pg8000)

Python (asyncpg)

‫Go ‏ (pgx)

‫Go (database/sql)

חיבור באמצעות מחברי השפה של AlloyDB