Package cloud.google.com/go/alloydbconn (v1.10.0)

Package alloydbconn provides functions for authorizing and encrypting connections. These functions can be used with a database driver to connect to an AlloyDB cluster.

Creating a Dialer

To start working with this package, create a Dialer. There are two ways of creating a Dialer, which one you use depends on your database driver.

Users have the option of using the database/sql interface or using pgx directly.

To use a dialer with pgx, we recommend using connection pooling with pgxpool. To create the dialer use the NewDialer func.

import (
    "context"
    "net"

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

func connect() {
    // Configure the driver to connect to the database
    dsn := fmt.Sprintf("user=%s password=%s dbname=%s sslmode=disable", pgUser, pgPass, pgDB)
    config, err := pgxpool.ParseConfig(dsn)
    if err != nil {
        log.Fatalf("failed to parse pgx config: %v", err)
    }

    // Create a new dialer with any options
    d, err := alloydbconn.NewDialer(ctx)
    if err != nil {
        log.Fatalf("failed to initialize dialer: %v", err)
    }
    defer d.Close()

    // Tell the driver to use the AlloyDB Go Connector to create connections
    config.ConnConfig.DialFunc = func(ctx context.Context, _ string, instance string) (net.Conn, error) {
        return d.Dial(ctx, "projects/<PROJECT>/locations/<REGION>/clusters/<CLUSTER>/instances/<INSTANCE>")
    }

    // Interact with the driver directly as you normally would
    conn, err := pgxpool.ConnectConfig(context.Background(), config)
    if err != nil {
        log.Fatalf("failed to connect: %v", connErr)
    }
    defer conn.Close()
}

To use database/sql, call pgxv4.RegisterDriver with any necessary Dialer configuration.

import (
    "database/sql"

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

func connect() {
    // adjust options as needed
    cleanup, err := pgxv4.RegisterDriver("alloydb")
    if err != nil {
        // ... handle error
    }
    defer cleanup()

    db, err := sql.Open(
        "alloydb",
        "host=projects/<PROJECT>/locations/<REGION>/clusters/<CLUSTER>/instances/<INSTANCE> user=myuser password=mypass dbname=mydb sslmode=disable",
    )
    //... etc
}

CloudPlatformScope is the default OAuth2 scope set on the API client.

A DialOption is an option for configuring how a Dialer's Dial call is executed.

DialOptions turns a list of DialOption instances into an DialOption.

WithOneOffDialFunc configures the dial function on a one-off basis for an individual call to Dial. To configure a dial function across all invocations of Dial, use WithDialFunc.

WithPSC returns a DialOption that specifies a PSC endpoint will be used to connect.

WithPrivateIP returns a DialOption that specifies a private IP (VPC) will be used to connect.

WithPublicIP returns a DialOption that specifies a public IP will be used to connect.

WithTCPKeepAlive returns a DialOption that specifies the tcp keep alive period for the connection returned by Dial.

A Dialer is used to create connections to AlloyDB instance.

Use NewDialer to initialize a Dialer.

NewDialer creates a new Dialer.

Initial calls to NewDialer make take longer than normal because generation of an RSA keypair is performed. Calls with a WithRSAKeyPair DialOption or after a default RSA keypair is generated will be faster.

Close closes the Dialer; it prevents the Dialer from refreshing the information needed to connect.

Dial returns a net.Conn connected to the specified AlloyDB instance. The instance argument must be the instance's URI, which is in the format projects/

An Option is an option for configuring a Dialer.

WithAdminAPIEndpoint configures the underlying AlloyDB Admin API client to use the provided URL.

WithContextLogger configures a debug lgoger for reporting on internal operations. By default the debug logger is disabled.

WithCredentialsFile returns an Option that specifies a service account or refresh token JSON credentials file to be used as the basis for authentication.

WithCredentialsJSON returns an Option that specifies a service account or refresh token JSON credentials to be used as the basis for authentication.

WithDebugLogger configures a debug logger for reporting on internal operations. By default the debug logger is disabled. Prefer WithContextLogger.

WithDefaultDialOptions returns an Option that specifies the default DialOptions used.

WithDialFunc configures the function used to connect to the address on the named network. This option is generally unnecessary except for advanced use-cases. The function is used for all invocations of Dial. To configure a dial function per individual calls to dial, use WithOneOffDialFunc.

WithHTTPClient configures the underlying AlloyDB Admin API client with the provided HTTP client. This option is generally unnecessary except for advanced use-cases.

WithIAMAuthN enables automatic IAM Authentication. If no token source has been configured (such as with WithTokenSource, WithCredentialsFile, etc), the dialer will use the default token source as defined by https://pkg.go.dev/golang.org/x/oauth2/google#FindDefaultCredentialsWithParams.

WithLazyRefresh configures the dialer to refresh certificates on an as-needed basis. If a certificate is expired when a connection request occurs, the Go Connector will block the attempt and refresh the certificate immediately. This option is useful when running the Go Connector in environments where the CPU may be throttled, thus preventing a background goroutine from running consistently (e.g., in Cloud Run the CPU is throttled outside of a request context causing the background refresh to fail).

WithOptions turns a list of Option's into a single Option.

WithRSAKey returns an Option that specifies a rsa.PrivateKey used to represent the client.

WithRefreshTimeout returns an Option that sets a timeout on refresh operations. Defaults to 60s.

WithStaticConnectionInfo specifies an io.Reader from which to read static connection info. This is a dev-only option and should not be used in production as it will result in failed connections after the client certificate expires. It is also subject to breaking changes in the format. NOTE: The static connection info is not refreshed by the dialer. The JSON format supports multiple instances, regardless of cluster.

The reader should hold JSON with the following format:

{
    "publicKey": "<PEM Encoded public RSA key>",
    "privateKey": "<PEM Encoded private RSA key>",
    "projects/<PROJECT>/locations/<REGION>/clusters/<CLUSTER>/instances/<INSTANCE>": {
        "ipAddress": "<PSA-based private IP address>",
        "publicIpAddress": "<public IP address>",
        "pscInstanceConfig": {
            "pscDnsName": "<PSC DNS name>"
        },
        "pemCertificateChain": [
            "<client cert>", "<intermediate cert>", "<CA cert>"
        ],
        "caCert": "<CA cert>"
    }
}

WithTokenSource returns an Option that specifies an OAuth2 token source to be used as the basis for authentication.

WithUserAgent returns an Option that sets the User-Agent.