### Complete Configuration Guide

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/README.md

A comprehensive guide to configuring the Cloud SQL Go Connector, covering all aspects from authentication to network settings.

```APIDOC
## Complete Configuration Guide

### Description
This guide provides an exhaustive overview of all configuration parameters and strategies for the Cloud SQL Go Connector.

### Key Configuration Areas
- **Authentication**: Setting up Application Default Credentials (ADC), service account keys, and token sources.
- **Refresh Configuration**: Strategies for certificate refresh (background vs. lazy).
- **Certificate Options**: Managing TLS certificates.
- **Connection Configuration**: IP type selection, TCP keep-alive settings.
- **DNS Resolution**: Configuring DNS lookup behavior and failover.
- **API Configuration**: Settings related to Cloud SQL Admin API interactions.
- **Network Configuration**: Dial functions, HTTP client settings.
- **Environment Variables**: How environment variables can influence configuration.

### Configuration Presets
Predefined configuration profiles for common environments like Cloud Run, Kubernetes, and local development.
```

--------------------------------

### Install Cloud SQL Go Connector

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/README.md

Use 'go get' to install the Cloud SQL Go Connector package. This command fetches and installs the package and its dependencies.

```sh
go get cloud.google.com/go/cloudsqlconn
```

--------------------------------

### ConnName String Method Example

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/types.md

Demonstrates how to get a string representation of a ConnName. The format depends on whether a domain name is set.

```go
cn, _ := instance.ParseConnName("my-project:us-central1:my-instance")
fmt.Println(cn.String()) // Output: "my-project:us-central1:my-instance"
```

--------------------------------

### Example: Structured Logging with ContextLogger

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/api-reference/debug-logging.md

Illustrates how to implement ContextLogger for structured logging using the 'log/slog' package.

```go
import "log/slog"

type structuredLogger struct{}

func (l *structuredLogger) Debugf(ctx context.Context, format string, args ...interface{}) {
    slog.DebugContext(ctx, fmt.Sprintf(format, args...))
}

dialer, _ := cloudsqlconn.NewDialer(
    ctx,
    cloudsqlconn.WithContextDebugLogger(&structuredLogger{}),
)
```

--------------------------------

### Example: Basic ContextLogger Implementation

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/api-reference/debug-logging.md

Shows a basic implementation of the ContextLogger interface for creating a new Dialer.

```go
type myContextLogger struct{}

func (l *myContextLogger) Debugf(ctx context.Context, format string, args ...interface{}) {
    log.Printf("[DEBUG] "+format, args...)
}

dialer, _ := cloudsqlconn.NewDialer(
    ctx,
    cloudsqlconn.WithContextDebugLogger(&myContextLogger{}),
)
```

--------------------------------

### Custom ContextLogger Implementation Example

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/types.md

Example of implementing the ContextLogger interface for context-aware debug logging.

```go
type myContextLogger struct{}

func (l *myContextLogger) Debugf(ctx context.Context, format string, args ...interface{}) {
    log.Printf("[DEBUG] "+format, args...)
}

dialer, _ := cloudsqlconn.NewDialer(ctx, cloudsqlconn.WithContextDebugLogger(&myContextLogger{}))
```

--------------------------------

### Example: Request-Aware ContextLogger

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/api-reference/debug-logging.md

Demonstrates a ContextLogger implementation that includes a request ID from the context in log messages.

```go
type requestAwareLogger struct{}

func (l *requestAwareLogger) Debugf(ctx context.Context, format string, args ...interface{}) {
    requestID := ""
    if id := ctx.Value("request-id"); id != nil {
        requestID = fmt.Sprintf("[%s] ", id)
    }
    log.Printf("[DEBUG] %s"+format, append([]interface{}{requestID}, args...)...)
}

dialer, _ := cloudsqlconn.NewDialer(
    ctx,
    cloudsqlconn.WithContextDebugLogger(&requestAwareLogger{}),
)
```

--------------------------------

### Custom Logger Implementation Example

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/types.md

Example of implementing the Logger interface for debug logging.

```go
type myLogger struct{}

func (l *myLogger) Debugf(format string, args ...interface{}) {
    log.Printf("[DEBUG] "+format, args...)
}

dialer, _ := cloudsqlconn.NewDialer(ctx, cloudsqlconn.WithDebugLogger(&myLogger{}))
```

--------------------------------

### Configure DNS TXT Record

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/api-reference/instance-resolver.md

Example of setting up a DNS TXT record for instance connection name resolution. This is typically done in your DNS provider's interface.

```bash
# Using Google Cloud DNS (private zone)
gcloud dns record-sets create prod-db.example.com \
    --rrdatas="my-project:us-central1:my-instance" \
    --ttl=3600 \
    --type=TXT \
    --zone=private-zone
```

--------------------------------

### Custom Connection Name Resolver Example

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/types.md

Demonstrates how to implement and use a custom ConnectionNameResolver to map short names to full instance connection names.

```go
type customResolver struct {
    mapping map[string]string
}

func (r *customResolver) Resolve(ctx context.Context, name string) (instance.ConnName, error) {
    if actual, ok := r.mapping[name]; ok {
        name = actual
    }
    return instance.ParseConnName(name)
}

resolver := &customResolver{
    mapping: map[string]string{
        "db": "my-project:us-central1:my-instance",
    },
}

dialer, err := cloudsqlconn.NewDialer(ctx, cloudsqlconn.WithResolver(resolver))
if err != nil {
    log.Fatal(err)
}

// Now "db" resolves to "my-project:us-central1:my-instance"
conn, _ := dialer.Dial(context.Background(), "db")
```

--------------------------------

### Migrate to OpenTelemetry with OpenCensus Bridge

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/README.md

This example demonstrates migrating to OpenTelemetry using the OpenCensus bridge for traces. It configures a trace provider and registers an OpenCensus tracer. Remember to replace 'mycoolproject' with your project ID and consider using a production-ready sampler.

```Go
import (
	texporter "github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace"
	"go.opencensus.io/trace"
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/bridge/opencensus"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
	"google.golang.org/api/option"
)

func main() {
	// trace.AlwaysSample() is expensive. Replacing it with your own
	// sampler for production environments is recommended.

trace.ApplyConfig(trace.Config{DefaultSampler: trace.AlwaysSample()})
	exporter, err := texporter.New(
		texporter.WithTraceClientOptions([]option.ClientOption{option.WithTelemetryDisabled()}),
		texporter.WithProjectID("mycoolproject"),
	)
	if err != nil {
		// Handle error
	}

	tp := sdktrace.NewTracerProvider(sdktrace.WithSyncer(exporter))
	otel.SetTracerProvider(tp)
	tracer := tp.Tracer("Cloud SQL Go Connector Trace")
	trace.DefaultTracer = opencensus.NewTracer(tracer)

	// Use cloudsqlconn as usual.
	// ...
}
```

--------------------------------

### Connect to SQL Server using Cloud SQL Go Connector

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/migration-guide.md

Example of connecting to a Cloud SQL SQL Server instance using the Go Connector driver. This demonstrates registering a custom driver name and configuring options like credentials file.

```golang
import (
	"database/sql"

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

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

	db, err := sql.Open(
		"cloudsql-sqlserver", // matches the name registered above
		"sqlserver://user:password@localhost?database=mydb&cloudsql=project:region:instance",
	)
	if err != nil {
		// handle error as necessary
	}
	return db
}
```

--------------------------------

### Setup pgx Connection Pool with IAM AuthN

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/overview.md

Demonstrates how to set up a pgx connection pool using the Cloud SQL Go Connector with IAM authentication. Ensure the `cloudsqlconn.NewDialer` is created once and reused.

```go
func setupPgxPool(ctx context.Context) (*pgxpool.Pool, error) {
    d, err := cloudsqlconn.NewDialer(ctx, cloudsqlconn.WithIAMAuthN())
    if err != nil {
        return nil, err
    }
    
    config, _ := pgxpool.ParseConfig(
        "user=sa@project.iam dbname=mydb sslmode=disable",
    )
    config.ConnConfig.DialFunc = func(ctx context.Context, _, _ string) (net.Conn, error) {
        return d.Dial(ctx, "my-project:us-central1:my-instance")
    }
    
    return pgxpool.NewWithConfig(ctx, config)
}
```

--------------------------------

### Connect to MySQL using Cloud SQL Go Connector

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/migration-guide.md

Example of connecting to a Cloud SQL MySQL instance using the new Go Connector driver. This demonstrates registering a custom driver name and configuring options like credentials file.

```golang
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
}
```

--------------------------------

### Connect to MySQL using Cloud SQL Proxy v1

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/migration-guide.md

Example of connecting to a Cloud SQL MySQL instance using the v1 Cloud SQL Proxy driver.

```golang
import (
	"database/sql"

	"github.com/GoogleCloudPlatform/cloudsql-proxy/proxy/dialers/mysql"
)

func connectMySQL() *sql.DB {
	cfg := mysql.Cfg("project:region:instance", "user", "password")
	cfg.DBName = "DB_1"
	cfg.ParseTime = true

	db, err := mysql.DialCfg(cfg)
	if err != nil {
		// handle error as necessary
	}
	return db
}
```

--------------------------------

### ConnName Region Method Example

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/types.md

Retrieves the Cloud SQL instance region from a ConnName struct.

```go
cn, _ := instance.ParseConnName("my-project:us-central1:my-instance")
fmt.Println(cn.Region()) // Output: "us-central1"
```

--------------------------------

### Connect to PostgreSQL using Cloud SQL Proxy v1

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/migration-guide.md

Example of connecting to a Cloud SQL PostgreSQL instance using the v1 Cloud SQL Proxy driver.

```golang
import (
	"database/sql"

	_ "github.com/GoogleCloudPlatform/cloudsql-proxy/proxy/dialers/postgres"
)
func connectPostgres() *sql.DB {
	db, err := sql.Open(
		"cloudsqlpostgres",
		"host=project:region:instance user=postgres dbname=postgres password=password sslmode=disable",
	)
	if err != nil {
		// handle error as necessary
	}
	return db
}
```

--------------------------------

### Register PostgreSQL (pgx v5) Driver

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/overview.md

Registers the PostgreSQL driver for use with the standard database/sql interface. This example shows how to register the pgx v5 driver with optional configurations.

```go
pgxv5.RegisterDriver(name, opts...)
```

--------------------------------

### ConnName Name Method Example

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/types.md

Retrieves the Cloud SQL instance name from a ConnName struct.

```go
cn, _ := instance.ParseConnName("my-project:us-central1:my-instance")
fmt.Println(cn.Name()) // Output: "my-instance"
```

--------------------------------

### Connect to PostgreSQL using Cloud SQL Go Connector

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/migration-guide.md

Example of connecting to a Cloud SQL PostgreSQL instance using the new Go Connector driver with pgx. This demonstrates registering a custom driver name and configuring options like credentials file and IAM authentication.

```golang
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
}
```

--------------------------------

### ConnName Project Method Example

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/types.md

Retrieves the GCP project ID from a ConnName struct.

```go
cn, _ := instance.ParseConnName("my-project:us-central1:my-instance")
fmt.Println(cn.Project()) // Output: "my-project"
```

--------------------------------

### Set Default DialOptions

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/README.md

Configure default DialOptions to be applied to all connections created by the dialer. This simplifies setup when common options are required for multiple connections.

```go
d, err := cloudsqlconn.NewDialer(
    ctx,
    cloudsqlconn.WithDefaultDialOptions(
        cloudsqlconn.WithPrivateIP(),
    ),
)
```

--------------------------------

### Connect to Multiple Database Instances

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/api-reference/database-drivers.md

Demonstrates registering and connecting to both PostgreSQL and MySQL instances simultaneously. Cleanup functions for both drivers should be deferred.

```go
// PostgreSQL instance
pgCleanup, _ := pgxv5.RegisterDriver("pg-prod", cloudsqlconn.WithIAMAuthN())
pgDB, _ := sql.Open("pg-prod", "host=my-project:us-central1:pg-instance user=myuser dbname=mydb sslmode=disable")

// MySQL instance
mysqlCleanup, _ := mysql.RegisterDriver("mysql-prod", cloudsqlconn.WithIAMAuthN())
mysqlDB, _ := sql.Open("mysql-prod", "myuser@cloudsql-mysql(my-project:us-central1:mysql-instance)/mydb")

// Cleanup
default pgCleanup()
default mysqlCleanup()
```

--------------------------------

### Creating a Dialer with Options

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/INDEX.md

Shows how to create a new `Dialer` instance using `NewDialer` and applying options like `WithIAMAuthN()` and `WithPrivateIP()`.

```go
dialer, _ := cloudsqlconn.NewDialer(
    ctx,
    cloudsqlconn.WithIAMAuthN(),          // Option
    cloudsqlconn.WithPrivateIP(),         // DialOption (when passed to Dial)
)
```

--------------------------------

### Catching ErrDialerClosed

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/errors.md

Example of how to check for and handle the ErrDialerClosed error when calling the Dial method.

```go
conn, err := dialer.Dial(ctx, instanceName)
if err == cloudsqlconn.ErrDialerClosed {
    log.Fatal("Dialer was already closed")
}
```

--------------------------------

### ParseConnName Invalid Name Examples

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/api-reference/instance-resolver.md

Demonstrates invalid connection name formats that will result in errors when using ParseConnName.

```go
// Missing region
_, err := instance.ParseConnName("my-project::my-instance")
// Error: invalid instance connection name

// Missing component
_, err := instance.ParseConnName("my-project:us-central1")
// Error: invalid instance connection name

// Wrong format
_, err := instance.ParseConnName("my-project-us-central1-my-instance")
// Error: invalid instance connection name
```

--------------------------------

### Common Patterns - Multiple Database Instances

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/api-reference/database-drivers.md

Demonstrates how to register and connect to multiple database instances (PostgreSQL and MySQL) simultaneously using their respective drivers.

```APIDOC
## Common Patterns - Multiple Database Instances

### Description
Shows how to register and use multiple database instances (e.g., PostgreSQL and MySQL) concurrently by registering distinct drivers for each.

### Example
```go
import (
    "database/sql"
    "log"
    "cloud.google.com/go/cloudsqlconn"
    "cloud.google.com/go/cloudsqlconn/mysql"
    "github.com/jackc/pgx/v5/stdlib"
)

func main() {
    // PostgreSQL instance
    pgCleanup, err := pgxv5.RegisterDriver("pg-prod", cloudsqlconn.WithIAMAuthN())
    if err != nil {
        log.Fatalf("Failed to register pg driver: %v", err)
    }
    defer pgCleanup()
    pgDB, err := sql.Open("pg-prod", "host=my-project:us-central1:pg-instance user=myuser dbname=mydb sslmode=disable")
    if err != nil {
        log.Fatalf("Failed to connect to pg instance: %v", err)
    }
    defer pgDB.Close()

    // MySQL instance
    mysqlCleanup, err := mysql.RegisterDriver("mysql-prod", cloudsqlconn.WithIAMAuthN())
    if err != nil {
        log.Fatalf("Failed to register mysql driver: %v", err)
    }
    defer mysqlCleanup()
    mysqlDB, err := sql.Open("mysql-prod", "myuser@cloudsql-mysql(my-project:us-central1:mysql-instance)/mydb")
    if err != nil {
        log.Fatalf("Failed to connect to mysql instance: %v", err)
    }
    defer mysqlDB.Close()

    // Use pgDB and mysqlDB for your database operations...
}
```
```

--------------------------------

### ConnName HasDomainName Method Example

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/types.md

Checks if a domain name is associated with the ConnName. Returns true if a domain name was provided during parsing, false otherwise.

```go
cn, _ := instance.ParseConnNameWithDomainName("my-project:us-central1:my-instance", "prod-db.example.com")
fmt.Println(cn.HasDomainName()) // Output: true
```

--------------------------------

### Catching ConfigError

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/errors.md

Demonstrates how to catch and handle `ConfigError` using `errors.As`. This is useful for identifying and logging specific configuration problems.

```go
import (
    "errors"
    "cloud.google.com/go/cloudsqlconn/errtype"
)

conn, err := dialer.Dial(ctx, instanceName)
if err != nil {
    var ce *errtype.ConfigError
    if errors.As(err, &ce) {
        log.Printf("Configuration error for %s: %v", ce.ConnName, ce.Message)
    }
}
```

--------------------------------

### Build Docker Image

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/examples/cloudrun/README.md

Build the Docker image for your application. Replace REGION, PROJECT_ID, REPO_NAME, IMAGE_NAME, and specify 'mysql', 'postgres', or 'sqlserver'.

```bash
docker build -t REGION-docker.pkg.dev/PROJECT_ID/REPO_NAME/IMAGE_NAME mysql
```

--------------------------------

### IsValidDomain Function Example

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/types.md

Validates if a given string is a well-formed domain name according to relevant RFCs. Returns true for valid domain names and false otherwise.

```go
if instance.IsValidDomain("prod-db.example.com") {
    fmt.Println("Valid domain")
}
if !instance.IsValidDomain("invalid..domain") {
    fmt.Println("Invalid domain")
}
```

--------------------------------

### ConnName DomainName Method Example

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/types.md

Retrieves the associated domain name from a ConnName struct, if one was provided during parsing. Returns an empty string if no domain name is set.

```go
cn, _ := instance.ParseConnNameWithDomainName(
    "my-project:us-central1:my-instance",
    "prod-db.example.com",
)
fmt.Println(cn.DomainName()) // Output: "prod-db.example.com"
```

--------------------------------

### Development Configuration Preset

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/configuration.md

Configure the dialer for local development, enabling public IP access and context-aware debug logging.

```go
dialer, _ := cloudsqlconn.NewDialer(
    ctx,
    cloudsqlconn.WithPublicIP(),    // Local development
    cloudsqlconn.WithContextDebugLogger(myLogger), // Debug logs
)
```

--------------------------------

### Connect to PostgreSQL with Password

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/INDEX.md

Register the PostgreSQL driver and open a SQL database connection using password authentication.

```go
cleanup, _ := pgxv5.RegisterDriver("cloudsql-postgres")
db, _ := sql.Open("cloudsql-postgres", "host=project:region:instance user=user password=pass dbname=db sslmode=disable")
```

--------------------------------

### Set Private IP as Default Dialer Option

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/configuration.md

Configure the dialer to use private IP access by default for all connections. This simplifies setup when all connections should use this method.

```go
dialer, _ := cloudsqlconn.NewDialer(
    ctx,
    cloudsqlconn.WithDefaultDialOptions(cloudsqlconn.WithPrivateIP()),
)
```

--------------------------------

### New Dialer with Service Account File

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/configuration.md

Use this to configure the Dialer to load credentials from a specified service account JSON file.

```go
dialer, err := cloudsqlconn.NewDialer(
    ctx,
    cloudsqlconn.WithCredentialsFile("service-account.json"),
)
```

--------------------------------

### Simple PostgreSQL with Password Authentication

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/overview.md

Connect to a PostgreSQL instance using password authentication. Ensure the database credentials are provided in the connection string.

```go
func setupDB() (*sql.DB, error) {
    cleanup, err := pgxv5.RegisterDriver("cloudsql-postgres")
    if err != nil {
        return nil, err
    }
    defer cleanup()
    
    return sql.Open(
        "cloudsql-postgres",
        "host=my-project:us-central1:my-instance user=postgres password=secret dbname=mydb sslmode=disable",
    )
}
```

--------------------------------

### ParseConnName Function Example

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/types.md

Parses a Cloud SQL instance connection name string into a ConnName struct. Requires the format PROJECT:REGION:INSTANCE. Errors are returned for invalid formats.

```go
import "cloud.google.com/go/cloudsqlconn/instance"

cn, err := instance.ParseConnName("my-project:us-central1:my-instance")
if err != nil {
    log.Fatal(err)
}
fmt.Println(cn.Project()) // "my-project"
```

--------------------------------

### Enable DNS-Based Instance Discovery

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/api-reference/options.md

Enable DNS-based instance discovery with WithDNSResolver. This allows mapping domain names to instance connection names via DNS TXT records.

```go
dialer, err := cloudsqlconn.NewDialer(ctx, cloudsqlconn.WithDNSResolver())

// Now Dial accepts DNS names
conn, err := dialer.Dial(ctx, "prod-db.mycompany.example.com")
```

--------------------------------

### Postgres DSN for IAM Authentication

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/README.md

Example DSN for connecting to a Postgres instance using IAM authentication with a service account. The user field should be the service account's email address.

```sql
dsn := "user=test-sa@test-project.iam dbname=mydb sslmode=disable"
```

--------------------------------

### WithPublicIP

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/api-reference/dial-options.md

Connects using the instance's public IP address. This is the default option if none is specified and requires the instance to have a public IP assigned.

```APIDOC
## WithPublicIP

### Description
Connects using the instance's public IP address. This is the default option if none is specified and requires the instance to have a public IP assigned.

### Method
```go
func WithPublicIP() DialOption
```

### Example
```go
conn, err := dialer.Dial(
    ctx,
    "my-project:us-central1:my-instance",
    cloudsqlconn.WithPublicIP(),
)
```
```

--------------------------------

### ParseConnNameWithDomainName Function Example

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/types.md

Parses a connection name string and associates it with a given domain name. The domain name is used for fallback address resolution. Errors are returned for invalid connection name formats.

```go
cn, err := instance.ParseConnNameWithDomainName(
    "my-project:us-central1:my-instance",
    "prod-db.example.com",
)
if err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Error Message Format Example

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/errors.md

Shows the standard format for custom errors generated by the connector, including error type, message, connection name, and the underlying cause. This format aids in parsing and debugging.

```text
dial error: handshake failed (connection name = "my-project:us-central1:my-instance"): tls: failed to verify certificate
```

--------------------------------

### Connect using Public IP

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/api-reference/dial-options.md

Use WithPublicIP() to connect using the instance's public IP address. This is the default option if none is specified and requires the instance to have a public IP. It's suitable for connections from outside VPC networks.

```go
conn, err := dialer.Dial(
    ctx,
    "my-project:us-central1:my-instance",
    cloudsqlconn.WithPublicIP(),
)
```

--------------------------------

### DefaultResolver Usage

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/api-reference/instance-resolver.md

Demonstrates the usage of the DefaultResolver, which parses connection names directly. This is the default behavior if no custom resolver is specified.

```go
cn, _ := instance.ParseConnName("my-project:us-central1:my-instance")
// Same as using DefaultResolver
```

--------------------------------

### MySQL DSN for IAM Authentication

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/README.md

Example DSN for connecting to a MySQL instance using IAM authentication with a service account. The user field should be the service account's email address without the domain suffix.

```sql
dsn := "user=test-sa dbname=mydb sslmode=disable"
```

--------------------------------

### Get Engine Version

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/api-reference/dialer.md

Retrieves the database engine type and version for a given instance connection name or DNS name. Triggers a metadata fetch if not cached and returns version strings like 'POSTGRES_15' or 'MYSQL_8_0'.

```go
version, err := dialer.EngineVersion(ctx, "my-project:us-central1:my-instance")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Instance version: %s\n", version)
```

--------------------------------

### Type-Safe Error Handling

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/INDEX.md

Demonstrates how to use `errors.As()` for type-safe error handling, specifically checking for `errtype.ConfigError`.

```go
var ce *errtype.ConfigError
if errors.As(err, &ce) {
  /* ... */
}
```

--------------------------------

### Create Artifact Registry Repository

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/examples/cloudrun/README.md

Create a Docker repository in Artifact Registry. Replace REPO_NAME and REGION.

```bash
gcloud artifacts repositories create REPO_NAME \
      --repository-format=docker \
      --location=REGION
```

--------------------------------

### Basic Connection Name Parsing

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/api-reference/instance-resolver.md

Parses a standard instance connection name string into its components (project, region, instance).

```go
cn, err := instance.ParseConnName("my-project:us-central1:my-instance")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Project: %s, Region: %s, Instance: %s\n",
    cn.Project(), cn.Region(), cn.Name())
// Output: Project: my-project, Region: us-central1, Instance: my-instance
```

--------------------------------

### Enable Debug Logging

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/INDEX.md

Create a dialer and configure it to use a custom logger for debug output.

```go
dialer, _ := cloudsqlconn.NewDialer(
    ctx,
    cloudsqlconn.WithContextDebugLogger(&myLogger{}),
)
```

--------------------------------

### Configure DNS-Based Failover

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/INDEX.md

Initialize a dialer with DNS resolver enabled and configure a failover period.

```go
dialer, _ := cloudsqlconn.NewDialer(
    ctx,
    cloudsqlconn.WithDNSResolver(),
    cloudsqlconn.WithFailoverPeriod(15*time.Second),
)
```

--------------------------------

### Deploy MySQL or PostgreSQL to Cloud Run (Public IP)

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/examples/cloudrun/README.md

Use this command to deploy a service connecting to a database via a public IP address.

```bash
gcloud run deploy SERVICE_NAME \
  --image=REGION-docker.pkg.dev/PROJECT_ID/REPO_NAME/IMAGE_NAME \
  --set-env-vars=DB_USER=DB_USER,DB_IAM_USER=DB_IAM_USER,DB_NAME=DB_NAME,DB_SECRET_NAME=DB_SECRET_NAME,INSTANCE_CONNECTION_NAME=INSTANCE_CONNECTION_NAME \
  --region=REGION \
  --update-secrets=DB_PASSWORD=DB_PASSWORD:latest
```

--------------------------------

### Adapting Old Logger to ContextLogger

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/api-reference/debug-logging.md

Demonstrates how to adapt a deprecated `Logger` interface to the `ContextLogger` interface for use with the Cloud SQL Go Connector's Dialer. This is useful when migrating older codebases or using custom logger implementations.

```go
package main

import (
	"context"
	"log"

	"github.com/GoogleCloudPlatform/cloud-sql-go-connector/cloudsqlconn"
)

// Old Logger interface (deprecated)
type oldLogger struct{}

func (l *oldLogger) Debugf(format string, args ...interface{}) {
	log.Printf(format, args...)
}

// Adapter to convert to ContextLogger
type loggerAdapter struct {
	logger Logger
}

func (a *loggerAdapter) Debugf(ctx context.Context, format string, args ...interface{}) {
	a.logger.Debugf(format, args...)
}

func main() {
	ctx := context.Background()
	// Use with adapter
	dialer, _ := cloudsqlconn.NewDialer(
		ctx,
		cloudsqlconn.WithContextDebugLogger(&loggerAdapter{&oldLogger{}}),
	)

	_ = dialer
}
```

--------------------------------

### Enable Artifact Registry API

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/examples/cloudrun/README.md

Enable the Artifact Registry API for your Google Cloud project.

```bash
gcloud services enable artifactregistry.googleapis.com
```

--------------------------------

### Create a Dialer with Custom Options

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/api-reference/dialer.md

Configures a new Dialer using specific options such as a credentials file, IAM authentication, and lazy refresh for certificates.

```go
dialer, err := cloudsqlconn.NewDialer(
    ctx,
    cloudsqlconn.WithCredentialsFile("service-account.json"),
    cloudsqlconn.WithIAMAuthN(),
    cloudsqlconn.WithLazyRefresh(),
)
if err != nil {
    log.Fatal(err)
}
defer dialer.Close()
```

--------------------------------

### Initialize Custom Dialer

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/README.md

Initializes a new Dialer instance with custom options such as a credentials file path.

```go
d, err := cloudsqlconn.NewDialer(
    ctx,
    cloudsqlconn.WithCredentialsFile("key.json"),
)
if err != nil {
    log.Fatalf("unable to initialize dialer: %s", err)
}

conn, err := d.Dial(ctx, "project:region:instance")
```

--------------------------------

### Configure Dialer and Dial Options

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/overview.md

Demonstrates using the functional options pattern to configure both the Dialer at creation time and individual connection attempts. Options include IAM authentication, lazy refresh, private IP, and TCP keep-alive settings.

```go
// Dialer options (creation time)
dialer, _ := cloudsqlconn.NewDialer(
    ctx,
    cloudsqlconn.WithIAMAuthN(),
    cloudsqlconn.WithLazyRefresh(),
)

// Dial options (per-connection)
conn, _ := dialer.Dial(
    ctx,
    instanceName,
    cloudsqlconn.WithPrivateIP(),
    cloudsqlconn.WithTCPKeepAlive(15*time.Second),
)
```

--------------------------------

### Connect with IAM Authentication

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/INDEX.md

Create a dialer with IAM authentication enabled and establish a connection to the Cloud SQL instance.

```go
dialer, _ := cloudsqlconn.NewDialer(ctx, cloudsqlconn.WithIAMAuthN())
conn, _ := dialer.Dial(ctx, "project:region:instance")
```

--------------------------------

### Deploy SQL Server to Cloud Run (Public IP)

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/examples/cloudrun/README.md

Use this command to deploy a service connecting to a SQL Server instance via a public IP address.

```bash
gcloud run deploy SERVICE_NAME \
  --image=REGION-docker.pkg.dev/PROJECT_ID/REPO_NAME/IMAGE_NAME \
  --set-env-vars=DB_USER=DB_USER,DB_NAME=DB_NAME,DB_SECRET_NAME=DB_SECRET_NAME,INSTANCE_CONNECTION_NAME=INSTANCE_CONNECTION_NAME \
  --region=REGION \
  --update-secrets=DB_PASSWORD=DB_PASSWORD:latest
```

--------------------------------

### Initialize Cloud SQL Dialer

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/overview.md

Create a new Cloud SQL Dialer instance. This is the primary interface for establishing connections to Cloud SQL instances. It can be configured with various options during initialization.

```go
dialer, err := cloudsqlconn.NewDialer(ctx, opts...)
```

--------------------------------

### Warmup

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/api-reference/dialer.md

Pre-initializes certificate refresh for an instance without establishing a connection. This is useful for reducing latency on the first connection.

```APIDOC
## Warmup

### Description
Pre-initializes certificate refresh for an instance without establishing a connection. This is useful for reducing latency on the first connection.

### Method Signature
```go
func (d *Dialer) Warmup(ctx context.Context, icn string, opts ...DialOption) error
```

### Parameters
#### Path Parameters
- **ctx** (context.Context) - Required - Context for the operation
- **icn** (string) - Required - Instance connection name or DNS name
- **opts** (...DialOption) - Optional - Variable number of DialOption functions to configure refresh behavior

### Return
`error` — Error if certificate refresh fails, nil on success

### Errors:
- `errtype.ConfigError` — Instance connection name is malformed
- `errtype.RefreshError` — Failed to retrieve instance metadata or certificates

### Behavior:
- Useful for reducing latency on first connection in latency-sensitive applications
- Starts the background refresh process (unless `WithLazyRefresh` is enabled)
- Can be called for multiple instances to pre-populate the certificate cache
- In Cloud Run with CPU throttling, use `WithLazyRefresh` so refresh happens on-demand instead

### Example:
```go
// Warm up certificates for instances before handling requests
instances := []string{
    "my-project:us-central1:instance-1",
    "my-project:us-central1:instance-2",
}

for _, icn := range instances {
    if err := dialer.Warmup(ctx, icn); err != nil {
        log.Printf("Failed to warmup %s: %v", icn, err)
    }
}

// First Dial calls will be faster now
```
```

--------------------------------

### Configure Dialer for Cloud Run Deployment

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/INDEX.md

Initialize a dialer with settings suitable for Cloud Run, including lazy refresh, private IP, and IAM authentication.

```go
dialer, _ := cloudsqlconn.NewDialer(
    ctx,
    cloudsqlconn.WithLazyRefresh(),
    cloudsqlconn.WithPrivateIP(),
    cloudsqlconn.WithIAMAuthN(),
)
```

--------------------------------

### Configure Quota Project for API Requests

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/configuration.md

Set a specific billing project for API requests using the `WithQuotaProject` option. This attributes quota and billing to the specified project, useful in multi-tenant scenarios.

```go
dialer, _ := cloudsqlconn.NewDialer(
    ctx,
    cloudsqlconn.WithQuotaProject("my-billing-project"),
)
```

--------------------------------

### Enabling Debug Logging with ContextLogger

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/api-reference/debug-logging.md

Shows the preferred method for enabling debug logging by providing a ContextLogger implementation to NewDialer.

```go
dialer, err := cloudsqlconn.NewDialer(
    ctx,
    cloudsqlconn.WithContextDebugLogger(&myLogger{}),
)
```

--------------------------------

### Enabling Debug Logging with Deprecated Logger

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/api-reference/debug-logging.md

Demonstrates how to enable debug logging using the deprecated Logger interface, which is not recommended for new implementations.

```go
dialer, err := cloudsqlconn.NewDialer(
    ctx,
    cloudsqlconn.WithDebugLogger(&myLogger{}),
)
```

--------------------------------

### Implement Custom Caching Resolver

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/api-reference/instance-resolver.md

Demonstrates how to create a custom `ConnectionNameResolver` that caches resolved connection names to improve performance. It wraps a base resolver and stores results in a map.

```go
type cachedResolver struct {
    cache map[string]instance.ConnName
    base  instance.ConnectionNameResolver
    mu    sync.RWMutex
}

func (r *cachedResolver) Resolve(ctx context.Context, name string) (instance.ConnName, error) {
    r.mu.RLock()
    if cn, ok := r.cache[name]; ok {
        r.mu.RUnlock()
        return cn, nil
    }
    r.mu.RUnlock()
    
    cn, err := r.base.Resolve(ctx, name)
    if err != nil {
        return cn, err
    }
    
    r.mu.Lock()
    r.cache[name] = cn
    r.mu.Unlock()
    
    return cn, nil
}

resolver := &cachedResolver{
    cache: make(map[string]instance.ConnName),
    base:  cloudsql.DefaultResolver,
}

dialer, _ := cloudsqlconn.NewDialer(ctx, cloudsqlconn.WithResolver(resolver))
```

--------------------------------

### Deploy MySQL or PostgreSQL to Cloud Run (Private IP)

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/examples/cloudrun/README.md

Use this command to deploy a service connecting to a database via a private IP address within a VPC.

```bash
gcloud run deploy SERVICE_NAME \
  --image=REGION-docker.pkg.dev/PROJECT_ID/REPO_NAME/IMAGE_NAME \
  --set-env-vars=DB_USER=DB_USER,DB_IAM_USER=DB_IAM_USER,DB_NAME=DB_NAME,DB_SECRET_NAME=DB_SECRET_NAME,INSTANCE_CONNECTION_NAME=INSTANCE_CONNECTION_NAME,IP_TYPE=PRIVATE \
  --network=VPC_NETWORK \
  --subnet=SUBNET_NAME \
  --vpc-egress=private-ranges-only \
  --region=REGION \
  --update-secrets=DB_PASSWORD=DB_PASSWORD:latest
```

--------------------------------

### New Dialer with Environment Variable Credentials

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/configuration.md

Configure the Dialer to load credentials from a JSON string obtained from an environment variable.

```go
credsJSON := os.Getenv("GCP_CREDENTIALS")
dialer, err := cloudsqlconn.NewDialer(
    ctx,
    cloudsqlconn.WithCredentialsJSON([]byte(credsJSON)),
)
```

--------------------------------

### Use DNS Resolved Instance in Application

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/api-reference/instance-resolver.md

Demonstrates how to use a Dialer configured with a DNS resolver to connect to an instance using a domain name. The connector will automatically resolve the connection name via DNS.

```go
dialer, _ := cloudsqlconn.NewDialer(
    ctx,
    cloudsqlconn.WithDNSResolver(),
    cloudsqlconn.WithFailoverPeriod(15*time.Second),
)

// Resolves via DNS TXT record
conn, _ := dialer.Dial(ctx, "prod-db.example.com")
```

--------------------------------

### Connect using Auto IP Selection

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/api-reference/dial-options.md

Use WithAutoIP() to automatically select the public IP if available, falling back to private IP. This option is provided for backward compatibility and is not recommended for production use. It selects public IP if the instance has one; otherwise, it uses private IP.

```go
conn, err := dialer.Dial(
    ctx,
    "my-project:us-central1:my-instance",
    cloudsqlconn.WithAutoIP(),
)
```

--------------------------------

### Configure Dialer with Credentials JSON

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/api-reference/options.md

Use `WithCredentialsJSON` to provide authentication credentials directly as a byte slice of JSON. This is useful when credentials are obtained from environment variables or other dynamic sources.

```go
credsJSON := []byte(`{"type": "service_account", ...}`)
dialer, err := cloudsqlconn.NewDialer(
    ctx,
    cloudsqlconn.WithCredentialsJSON(credsJSON),
)
```

--------------------------------

### Import Cloud SQL Go Connector Modules

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/INDEX.md

Import the main package and specific sub-packages for instance handling, debugging, error types, and database drivers.

```go
import "cloud.google.com/go/cloudsqlconn"
import "cloud.google.com/go/cloudsqlconn/instance"
import "cloud.google.com/go/cloudsqlconn/debug"
import "cloud.google.com/go/cloudsqlconn/errtype"
import "cloud.google.com/go/cloudsqlconn/postgres/pgxv5"
import "cloud.google.com/go/cloudsqlconn/postgres/pgxv4"
import "cloud.google.com/go/cloudsqlconn/mysql/mysql"
import "cloud.google.com/go/cloudsqlconn/sqlserver/mssql"
```

--------------------------------

### Connect to SQL Server using ADO format

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/api-reference/database-drivers.md

Opens a SQL Server database connection using the "cloudsql-sqlserver" driver and an ADO-formatted DSN. The DSN must include the 'cloudsql' parameter for the instance connection name.

```go
dsn := "Server=localhost;Database=master;User Id=sa;Password=password;cloudsql=my-project:us-central1:my-instance"
db, err := sql.Open("cloudsql-sqlserver", dsn)
```

--------------------------------

### WithQuotaProject

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/api-reference/options.md

Sets the GCP project for quota and billing purposes by adding the `X-Goog-User-Project` header to API requests. This is useful in multi-tenant scenarios.

```APIDOC
## WithQuotaProject

### Description
Sets the GCP project for quota and billing purposes.

### Method
`func WithQuotaProject(p string) Option`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
dialer, err := cloudsqlconn.NewDialer(
    ctx,
    cloudsqlconn.WithQuotaProject("my-billing-project"),
)
```

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### Dial a Cloud SQL Instance (Basic)

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/api-reference/dialer.md

Establishes a TLS-encrypted connection to a Cloud SQL instance using its connection name. A context with a timeout is recommended for the dial operation.

```go
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

conn, err := dialer.Dial(ctx, "my-project:us-central1:my-instance")
if err != nil {
    log.Fatal(err)
}
defer conn.Close()
```

--------------------------------

### Enable DNS-Based Instance Discovery

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/configuration.md

Activate DNS-based instance discovery to enable dynamic resolution of instance endpoints. This is useful for environments where instance IPs may change.

```go
dialer, _ := cloudsqlconn.NewDialer(ctx, cloudsqlconn.WithDNSResolver())
```

--------------------------------

### Initialize Dialer with DNS Resolver

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/api-reference/instance-resolver.md

Initializes a new Dialer with the DNS resolver enabled. This allows the connector to resolve instance connection names from DNS TXT records.

```go
dialer, _ := cloudsqlconn.NewDialer(
    ctx,
    cloudsqlconn.WithDNSResolver(),
)
```

--------------------------------

### Deploy SQL Server to Cloud Run (Private IP)

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/examples/cloudrun/README.md

Use this command to deploy a service connecting to a SQL Server instance via a private IP address within a VPC.

```bash
gcloud run deploy SERVICE_NAME \
  --image=REGION-docker.pkg.dev/PROJECT_ID/REPO_NAME/IMAGE_name \
  --set-env-vars=DB_USER=DB_USER,DB_NAME=DB_NAME,DB_SECRET_NAME=DB_SECRET_NAME,INSTANCE_CONNECTION_NAME=INSTANCE_CONNECTION_NAME,IP_TYPE=PRIVATE \
  --network=VPC_NETWORK \
  --subnet=SUBNET_NAME \
  --vpc-egress=private-ranges-only \
  --region=REGION \
  --update-secrets=DB_PASSWORD=DB_PASSWORD:latest
```

--------------------------------

### Register PostgreSQL Driver (pgxv5)

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/api-reference/database-drivers.md

Registers a PostgreSQL driver for use with database/sql. Configure with options like IAM authentication. Returns a cleanup function to close the dialer.

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

func init() {
    cleanup, err := pgxv5.RegisterDriver(
        "cloudsql-postgres",
        cloudsqlconn.WithIAMAuthN(),
    )
    if err != nil {
        log.Fatal(err)
    }
    defer cleanup()
}

func connect() (*sql.DB, error) {
    return sql.Open(
        "cloudsql-postgres",
        "host=my-project:us-central1:my-instance user=myuser password=mypass dbname=mydb sslmode=disable",
    )
}
```

--------------------------------

### Configure Custom Instance Name Resolution

Source: https://github.com/googlecloudplatform/cloud-sql-go-connector/blob/main/_autodocs/INDEX.md

Create a dialer that uses a custom resolver for instance name resolution.

```go
dialer, _ := cloudsqlconn.NewDialer(ctx, cloudsqlconn.WithResolver(&customResolver{}))
```