Package cloud.google.com/go/cloudsqlconn (v1.0.1)

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

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

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

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

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 corespond to one of the following types for the instance: https://cloud.google.com/sql/docs/mysql/admin-api/rest/v1beta4/SqlDatabaseVersion

func (*Dialer) Warmup

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

Warmup starts the background refresh neccesary 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".

Option

type Option func(d *dialerConfig)

An Option is an option for configuring a Dialer.

func WithAdminAPIEndpoint

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.

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

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:

  1. https://www.googleapis.com/auth/sqlservice.admin, and
  2. https://www.googleapis.com/auth/cloud-platform

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

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

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

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

func WithUserAgent(ua string) Option

WithUserAgent returns an Option that sets the User-Agent.