AlloyDB 언어 커넥터를 사용하여 연결

AlloyDB 언어 커넥터는 다음을 사용하여 클러스터에 대한 안전한 연결을 설정하는 간소화된 프로세스를 제공하는 라이브러리입니다.

• 자동화된 mTLS 연결
• Identity and Access Management (IAM) 기반 승인 지원
• 자동화된 IAM 인증

네트워크 경로가 아직 없는 경우 AlloyDB 언어 커넥터는 AlloyDB 클러스터에 대한 네트워크 경로를 제공할 수 없습니다.

AlloyDB 언어 커넥터에 관한 자세한 내용은 AlloyDB 언어 커넥터 개요를 참고하세요.

이 페이지에서는 다음 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 언어 커넥터 설치

자바

AlloyDB Java 커넥터는 AlloyDB 인스턴스에 연결할 때 IAM 기반 승인 및 암호화를 제공하는 라이브러리입니다.

설치

Maven의 경우 프로젝트의 pom.xml에 다음을 추가하여 AlloyDB Java 커넥터를 설치할 수 있습니다.

<!-- 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 커넥터를 설치할 수 있습니다.

// 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 데이터베이스에 연결할 수 있습니다.

설치

pip install를 사용하여 AlloyDB Python 커넥터 라이브러리를 설치할 수 있습니다.

pg8000을 사용하는 경우 다음 명령어를 실행합니다.

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

Python (asyncpg)

AlloyDB Python 커넥터는 데이터베이스 드라이버와 함께 사용할 수 있는 라이브러리로, 충분한 권한이 있는 사용자가 IP를 직접 허용 목록에 추가하지 않고도 AlloyDB 데이터베이스에 연결할 수 있습니다.

설치

pip install를 사용하여 AlloyDB Python 커넥터 라이브러리를 설치할 수 있습니다.

asyncpg를 사용하는 경우 다음 명령어를 실행합니다.

asyncpg의 경우 다음을 사용합니다.

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

비동기 드라이버 사용에 관한 자세한 내용은 비동기 드라이버 사용을 참고하세요.

Go (pgx)

AlloyDB Go 커넥터는 Go 언어와 함께 사용할 수 있도록 설계된 AlloyDB 커넥터입니다.

설치

go get를 사용하여 AlloyDB Go 커넥터를 설치할 수 있습니다.

pgx를 사용하는 경우 다음 명령어를 실행합니다.

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

Go (database/sql)

AlloyDB Go 커넥터는 Go 언어와 함께 사용할 수 있도록 설계된 AlloyDB 커넥터입니다.

설치

go get를 사용하여 AlloyDB Go 커넥터를 설치할 수 있습니다.

database/sql을 사용하는 경우 다음 명령어를 실행합니다.

go get cloud.google.com/go/alloydbconn

AlloyDB 언어 커넥터 구성

자바

AlloyDB Java 커넥터를 사용하여 AlloyDB 클러스터에 연결하려면 다음 단계에 따라 구성합니다.

웹 애플리케이션의 컨텍스트에서 이 스니펫을 사용하려면 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 Language Connectors는 기본 제공 인증을 사용합니다. AlloyDB Java 커넥터에서 자동 IAM 인증을 사용할 수 있습니다. 사용 설정하려면 다음을 포함하세요.

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

Python (pg8000)

AlloyDB Python 커넥터를 사용하여 AlloyDB 클러스터에 연결하려면 pg8000를 사용하는 경우 다음 단계에 따라 커넥터를 구성합니다.

웹 애플리케이션의 컨텍스트에서 이 스니펫을 사용하려면 GitHub의 리드미를 참고하세요.

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 커넥터를 사용하여 AlloyDB 클러스터에 연결하려면 async를 사용하는 경우 다음 단계에 따라 커넥터를 구성합니다.

웹 애플리케이션의 컨텍스트에서 이 스니펫을 사용하려면 GitHub의 리드미를 참고하세요.

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 커넥터를 사용하여 AlloyDB 클러스터에 연결하려면 pgx를 사용하는 경우 다음 단계에 따라 커넥터를 구성합니다.

웹 애플리케이션의 컨텍스트에서 이 스니펫을 사용하려면 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 Language Connectors는 기본 제공 인증을 사용합니다. AlloyDB Go 커넥터에서 자동 IAM 인증을 사용할 수 있습니다. 사용 설정하려면 alloydbconn.NewDialer 함수를 다음으로 바꿉니다.

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

Go (database/sql)

AlloyDB Go 커넥터를 사용하여 AlloyDB 클러스터에 연결하려면 database/sql를 사용하는 경우 다음 단계에 따라 커넥터를 구성합니다.

웹 애플리케이션의 컨텍스트에서 이 스니펫을 사용하려면 GitHub의 리드미를 참고하세요.

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