feat: deprecate proxy drivers (#1500)

proxy/README.md

@@ -1,5 +1,15 @@
 # Cloud SQL proxy dialer for Go
 
+## Note
+
+This package is deprecated. Instead use the [Cloud SQL Go
+Connector][go-connector] which has support for MySQL, Postgres, and SQL Server,
+in addition to better configurability, support for metrics and tracing, and a
+number of additional features. See the [migration guide][migration-guide] for
+how to switch.
+
+## Overview
+
 You can also use the Cloud SQL proxy directly from a Go program.
 
 These packages are primarily used as implementation for the Cloud SQL proxy
@@ -31,3 +41,5 @@ See [example usage](dialers/postgres/hook_test.go).
 [Python]: https://github.com/GoogleCloudPlatform/cloud-sql-python-connector
 [go-mysql]: https://github.com/go-sql-driver/mysql
 [mysql-godoc]: https://pkg.go.dev/github.com/GoogleCloudPlatform/cloudsql-proxy/proxy/dialers/mysql
+[go-connector]: https://pkg.go.dev/cloud.google.com/go/cloudsqlconn
+[migration-guide]: https://github.com/GoogleCloudPlatform/cloud-sql-go-connector/blob/main/migration-guide.md

proxy/dialers/mysql/hook.go

@@ -37,6 +37,10 @@ func init() {
 //
 // The returned *sql.DB may be valid even if there's also an error returned
 // (e.g. if there was a transient connection error).
+//
+// Deprecated: Dial has been replaced by the Cloud SQL Go connector which has
+// better support for configuring the dialer's behavior.
+// See cloud.google.com/go/cloudsqlconn/mysql/mysql.RegisterDriver instead.
 func Dial(instance, user string) (*sql.DB, error) {
 	cfg := mysql.NewConfig()
 	cfg.User = user
@@ -51,6 +55,10 @@ func Dial(instance, user string) (*sql.DB, error) {
 // information, see:
 //
 //	https://cloud.google.com/sql/docs/sql-proxy#user
+//
+// Deprecated: DialPassword has been replaced by the Cloud SQL Go connector
+// which has better support for configuring the dialer's behavior. See
+// cloud.google.com/go/cloudsqlconn/mysql/mysql.RegisterDriver instead.
 func DialPassword(instance, user, password string) (*sql.DB, error) {
 	cfg := mysql.NewConfig()
 	cfg.User = user
@@ -63,6 +71,10 @@ func DialPassword(instance, user, password string) (*sql.DB, error) {
 // provided instance via the given user and password. The config can be
 // modified and passed to DialCfg to connect. If you don't modify the returned
 // config before dialing, consider using Dial or DialPassword.
+//
+// Deprecated: Cfg has been replaced by the Cloud SQL Go connector which has
+// better support for configuring the dialer's behavior.
+// See cloud.google.com/go/cloudsqlconn/mysql/mysql.RegisterDriver instead.
 func Cfg(instance, user, password string) *mysql.Config {
 	cfg := mysql.NewConfig()
 	cfg.User = user
@@ -78,6 +90,10 @@ func Cfg(instance, user, password string) *mysql.Config {
 // The cfg.Addr should be the instance's connection string, in the format of:
 //
 //	project-name:region:instance-name.
+//
+// Deprecated: DialCfg has been replaced by the Cloud SQL Go connector which has
+// better support for configuring the dialer's behavior. See
+// cloud.google.com/go/cloudsqlconn/mysql/mysql.RegisterDriver instead.
 func DialCfg(cfg *mysql.Config) (*sql.DB, error) {
 	if cfg.TLSConfig != "" {
 		return nil, errors.New("do not specify TLS when using the Proxy")

proxy/dialers/postgres/hook.go

@@ -43,6 +43,11 @@ type dialer struct{}
 // lib/pq returns the format '[project:region:instance]:port'
 var instanceRegexp = regexp.MustCompile(`^\[(.+)\]:[0-9]+$`)
 
+// Dial connects to the provider Cloud SQL instance.
+//
+// Deprecated: Dial has been replaced by the Cloud SQL Go connector which has
+// better support for configuring the dialer's behavior. See
+// cloud.google.com/go/cloudsqlconn/postgres/pgxv4.RegisterDriver instead.
 func (d dialer) Dial(ntw, addr string) (net.Conn, error) {
 	matches := instanceRegexp.FindStringSubmatch(addr)
 	if len(matches) != 2 {
@@ -52,10 +57,19 @@ func (d dialer) Dial(ntw, addr string) (net.Conn, error) {
 	return proxy.Dial(instance)
 }
 
+// DialTimeout connects to the provider Cloud SQL instance using the provided
+// timeout.
+//
+// Deprecated: DialTimeout has been replaced by the Cloud SQL Go connector which
+// has better support for configuring the dialer's behavior. See
+// cloud.google.com/go/cloudsqlconn/postgres/pgxv4.RegisterDriver instead.
 func (d dialer) DialTimeout(ntw, addr string, timeout time.Duration) (net.Conn, error) {
 	return nil, fmt.Errorf("timeout is not currently supported for cloudsqlpostgres dialer")
 }
 
+// Deprecated: Open has been replaced by the Cloud SQL Go connector which has
+// better support for configuring the dialer's behavior. See
+// cloud.google.com/go/cloudsqlconn/postgres/pgxv4.RegisterDriver instead.
 func (d *Driver) Open(name string) (driver.Conn, error) {
 	return pq.DialOpen(dialer{}, name)
 }