github.com/kurtisvg/cloud-sql-connector-go
go get github.com/kurtisvg/cloud-sql-connector-go

github.com/kurtisvg/cloud-sql-connector-go

by GoogleCloudPlatform

v0.0.0-20211117173358-4cb523e80b4a (see all)License:Apache-2.0
go get github.com/kurtisvg/cloud-sql-connector-go
Readme

cloud-sql-go-connector

Warning: This project is in Public Preview, and may contain breaking changes before it becomes Generally Available.

CI Go Reference

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.3git stat 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 Authenticiation: provides support for Cloud SQL’s automatic IAM DB AuthN feature.

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

Credentials

This repo uses the Application Default Credentials (ADC) strategy for typing providing credentials. Please see the golang.org/x/oauth2/google documentation for more information in how these credentials are sourced.

To explicitly set a specific source for the Credentials to use, see Using Option below.

Using the default Dialer

If you don't need to customize your Dialer's behavior, it is convenient to use the package's "Dial" option, which initializes a default dialer for you.

pgx for Postgres

To use the dialer with pgx, configure the pgConn.DialFunc field to create connections:

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

// Tell the driver to use the Cloud SQL Go Connector to create connections
d, err := cloudsqlconn.NewDialer(ctx)
if err != nil {
    log.Fatalf("failed to initialize dialer: %v", err)
}
defer d.Close()
config.DialFunc = func(ctx context.Context, network string, instance string) (net.Conn, error) {
    return d.Dial(ctx, "project:region:instance")
}

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

go-sql-driver/mysql for MySQL

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.

SQL Server Support

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.

Using Options

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.

Using DialOptions

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

Postgres

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/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
}

MySQL

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

package foo

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
}

SQL Server

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

package foo

import (
    "database/sql"

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

func Connect() {
    cleanup, err := sqlserver.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
}

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.

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 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 support the latest four Go versions. Changes in supported Go versions will be considered a minor change.

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.

GitHub Stars

12

LAST COMMIT

3mos ago

MAINTAINERS

0

CONTRIBUTORS

7

OPEN ISSUES

5

OPEN PRs

4
VersionTagPublished
v0.0.0-20211117173358-4cb523e80b4a
6mos ago
v0.0.0-20211111184826-de9e72e1dc69
6mos ago
v0.0.0-20211025210206-86f37d7a784a
7mos ago
v0.0.0-20210816203428-f2de1e09208e
9mos ago
No alternatives found
No tutorials found
Add a tutorial