1 // Copyright 2023 Google LLC 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 // Package cloudsqlconn provides functions for authorizing and encrypting 16 // connections. These functions can be used with a database driver to 17 // connect to a Cloud SQL instance. 18 // 19 // The instance connection name for a Cloud SQL instance is always in the 20 // format "project:region:instance". 21 // 22 // # Creating a Dialer 23 // 24 // To start working with this package, create a Dialer. There are two ways of 25 // creating a Dialer, which one you use depends on your database driver. 26 // 27 // # Postgres 28 // 29 // Postgres users have the option of using the [database/sql] interface or using [pgx] directly. 30 // 31 // To use a dialer with [pgx], we recommend using connection pooling with 32 // [pgxpool]. To create the dialer use the NewDialer func. 33 // 34 // import ( 35 // "context" 36 // "net" 37 // 38 // "cloud.google.com/go/cloudsqlconn" 39 // "github.com/jackc/pgx/v4/pgxpool" 40 // ) 41 // 42 // func connect() { 43 // // Configure the driver to connect to the database 44 // dsn := "user=myuser password=mypass dbname=mydb sslmode=disable" 45 // config, err := pgxpool.ParseConfig(dsn) 46 // if err != nil { 47 // // handle error 48 // } 49 // 50 // // Create a new dialer with any options 51 // d, err := cloudsqlconn.NewDialer(context.Background()) 52 // if err != nil { 53 // // handle error 54 // } 55 // 56 // // Tell the driver to use the Cloud SQL Go Connector to create connections 57 // config.ConnConfig.DialFunc = func(ctx context.Context, _ string, instance string) (net.Conn, error) { 58 // return d.Dial(ctx, "project:region:instance") 59 // } 60 // 61 // // Interact with the driver directly as you normally would 62 // conn, err := pgxpool.ConnectConfig(context.Background(), config) 63 // if err != nil { 64 // // handle error 65 // } 66 // 67 // // call cleanup when you're done with the database connection 68 // cleanup := func() error { return d.Close() } 69 // // ... etc 70 // } 71 // 72 // To use [database/sql], call pgxv4.RegisterDriver with any necessary Dialer 73 // configuration. 74 // 75 // Note: the connection string must use the keyword/value format 76 // with host set to the instance connection name. The returned cleanup func 77 // will stop the dialer's background refresh goroutine and so should only be 78 // called when you're done with the Dialer. 79 // 80 // import ( 81 // "database/sql" 82 // 83 // "cloud.google.com/go/cloudsqlconn" 84 // "cloud.google.com/go/cloudsqlconn/postgres/pgxv4" 85 // ) 86 // 87 // func connect() { 88 // // adjust options as needed 89 // cleanup, err := pgxv4.RegisterDriver("cloudsql-postgres", cloudsqlconn.WithIAMAuthN()) 90 // if err != nil { 91 // // ... handle error 92 // } 93 // // call cleanup when you're done with the database connection 94 // defer cleanup() 95 // 96 // db, err := sql.Open( 97 // "cloudsql-postgres", 98 // "host=project:region:instance user=myuser password=mypass dbname=mydb sslmode=disable", 99 // ) 100 // // ... etc 101 // } 102 // 103 // # MySQL 104 // 105 // MySQL users should use [database/sql]. Use mysql.RegisterDriver with any 106 // necessary Dialer configuration. 107 // 108 // Note: The returned cleanup func will stop the dialer's background refresh 109 // goroutine and should only be called when you're done with the Dialer. 110 // 111 // import ( 112 // "database/sql" 113 // 114 // "cloud.google.com/go/cloudsqlconn" 115 // "cloud.google.com/go/cloudsqlconn/mysql/mysql" 116 // ) 117 // 118 // func connect() { 119 // // adjust options as needed 120 // cleanup, err := mysql.RegisterDriver("cloudsql-mysql", cloudsqlconn.WithIAMAuthN()) 121 // if err != nil { 122 // // ... handle error 123 // } 124 // // call cleanup when you're done with the database connection 125 // defer cleanup() 126 // 127 // db, err := sql.Open( 128 // "cloudsql-mysql", 129 // "myuser:mypass@cloudsql-mysql(project:region:instance)/mydb", 130 // ) 131 // // ... etc 132 // } 133 // 134 // # SQL Server 135 // 136 // SQL Server users should use [database/sql]. Use mssql.RegisterDriver with any 137 // necessary Dialer configuration. 138 // 139 // Note: The returned cleanup func will stop the dialer's background refresh 140 // goroutine and should only be called when you're done with the Dialer. 141 // 142 // import ( 143 // "database/sql" 144 // 145 // "cloud.google.com/go/cloudsqlconn" 146 // "cloud.google.com/go/cloudsqlconn/sqlserver/mssql" 147 // ) 148 // 149 // func connect() { 150 // cleanup, err := mssql.RegisterDriver("cloudsql-sqlserver") 151 // if err != nil { 152 // // ... handle error 153 // } 154 // // call cleanup when you're done with the database connection 155 // defer cleanup() 156 // 157 // db, err := sql.Open( 158 // "cloudsql-sqlserver", 159 // "sqlserver://user:password@localhost?database=mydb&cloudsql=project:region:instance", 160 // ) 161 // // ... etc 162 // } 163 // 164 // [database/sql]: https://pkg.go.dev/database/sql 165 // [pgx]: https://github.com/jackc/pgx 166 // [pgxpool]: https://pkg.go.dev/github.com/jackc/pgx/v4/pgxpool 167 package cloudsqlconn 168