Cloud SQL Go Connector

The library supports observability via OpenCensus. It is highly recommended to use the OpenTelemetry bridge to migrate to OpenTelemetry.

Supported Metrics

• cloudsqlconn/dial_latency: Dialer latencies (ms)
• cloudsqlconn/open_connections: Current number of open connections
• cloudsqlconn/dial_failure_count: Failed dial attempts
• cloudsqlconn/refresh_success_count: Successful certificate refreshes
• cloudsqlconn/refresh_failure_count: Failed certificate refreshes
• cloudsqlconn/bytes_sent: Bytes sent to Cloud SQL
• cloudsqlconn/bytes_received: Bytes received from Cloud SQL

Supported Traces

• cloud.google.com/go/cloudsqlconn.Dial: The dial operation (includes certificate refresh and connection)
• cloud.google.com/go/cloudsqlconn/internal.InstanceInfo: Retrieving instance metadata
• cloud.google.com/go/cloudsqlconn/internal.Connect: The connection attempt using the ephemeral certificate
• SQL Admin API client operations

To migrate MySQL connections, replace the github.com/GoogleCloudPlatform/cloudsql-proxy/proxy/dialers/mysql package with cloud.google.com/go/cloudsqlconn/mysql/mysql.

Unlike the v1 proxy, the Go Connector uses a driver registration pattern. You must call mysql.RegisterDriver with a custom driver name and any desired cloudsqlconn options (e.g., cloudsqlconn.WithCredentialsFile). This function returns a cleanup function that must be deferred to close the underlying driver when the application is finished. Finally, use sql.Open with the name you provided during registration.

import (
	"database/sql"
	"cloud.google.com/go/cloudsqlconn"
	"cloud.google.com/go/cloudsqlconn/mysql/mysql"
)

func connectMySQL() *sql.DB {
	// Register a driver using whatever name you like.
	cleanup, err := mysql.RegisterDriver(
		"cloudsql-mysql",
		// any desired options go here, for example:
		cloudsqlconn.WithCredentialsFile("key.json"),
	)
	if err != nil {
		// handle error as necessary
	}
	// call cleanup to close the underylying driver when you're done with the
	// db.
	defer cleanup()

	db, err := sql.Open(
		"cloudsql-mysql", // matches the name registered above
		"myuser:mypass@cloudsql-mysql(project:region:instance)/mydb",
	)
	if err != nil {
		// handle error as necessary
	}
	return db
}

The connector can use DNS to identify instances, enabling automatic failover. You can use Cloud SQL Advanced Disaster Recovery write endpoints or your own managed DNS records.

Configure DNS Records

Add a private TXT record to your DNS server.

• Name: The domain name used by your application (e.g., prod-db.mycompany.example.com).
• Value: The Cloud SQL instance connection name (e.g., my-project:region:my-instance).

Warning: Do not use public DNS servers, as this exposes your instance name to the internet.

Automatic Failover Behavior

When the connector is configured with cloudsqlconn.WithDNSResolver(), it periodically polls for changes to the DNS record (default every 30 seconds). If the record changes, the connector closes existing connections to the old instance, forcing the connection pool to reconnect to the new instance specified in the DNS record.

To adjust the polling frequency, use WithFailoverPeriod(d time.Duration). Setting this to 0 disables polling and only checks for changes during new connection attempts.

package main

import (
	"database/sql"

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

func connect() {
	cleanup, err := mysql.RegisterDriver("cloudsql-mysql",
		cloudsqlconn.WithDNSResolver())
	if err != nil {
		// ... handle error
	}
	defer cleanup()

	db, err := sql.Open(
		"cloudsql-mysql",
		"myuser:mypass@cloudsql-mysql(prod-db.mycompany.example.com)/mydb",
    )
    // ... etc
}

The connector supports automatic IAM database authentication for Postgres and MySQL. This requires your Cloud SQL instance to be configured to allow IAM authentication and the appropriate IAM user/service account to be added to the database.

To enable this, use the WithIAMAuthN() option when creating a Dialer or the WithDialIAMAuthN DialOption.

DSN Configuration for IAM

When using IAM authentication, omit the password field in your DSN. The user field must be formatted as follows:

• Postgres:
  • IAM User: The user's email address.
  • Service Account: The service account's email without the .gserviceaccount.com suffix.
  • Example: user=test-sa@test-project.iam dbname=mydb sslmode=disable
• MySQL:
  • IAM User: The user's email address without the @ or domain name (e.g., test-user for test-user@gmail.com).
  • Service Account: The service account's email without the @project-id.iam.gserviceaccount.com suffix.
  • Example: user=test-sa dbname=mydb sslmode=disable

To migrate Postgres connections, replace the github.com/GoogleCloudPlatform/cloudsql-proxy/proxy/dialers/postgres package with cloud.google.com/go/cloudsqlconn/postgres/pgxv5.

Use pgxv5.RegisterDriver to register a driver name and configure options like cloudsqlconn.WithIAMAuthN(). You must defer the returned cleanup function. When calling sql.Open, use the registered driver name and a connection string that includes the instance connection name as the host.

import (
	"database/sql"
	"cloud.google.com/go/cloudsqlconn"
	"cloud.google.com/go/cloudsqlconn/postgres/pgxv5"
)

func connectPostgres() *sql.DB {
	// Register a driver using whatever name you like.
	cleanup, err := pgxv5.RegisterDriver(
		"cloudsql-postgres",
		// any desired options go here, for example:
		cloudsqlconn.WithCredentialsFile("key.json"),
		cloudsqlconn.WithIAMAuthN(),
	)
	if err != nil {
		// handle error as necessary
	}
	// call cleanup to close the underylying driver when you're done with the
	// db.
	defer cleanup()
	db, err := sql.Open(
		"cloudsql-postgres", // matches the name registered above
		"host=project:region:instance user=postgres password=password dbname=postgres sslmode=disable",
	)
	if err != nil {
		// handle error as necessary
	}
	return db
}