AlloyDB Go Connector

The AlloyDB Go Connector is an AlloyDB connector designed for use with the Go language. Using an AlloyDB connector provides the following benefits:

• IAM Authorization: uses IAM permissions to control who/what can connect to your AlloyDB instances

• Improved Security: uses TLS 1.3 encryption and identity verification between the client connector and the server-side proxy, independent of the database protocol.

• Convenience: removes the requirement to use and distribute SSL certificates, as well as manage firewalls or source/destination IP addresses.

Installation

You can install this repo with go get:

go get cloud.google.com/go/alloydbconn

Usage

This package provides several functions for authorizing and encrypting connections. These functions can be used with your database driver to connect to your AlloyDB instance.

AlloyDB supports network connectivity through private, internal IP addresses only. This package must be run in an environment that is connected to the VPC Network that hosts your AlloyDB private IP address.

Please see Configuring AlloyDB Connectivity for more details.

APIs and Services

This package requires the following to connect successfully:

• IAM principal (user, service account, etc.) with the AlloyDB Client role or equivalent. Credentials for the IAM principal are used to authorize connections to an AlloyDB instance.

• The AlloyDB Admin API to be enabled within your Google Cloud Project. By default, the API will be called in the project associated with the IAM principal.

Credentials

This repo uses the Application Default Credentials (ADC) strategy for resolving credentials. Please see these instructions for how to set your ADC (Google Cloud Application vs Local Development, IAM user vs service account credentials), or consult the golang.org/x/oauth2/google documentation.

To explicitly set a specific source for the Credentials, see Using Options below.

Connecting with pgx

To use the dialer with pgx, use pgxpool by configuring a Config.DialFunc like so:

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

Using Options

If you need to customize something about the Dialer, you can initialize directly with NewDialer:

ctx := context.Background()
d, err := alloydbconn.NewDialer(
    ctx,
    alloydbconn.WithCredentialsFile("key.json"),
)
if err != nil {
    log.Fatalf("unable to initialize dialer: %s", err)
}

conn, err := d.Dial(ctx, "projects/<PROJECT>/locations/<REGION>/clusters/<CLUSTER>/instances/<INSTANCE>")

For a full list of customizable behavior, see alloydbconn.Option.

Using DialOptions

If you want to customize things about how the connection is created, use DialOption:

conn, err := d.Dial(
    ctx,
    "projects/<PROJECT>/locations/<REGION>/clusters/<CLUSTER>/instances/<INSTANCE>",
    alloydbconn.WithTCPKeepAlive(30*time.Second),
)

You can also use the WithDefaultDialOptions Option to specify DialOptions to be used by default:

d, err := alloydbconn.NewDialer(
    ctx,
    alloydbconn.WithDefaultDialOptions(
        alloydbconn.WithTCPKeepAlive(30*time.Second),
    ),
)

Using the dialer with database/sql

Using the dialer directly will expose more configuration options. However, it is possible to use the dialer with the database/sql package.

To use database/sql, use pgxv4.RegisterDriver with any necessary Dialer configuration. Note: the connection string must use the keyword/value format with host set to the instance connection name.

package foo

import (
    "database/sql"

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

func Connect() {
    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
}

Enabling Metrics and Tracing

This library includes support for metrics and tracing using OpenCensus. To enable metrics or tracing, you need to configure an exporter. OpenCensus supports many backends for exporters.

Supported metrics include:

• alloydbconn/dial_latency: The distribution of dialer latencies (ms)
• alloydbconn/open_connections: The current number of open AlloyDB connections
• alloydbconn/dial_failure_count: The number of failed dial attempts
• alloydbconn/refresh_success_count: The number of successful certificate refresh operations
• alloydbconn/refresh_failure_count: The number of failed refresh operations.

Supported traces include:

• cloud.google.com/go/alloydbconn.Dial: The dial operation including refreshing an ephemeral certificate and connecting to the instance
• cloud.google.com/go/alloydbconn/internal.InstanceInfo: The call to retrieve instance metadata (e.g., IP address, etc)
• cloud.google.com/go/alloydbconn/internal.Connect: The connection attempt using the ephemeral certificate
• AlloyDB API client operations

For example, to use Cloud Monitoring and Cloud Trace, you would configure an exporter like so:

package main

import (
    "contrib.go.opencensus.io/exporter/stackdriver"
    "go.opencensus.io/trace"
)

func main() {
    sd, err := stackdriver.NewExporter(stackdriver.Options{
        ProjectID: "mycoolproject",
    })
    if err != nil {
        // handle error
    }
    defer sd.Flush()
    trace.RegisterExporter(sd)

    sd.StartMetricsExporter()
    defer sd.StopMetricsExporter()

    // Use alloydbconn as usual.
    // ...
}

Support policy

Major version lifecycle

This project uses semantic versioning, and uses the following lifecycle regarding support for a major version:

Active - Active versions get all new features and security fixes (that wouldn’t otherwise introduce a breaking change). New major versions are guaranteed to be "active" for a minimum of 1 year.

Deprecated - Deprecated versions continue to receive security and critical bug fixes, but do not receive new features. Deprecated versions will be supported for 1 year.

Unsupported - Any major version that has been deprecated for >=1 year is considered unsupported.

Supported Go Versions

We follow the Go Version Support Policy used by Google Cloud Libraries for Go.

Release cadence

This project aims for a release on at least a monthly basis. If no new features or fixes have been added, a new PATCH version with the latest dependencies is released.