AlloyDB 言語コネクタを使用して接続する

AlloyDB Language Connectors は、クラスタへの安全な接続を確立するための簡素化されたプロセスを提供するライブラリです。次のものを使用します。

• 自動 mTLS 接続
• Identity and Access Management（IAM）ベースの認可のサポート
• IAM 認証の自動化

ネットワーク パスがまだ存在しない場合、AlloyDB Language コネクタは AlloyDB クラスタへのネットワーク パスを提供できません。

AlloyDB Language Connectors の詳細については、AlloyDB Language Connectors の概要をご覧ください。

このページでは、次の AlloyDB 言語コネクタについて説明します。

• AlloyDB Java コネクタ
• AlloyDB Go コネクタ
• AlloyDB Python コネクタ

始める前に

1. AlloyDB Admin API を有効にします。

   API を有効にする

2. AlloyDB インスタンスを作成し、デフォルト ユーザーを構成します。

   インスタンスの作成の詳細については、プライマリ インスタンスを作成するをご覧ください。

   ユーザーロールの詳細については、事前定義された AlloyDB IAM ロールをご覧ください。

3. AlloyDB インスタンスへの接続に必要な次のロールと権限を構成します。

   • roles/alloydb.client

   • roles/serviceusage.serviceUsageConsumer

     必要なロールと権限の詳細については、IAM 認証を管理するをご覧ください。

AlloyDB Language コネクタをインストールする

Java

AlloyDB Java コネクタは、AlloyDB インスタンスへの接続時に IAM ベースの認可と暗号化を提供するライブラリです。

インストール

Maven の場合は、プロジェクトの pom.xml に次のコードを追加して AlloyDB Java Connector をインストールできます。

<!-- 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 の場合は、プロジェクトの gradle.build に次のコードを追加して AlloyDB Java Connector をインストールできます。

// 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 コネクタは、データベース ドライバとともに使用できるライブラリです。これにより、十分な権限があるユーザーは IP を手動で許可リストに登録することなく、AlloyDB データベースに接続できるようになります。

インストール

AlloyDB Python Connector ライブラリは pip install を使用してインストールできます。

pg8000 を使用している場合は、次のコマンドを実行します。

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

Python（asyncpg）

AlloyDB Python コネクタはデータベース ドライバとともに使用できるライブラリです。これにより、十分な権限があるユーザーは IP を手動で許可リストに登録することなく、AlloyDB データベースに接続できるようになります。

インストール

AlloyDB Python Connector ライブラリは pip install を使用してインストールできます。

asyncpg を使用している場合は、次のコマンドを実行します。

asyncpg の場合は、次を使用します。

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

非同期ドライバの使用方法の詳細については、非同期ドライバの使用をご覧ください。

Go（pgx）

AlloyDB Go コネクタは、Go 言語で使用するように設計された AlloyDB コネクタです。

インストール

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 コネクタは、Go 言語で使用するように設計された AlloyDB コネクタです。

インストール

AlloyDB Go Connector は go get を使用してインストールできます。

database/sql を使用している場合は、次のコマンドを実行します。

go get cloud.google.com/go/alloydbconn

AlloyDB 言語コネクタを構成する

Java

AlloyDB Java コネクタを使用して AlloyDB クラスタに接続するには、次の手順で構成します。

このスニペットをウェブ アプリケーションのコンテキストで使用するには、GitHub の README をご覧ください。

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 Language Connectors は組み込みの認証を使用します。AlloyDB Java コネクタでは、IAM の自動認証を使用できます。有効にするには、次のコードを含めます。

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

Python（pg8000）

AlloyDB Python Connector を使用して AlloyDB クラスタに接続するには、pg8000 を使用している場合は、次の手順でコネクタを構成します。

このスニペットをウェブ アプリケーションのコンテキストで使用するには、GitHub の README をご覧ください。

import pg8000
import sqlalchemy

from google.cloud.alloydb.connector 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)

    def getconn() -> pg8000.dbapi.Connection:
        conn: pg8000.dbapi.Connection = connector.connect(
            inst_uri,
            "pg8000",
            user=user,
            password=password,
            db=db,
        )
        return conn

    # create SQLAlchemy connection pool
    engine = sqlalchemy.create_engine(
        "postgresql+pg8000://",
        creator=getconn,
    )
    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 Language Connectors は組み込みの認証を使用します。AlloyDB Python コネクタでは、IAM の自動認証を使用できます。有効にするには、接続関数を次のように置き換えます。

  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 を使用している場合は、次の手順でコネクタを構成します。

このスニペットをウェブ アプリケーションのコンテキストで使用するには、GitHub の README をご覧ください。

import asyncpg
import sqlalchemy
import sqlalchemy.ext.asyncio

from google.cloud.alloydb.connector 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)

    async def getconn() -> asyncpg.Connection:
        conn: asyncpg.Connection = await connector.connect(
            inst_uri,
            "asyncpg",
            user=user,
            password=password,
            db=db,
        )
        return conn

    # create SQLAlchemy connection pool
    engine = sqlalchemy.ext.asyncio.create_async_engine(
        "postgresql+asyncpg://",
        async_creator=getconn,
        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 の自動認証

デフォルトでは、AlloyDB Language Connectors は組み込みの認証を使用します。AlloyDB Python コネクタでは、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 を使用している場合は、次の手順でコネクタを構成します。

このスニペットをウェブ アプリケーションのコンテキストで使用するには、GitHub の README をご覧ください。

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 Language Connectors は組み込みの認証を使用します。AlloyDB Go コネクタでは、IAM の自動認証を使用できます。有効にするには、alloydbconn.NewDialer 関数を次のように置き換えます。

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

Go（database/sql）

AlloyDB Go コネクタを使用して AlloyDB クラスタに接続するには、database/sql を使用している場合は、次の手順でコネクタを構成します。

このスニペットをウェブ アプリケーションのコンテキストで使用するには、GitHub の README をご覧ください。

import (
	"database/sql"
	"fmt"

	"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,
) (*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")
	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 Language Connectors は組み込みの認証を使用します。AlloyDB Go コネクタでは、IAM の自動認証を使用できます。有効にするには、RegisterDriver 関数を次のように置き換えます。

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