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.
You can install this repo with go get
:
go get cloud.google.com/go/cloudsqlconn
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".
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.
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.
To use the dialer with pgx, use 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 */
}
defer d.Close()
// 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 dirver directly as you normally would
conn, err := pgxpool.ConnectConfig(context.Background(), config)
if err != nil {
/* handle error */
}
// ... etc
}
The Go MySQL driver does not provide a stand-alone interface for
interacting with a database and instead uses database/sql
. See the section
below on how to use the database/sql
package with a Cloud SQL MySQL
instance.
Go-mssql does not provide a stand-alone interface for interacting
with a database and instead uses database/sql
. See the section below
on how to use the database/sql
package with a Cloud SQL SQL Server instance.
If you need to customize something about the Dialer
, you can initialize
directly with NewDialer
:
myDialer, err := cloudsqlconn.NewDialer(
ctx,
cloudsqlconn.WithCredentialsFile("key.json"),
)
if err != nil {
log.Fatalf("unable to initialize dialer: %s", err)
}
conn, err := myDialer.Dial(ctx, "project:region:instance")
For a full list of customizable behavior, see Option.
If you want to customize things about how the connection is created, use
Option
:
conn, err := myDialer.Dial(
ctx,
"project:region:instance",
cloudsqlconn.WithPrivateIP(),
)
You can also use the WithDefaultDialOptions
Option to specify
DialOptions to be used by default:
myDialer, err := cloudsqlconn.NewDialer(
ctx,
cloudsqlconn.WithDefaultDialOptions(
cloudsqlconn.WithPrivateIP(),
),
)
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.
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
}
defer cleanup()
db, err := sql.Open(
"cloudsql-postgres",
"host=project:region:instance user=myuser password=mypass dbname=mydb sslmode=disable",
)
// ... etc
}
To use database/sql
, use mysql.RegisterDriver
with any necessary Dialer
configuration.
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
}
defer cleanup()
db, err := sql.Open(
"cloudsql-mysql",
"myuser:mypass@cloudsql-mysql(my-project:us-central1:my-instance)/mydb",
)
// ... etc
}
To use database/sql
, use mssql.RegisterDriver
with any necessary Dialer
configuration.
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
}
defer cleanup()
db, err := sql.Open(
"cloudsql-sqlserver",
"sqlserver://user:password@localhost?database=mydb&cloudsql=my-proj:us-central1:my-inst",
)
// ... etc
}
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 connectionscloudsqlconn/dial_failure_count
: The number of failed dial attemptscloudsqlconn/refresh_success_count
: The number of successful certificate refresh operationscloudsqlconn/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 instancecloud.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.
// ...
}
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.
We test and support at minimum, the latest three Go versions. Changes in supported Go versions will be considered a minor change, and will be listed in the realease notes.
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.