cloudsqlconn

package module

v1.3.0 Latest Latest Go to latest Published: Jun 13, 2023 License: Apache-2.0 Imports: 23 Imported by: 58

README ¶

Cloud SQL Go Connector

The Cloud SQL Go Connector is a Cloud SQL connector designed for use with the Go language. Using a Cloud SQL connector provides the following benefits:

IAM Authorization: uses IAM permissions to control who/what can connect to your Cloud SQL instances
Improved Security: uses robust, updated 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.
(optionally) IAM DB Authentication: provides support for Cloud SQL’s automatic IAM DB AuthN feature.

For users migrating from the Cloud SQL Proxy drivers, see the migration guide.

For a quick example, try out the Go Connector in a Codelab.

Installation

You can install this repo with go get:

go get cloud.google.com/go/cloudsqlconn

Usage

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

The instance connection name for your Cloud SQL instance is always in the format project:region:instance.

APIs and Services

This package requires the following to successfully make Cloud SQL Connections:

IAM principal (user, service account, etc.) with the Cloud SQL Client role or equivalent. This IAM principal will be used for credentials.
The Cloud SQL 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 project 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 to a database

Postgres

Postgres users have the option of using the database/sql interface or using pgx directly. See pgx's advice on which to choose.

Using the dialer with pgx

To use the dialer with pgx, we recommend using connection pooling with pgxpool by configuring a Config.DialFunc like so:

import (
    "context"
    "net"

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

func connect() {
    // Configure the driver to connect to the database
    dsn := "user=myuser password=mypass dbname=mydb sslmode=disable"
    config, err := pgxpool.ParseConfig(dsn)
    if err != nil {
        /* handle error */
    }

    // Create a new dialer with any options
    d, err := cloudsqlconn.NewDialer(context.Background())
    if err != nil {
        /* handle error */
    }

    // Tell the driver to use the Cloud SQL Go Connector to create connections
    config.ConnConfig.DialFunc = func(ctx context.Context, _ string, instance string) (net.Conn, error) {
        return d.Dial(ctx, "project:region:instance")
    }

    // Interact with the driver directly as you normally would
    conn, err := pgxpool.ConnectConfig(context.Background(), config)
    if err != nil {
        /* handle error */
    }

    // call cleanup when you're done with the database connection
    cleanup := func() error { return d.Close() }
    // ... etc
}

Using the dialer with `database/sql`

To use database/sql, call 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. The returned cleanup func will stop the dialer's background refresh goroutine and so should only be called when you're done with the Dialer.

import (
    "database/sql"

    "cloud.google.com/go/cloudsqlconn"
    "cloud.google.com/go/cloudsqlconn/postgres/pgxv4"
)

func connect() {
    cleanup, err := pgxv4.RegisterDriver("cloudsql-postgres", cloudsqlconn.WithIAMAuthN())
    if err != nil {
        // ... handle error
    }
    // call cleanup when you're done with the database connection
    defer cleanup()

    db, err := sql.Open(
        "cloudsql-postgres",
        "host=project:region:instance user=myuser password=mypass dbname=mydb sslmode=disable",
    )
    // ... etc
}

MySQL

To use database/sql, use mysql.RegisterDriver with any necessary Dialer configuration. The returned cleanup func will stop the dialer's background refresh goroutine and so should only be called when you're done with the Dialer.

import (
    "database/sql"

    "cloud.google.com/go/cloudsqlconn"
    "cloud.google.com/go/cloudsqlconn/mysql/mysql"
)

func connect() {
    cleanup, err := mysql.RegisterDriver("cloudsql-mysql", cloudsqlconn.WithCredentialsFile("key.json"))
    if err != nil {
        // ... handle error
    }
    // call cleanup when you're done with the database connection
    defer cleanup()

    db, err := sql.Open(
        "cloudsql-mysql",
        "myuser:mypass@cloudsql-mysql(project:region:instance)/mydb",
    )
    // ... etc
}

SQL Server

To use database/sql, use mssql.RegisterDriver with any necessary Dialer configuration. The returned cleanup func will stop the dialer's background refresh goroutine and so should only be called when you're done with the Dialer.

import (
    "database/sql"

    "cloud.google.com/go/cloudsqlconn"
    "cloud.google.com/go/cloudsqlconn/sqlserver/mssql"
)

func connect() {
    cleanup, err := mssql.RegisterDriver("cloudsql-sqlserver", cloudsqlconn.WithCredentialsFile("key.json"))
    if err != nil {
        // ... handle error
    }
    // call cleanup when you're done with the database connection
    defer cleanup()

    db, err := sql.Open(
        "cloudsql-sqlserver",
        "sqlserver://user:password@localhost?database=mydb&cloudsql=project:region:instance",
    )
    // ... etc
}

Using Options

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

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

conn, err := d.Dial(ctx, "project:region:instance")

For a full list of customizable behavior, see Option.

Using DialOptions

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

conn, err := d.Dial(
    ctx,
    "project:region:instance",
    cloudsqlconn.WithPrivateIP(),
)

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

d, err := cloudsqlconn.NewDialer(
    ctx,
    cloudsqlconn.WithDefaultDialOptions(
        cloudsqlconn.WithPrivateIP(),
    ),
)

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:

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

Supported traces include:

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

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

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 cloudsqlconn 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.

Documentation ¶

Overview ¶

Package cloudsqlconn contains methods for creating secure, authorized connections to a Cloud SQL instance.

Index ¶

type DialOption
type Dialer
- func NewDialer(ctx context.Context, opts ...Option) (*Dialer, error)
type Option

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

This section is empty.

Types ¶

type DialOption ¶

type DialOption func(d *dialCfg)

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

func DialOptions ¶

func DialOptions(opts ...DialOption) DialOption

DialOptions turns a list of DialOption instances into an DialOption.

func WithAutoIP ¶ added in v1.0.0

func WithAutoIP() DialOption

WithAutoIP returns a DialOption that selects the public IP if available and otherwise falls back to private IP. This option is present for backwards compatibility only and is not recommended for use in production.

func WithDialIAMAuthN ¶ added in v0.4.0

func WithDialIAMAuthN(b bool) DialOption

WithDialIAMAuthN allows you to enable or disable IAM Authentication for this instance as descibed in the documentation for WithIAMAuthN. This value will overide the Dialer-level configuration set with WithIAMAuthN.

WARNING: This DialOption can cause a new Refresh operation to be triggered. Toggling this option on or off between Dials may cause increased API usage and/or delayed connection attempts.

func WithOneOffDialFunc ¶ added in v1.3.0

func WithOneOffDialFunc(dial func(ctx context.Context, network, addr string) (net.Conn, error)) 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.

func WithPrivateIP ¶

func WithPrivateIP() DialOption

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

func WithPublicIP ¶

func WithPublicIP() DialOption

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

func WithTCPKeepAlive ¶

func WithTCPKeepAlive(d time.Duration) DialOption

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

type Dialer ¶

type Dialer struct {
	// contains filtered or unexported fields
}

A Dialer is used to create connections to Cloud SQL instances.

Use NewDialer to initialize a Dialer.

func NewDialer ¶

func NewDialer(ctx context.Context, opts ...Option) (*Dialer, error)

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.

func (*Dialer) Close ¶

func (d *Dialer) Close() error

Close closes the Dialer; it prevents the Dialer from refreshing the information needed to connect. Additional dial operations may succeed until the information expires.

func (*Dialer) Dial ¶

func (d *Dialer) Dial(ctx context.Context, instance string, opts ...DialOption) (conn net.Conn, err error)

Dial returns a net.Conn connected to the specified Cloud SQL instance. The instance argument must be the instance's connection name, which is in the format "project-name:region:instance-name".

func (*Dialer) EngineVersion ¶

func (d *Dialer) EngineVersion(ctx context.Context, instance string) (string, error)

EngineVersion returns the engine type and version for the instance. The value will correspond to one of the following types for the instance: https://cloud.google.com/sql/docs/mysql/admin-api/rest/v1beta4/SqlDatabaseVersion

func (*Dialer) Warmup ¶ added in v0.4.0

func (d *Dialer) Warmup(_ context.Context, instance string, opts ...DialOption) error

Warmup starts the background refresh necessary to connect to the instance. Use Warmup to start the refresh process early if you don't know when you'll need to call "Dial".

type Option ¶

type Option func(d *dialerConfig)

An Option is an option for configuring a Dialer.

func WithAdminAPIEndpoint ¶ added in v0.3.0

func WithAdminAPIEndpoint(url string) Option

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

func WithCredentialsFile ¶

func WithCredentialsFile(filename string) Option

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

func WithCredentialsJSON ¶

func WithCredentialsJSON(b []byte) Option

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

func WithDefaultDialOptions ¶

func WithDefaultDialOptions(opts ...DialOption) Option

WithDefaultDialOptions returns an Option that specifies the default DialOptions used.

func WithDialFunc ¶

func WithDialFunc(dial func(ctx context.Context, network, addr string) (net.Conn, error)) Option

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.

func WithHTTPClient ¶

func WithHTTPClient(client *http.Client) Option

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

func WithIAMAuthN ¶

func WithIAMAuthN() Option

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.

For documentation on automatic IAM Authentication, see https://cloud.google.com/sql/docs/postgres/authentication.

func WithIAMAuthNTokenSources ¶ added in v1.0.0

func WithIAMAuthNTokenSources(apiTS, iamLoginTS oauth2.TokenSource) Option

WithIAMAuthNTokenSources sets the oauth2.TokenSource for the API client and a second token source for IAM AuthN login tokens. The API client token source should have the following scopes:

The IAM AuthN token source on the other hand should only have:

https://www.googleapis.com/auth/sqlservice.login.

Prefer this option over WithTokenSource when using IAM AuthN which does not distinguish between the two token sources. WithIAMAuthNTokenSources should not be used with WithTokenSource.

func WithOptions ¶

func WithOptions(opts ...Option) Option

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

func WithQuotaProject ¶ added in v0.5.0

func WithQuotaProject(p string) Option

WithQuotaProject returns an Option that specifies the project used for quota and billing purposes.

func WithRSAKey ¶

func WithRSAKey(k *rsa.PrivateKey) Option

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

func WithRefreshTimeout ¶

func WithRefreshTimeout(t time.Duration) Option

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

func WithTokenSource ¶

func WithTokenSource(s oauth2.TokenSource) Option

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

When Auth IAM AuthN is enabled, use WithIAMAuthNTokenSources to set the token source for login tokens separately from the API client token source. WithTokenSource should not be used with WithIAMAuthNTokenSources.

func WithUserAgent ¶ added in v0.3.0

func WithUserAgent(ua string) Option

WithUserAgent returns an Option that sets the User-Agent.

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
errtype Package errtype provides a number of concrete types which are used by the cloudsqlconn package.	Package errtype provides a number of concrete types which are used by the cloudsqlconn package.
internal
cloudsql
mock
trace
mysql Package mysql provides a Cloud SQL MySQL driver that uses go-sql-driver/mysql and works with database/sql	Package mysql provides a Cloud SQL MySQL driver that uses go-sql-driver/mysql and works with database/sql
postgres
pgxv4 Package pgxv4 provides a Cloud SQL Postgres driver that uses pgx v4 and works with the database/sql package.	Package pgxv4 provides a Cloud SQL Postgres driver that uses pgx v4 and works with the database/sql package.
sqlserver
mssql Package mssql provides a Cloud SQL SQL Server driver that works with the database/sql package.	Package mssql provides a Cloud SQL SQL Server driver that works with the database/sql package.

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

README ¶

Cloud SQL Go Connector

Installation

Usage

APIs and Services

Credentials

Connecting to a database

Postgres

Using the dialer with pgx

Using the dialer with database/sql

MySQL

SQL Server

Using Options

Using DialOptions

Enabling Metrics and Tracing

Support policy

Major version lifecycle

Supported Go Versions

Release cadence

Documentation ¶

Overview ¶

Index ¶

Constants ¶

Variables ¶

Functions ¶

Types ¶

type DialOption ¶

func DialOptions ¶

func WithAutoIP ¶ added in v1.0.0

func WithDialIAMAuthN ¶ added in v0.4.0

func WithOneOffDialFunc ¶ added in v1.3.0

func WithPrivateIP ¶

func WithPublicIP ¶

func WithTCPKeepAlive ¶

type Dialer ¶

func NewDialer ¶

func (*Dialer) Close ¶

func (*Dialer) Dial ¶

func (*Dialer) EngineVersion ¶

func (*Dialer) Warmup ¶ added in v0.4.0

type Option ¶

func WithAdminAPIEndpoint ¶ added in v0.3.0

func WithCredentialsFile ¶

func WithCredentialsJSON ¶

func WithDefaultDialOptions ¶

func WithDialFunc ¶

func WithHTTPClient ¶

func WithIAMAuthN ¶

func WithIAMAuthNTokenSources ¶ added in v1.0.0

func WithOptions ¶

func WithQuotaProject ¶ added in v0.5.0

func WithRSAKey ¶

func WithRefreshTimeout ¶

func WithTokenSource ¶

func WithUserAgent ¶ added in v0.3.0

Source Files ¶

Directories ¶

Using the dialer with `database/sql`