Nov 17, 202611 min read

Cloud SQL Auth Proxy: Local Dev, Cloud Run, GKE Sidecars and Connectors

What the Cloud SQL Auth Proxy does, how to run it on your laptop, how Cloud Run's built-in connection uses it, how to run it as a native sidecar on GKE with Workload Identity and IAM database authentication, when a language connector is the better choice, and how Encore connects to Cloud SQL.

Illustration for Cloud SQL Auth Proxy: Local Dev, Cloud Run, GKE Sidecars and Connectors

The Cloud SQL Auth Proxy is the small Google binary that turns "connect to Cloud SQL securely" into "connect to 127.0.0.1:5432", and it is used on a laptop, inside Cloud Run, or as a sidecar in a GKE pod. Each of those places runs it differently, and the confusing errors usually come from the parts around it: a missing IAM role, a private IP the proxy cannot reach, or a sidecar that is still starting when the app tries to connect.

This guide covers how the proxy works, how to run it locally, on Cloud Run and on GKE, when a language connector is the better fit, and how Encore connects to Cloud SQL for apps it deploys to GCP.

Cloud SQL connection options at a glance

EncoreAuth ProxyLanguage connectorCloud Run built-inPrivate IP direct
Runs asPart of the deploySeparate binary or sidecarLibrary in your processManaged by Cloud RunPlain driver
TLS and certsHandled for youTLS 1.3, ephemeral certsSame as proxySame as proxyYou configure SSL
Access controlPer-service rolesIAM cloudsql.instances.connectIAMIAMNetwork and DB password
IAM DB loginNot needed--auto-iam-authnWithIAMAuthN()Via connectorNot available
Local devencore run starts PostgresSame binary on your laptopSame libraryProxy on laptopVPN or bastion

The proxy's behavior is described in Google's Auth Proxy overview, and the current release is v2.28.0.

How the Cloud SQL Auth Proxy works

The proxy listens on a local TCP port, or a Unix socket in /cloudsql/, and speaks the plain Postgres protocol to your app. For each instance it calls the Cloud SQL Admin API with your IAM identity to get an ephemeral client certificate, valid for about an hour and refreshed before it expires, and it opens a TLS 1.3 tunnel to the instance on port 3307, one tunnel connection per client connection. Authorization comes from IAM: the identity needs a role with cloudsql.instances.connect, such as Cloud SQL Client, and the instance needs no authorized networks or SSL setup of its own.

The proxy does not create a network path, so with --private-ip it has to run somewhere with a route into the instance's VPC, and the hop between your app and the proxy is unencrypted, which is why Google recommends running it on the same machine or in the same pod. It also does not pool: 50 app connections are 50 database connections.

Run the proxy locally

Locally, the proxy authenticates as you through Application Default Credentials. Your account needs Cloud SQL Client on the project, and the instance needs a public IP unless your machine can reach its VPC:

~
$ gcloud auth application-default login$ curl -o cloud-sql-proxy \ https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.28.0/cloud-sql-proxy.linux.amd64$ chmod +x cloud-sql-proxy # The instance connection name is PROJECT:REGION:INSTANCE$ gcloud sql instances describe orders-db --format='value(connectionName)'my-project:europe-west1:orders-db $ ./cloud-sql-proxy --port 5433 my-project:europe-west1:orders-dbAuthorizing with Application Default Credentials[my-project:europe-west1:orders-db] Listening on 127.0.0.1:5433The proxy has started successfully and is ready for new connections! # In another terminal$ psql "host=127.0.0.1 port=5433 dbname=orders user=postgres"

Use a port other than 5432 when a local Postgres is already running, add --auto-iam-authn to log in as your Google account with IAM database authentication instead of a password, and --impersonate-service-account to test with the permissions your service will have. Several instances can share one proxy, each with its own port: ./cloud-sql-proxy "proj:region:a?port=5433" "proj:region:b?port=5434".

Cloud Run: the built-in connection

Cloud Run runs the proxy for you when you deploy with --add-cloudsql-instances, which mounts a Unix socket for the instance at /cloudsql/INSTANCE_CONNECTION_NAME, and the service account only needs Cloud SQL Client:

~
$ gcloud projects add-iam-policy-binding my-project \ --member=serviceAccount:orders-api@my-project.iam.gserviceaccount.com \ --role=roles/cloudsql.client$ gcloud run deploy orders-api --image=europe-west1-docker.pkg.dev/my-project/apps/orders-api:1.4.2 \ --region=europe-west1 --service-account=orders-api@my-project.iam.gserviceaccount.com \ --add-cloudsql-instances=my-project:europe-west1:orders-db \ --set-env-vars=DB_HOST=/cloudsql/my-project:europe-west1:orders-db,DB_NAME=orders

Postgres drivers take the directory as the host and find .s.PGSQL.5432 inside it. The second-generation execution environment embeds proxy v2, which instances using the newer shared or customer-managed server CA modes require; the first generation embeds v1 and only works with the per-instance CA. For private IP, Cloud Run reaches the instance over Direct VPC egress or a Serverless VPC Access connector instead, and the Cloud Run connection guide covers both. The full Cloud Run walkthrough with Node code is in connecting Cloud Run to Cloud SQL.

GKE: run the proxy as a native sidecar

On GKE, Google recommends a sidecar per pod rather than one shared proxy Service, so each app keeps its own IAM identity and the unencrypted hop never leaves the pod. Set up Workload Identity so the pod's Kubernetes service account acts as a Google service account, and, for IAM database login, create the database user for it:

~
$ gcloud iam service-accounts create orders-api$ for role in roles/cloudsql.client roles/cloudsql.instanceUser; do gcloud projects add-iam-policy-binding my-project \ --member=serviceAccount:orders-api@my-project.iam.gserviceaccount.com --role=$roledone$ gcloud iam service-accounts add-iam-policy-binding orders-api@my-project.iam.gserviceaccount.com \ --role=roles/iam.workloadIdentityUser \ --member="serviceAccount:my-project.svc.id.goog[default/orders-api]" # IAM database user: the service account email without .gserviceaccount.com$ gcloud sql users create orders-api@my-project.iam --instance=orders-db --type=cloud_iam_service_account

The instance needs the cloudsql.iam_authentication flag on for IAM logins, and the new user starts with no privileges, so grant it access to the tables it needs with GRANT as the postgres user. Then the Deployment, with the proxy under initContainers and restartPolicy: Always:

# deployment.yaml apiVersion: v1 kind: ServiceAccount metadata: name: orders-api annotations: iam.gke.io/gcp-service-account: orders-api@my-project.iam.gserviceaccount.com --- apiVersion: apps/v1 kind: Deployment metadata: name: orders-api spec: replicas: 3 selector: matchLabels: app: orders-api template: metadata: labels: app: orders-api spec: serviceAccountName: orders-api initContainers: # A native sidecar (Kubernetes 1.29+): starts before the app, # keeps running alongside it, and stops after it. - name: cloud-sql-proxy image: gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.28.0 restartPolicy: Always args: - "--private-ip" - "--auto-iam-authn" - "--structured-logs" - "--port=5432" - "--health-check" - "--http-address=0.0.0.0" - "--max-sigterm-delay=30s" - "my-project:europe-west1:orders-db" startupProbe: httpGet: path: /startup port: 9090 periodSeconds: 1 failureThreshold: 30 livenessProbe: httpGet: path: /liveness port: 9090 securityContext: runAsNonRoot: true allowPrivilegeEscalation: false resources: requests: cpu: 250m memory: 256Mi containers: - name: api image: europe-west1-docker.pkg.dev/my-project/apps/orders-api:1.4.2 env: - name: DB_HOST value: "127.0.0.1" - name: DB_PORT value: "5432" - name: DB_USER value: "orders-api@my-project.iam" - name: DB_NAME value: "orders" ports: - containerPort: 8080

Listed as an init container with restartPolicy: Always, the proxy is a Kubernetes native sidecar: it starts before the app container, and the app container is held back until the proxy's startup probe passes, so the first query never races the tunnel. It is also stopped after the app on shutdown, which removes the old problem of Jobs never finishing because the proxy kept running. --health-check serves /startup, /liveness and /readiness on port 9090, --http-address=0.0.0.0 lets the kubelet reach them, and --max-sigterm-delay gives open connections time to drain. Size the proxy's resources from load: memory grows with open connections and CPU with traffic. Clusters older than Kubernetes 1.29 put the proxy under containers instead, and so do pods using Istio or Cloud Service Mesh.

Use a language connector instead

The language connectors do the proxy's certificate and IAM work inside your process, and Google recommends them over the proxy for Go, Java and Python, with a Node.js connector as well. There is no second container to start first and stop last, and no unencrypted localhost hop. In Go, cloudsqlconn plugs into pgx as its dial function:

// main.go package main import ( "context" "fmt" "log" "net" "os" "cloud.google.com/go/cloudsqlconn" "github.com/jackc/pgx/v5/pgxpool" ) func newPool(ctx context.Context) (*pgxpool.Pool, func() error, error) { instance := os.Getenv("INSTANCE_CONNECTION_NAME") // my-project:europe-west1:orders-db user := os.Getenv("DB_IAM_USER") // orders-api@my-project.iam (service account email without .gserviceaccount.com) // IAM database authentication: no password, the dialer logs in with the // service account's OAuth2 token. Lazy refresh suits Cloud Run, where CPU // can be throttled between requests. d, err := cloudsqlconn.NewDialer(ctx, cloudsqlconn.WithIAMAuthN(), cloudsqlconn.WithLazyRefresh(), cloudsqlconn.WithDefaultDialOptions(cloudsqlconn.WithPrivateIP()), ) if err != nil { return nil, nil, err } cfg, err := pgxpool.ParseConfig(fmt.Sprintf("user=%s dbname=orders", user)) if err != nil { return nil, nil, err } cfg.MaxConns = 5 // Every connection the pool opens goes through the dialer's mTLS tunnel. cfg.ConnConfig.DialFunc = func(ctx context.Context, _, _ string) (net.Conn, error) { return d.Dial(ctx, instance) } pool, err := pgxpool.NewWithConfig(ctx, cfg) if err != nil { d.Close() return nil, nil, err } return pool, d.Close, nil } func main() { ctx := context.Background() pool, closeDialer, err := newPool(ctx) if err != nil { log.Fatal(err) } defer closeDialer() defer pool.Close() var who string if err := pool.QueryRow(ctx, "SELECT current_user").Scan(&who); err != nil { log.Fatal(err) } log.Printf("connected as %s", who) }

WithIAMAuthN makes the connector log in with the service account's token, so the DSN has no password, and WithLazyRefresh fetches certificates on demand instead of on a background timer, which matters on Cloud Run services with request-based billing, where CPU is throttled between requests. The proxy stays useful for languages without a connector and for tools like psql or a migration runner.

Cloud SQL Auth Proxy flags worth knowing

FlagWhat it does
--port / --addressLocal listener, 127.0.0.1 and the engine's default port unless set
--unix-socketListen on sockets in a directory instead of TCP
--private-ipConnect to the instance's private IP
--auto-iam-authnLog in with IAM database authentication
--health-checkServe /startup, /liveness, /readiness on --http-port (9090)
--max-sigterm-delayWait for connections to close after SIGTERM
--lazy-refreshFetch certificates on demand, for throttled CPU
--max-connectionsCap client connections; no limit by default
--quitquitquitAdmin endpoint on port 9091 to shut the proxy down, for Jobs on older clusters

Every flag can also be set as an environment variable with the CSQL_PROXY_ prefix, such as CSQL_PROXY_AUTO_IAM_AUTHN=true, as the proxy README describes.

How Encore connects to Cloud SQL

Encore

Encore handles the Cloud SQL connection as part of infrastructure from code: a database declared in a Go or TypeScript service becomes a database on a Cloud SQL for PostgreSQL instance that Encore provisions in a private network in your GCP project, with daily backups kept for 7 days and point-in-time recovery, as the GCP infrastructure docs describe. Encore provisions a service account for the service and connects it to the database itself, so the app has no proxy flag, sidecar, connector library or connection string to maintain.

Set up the app

Get started
brew install encoredev/tap/encore &&
encore app create
Copy

Run in your terminal to get started locally.

~
$ encore app create shop --example=hello-world$ cd shop && mkdir -p inventory/migrations
// inventory/inventory.go package inventory import ( "context" "encore.dev/beta/errs" "encore.dev/storage/sqldb" ) // On GCP this is a database on the environment's Cloud SQL for PostgreSQL // instance; under encore run it is a local Postgres. var db = sqldb.NewDatabase("inventory", sqldb.DatabaseConfig{ Migrations: "./migrations", }) type ReserveParams struct { SKU string `json:"sku"` Quantity int `json:"quantity"` } type Stock struct { SKU string `json:"sku"` Available int `json:"available"` } // Reserve takes stock only if enough is left, in a single statement, // so two concurrent orders cannot both take the last unit. // //encore:api public method=POST path=/inventory/reserve func Reserve(ctx context.Context, p *ReserveParams) (*Stock, error) { if p.SKU == "" || p.Quantity <= 0 { return nil, &errs.Error{Code: errs.InvalidArgument, Message: "sku and a positive quantity are required"} } s := &Stock{SKU: p.SKU} err := db.QueryRow(ctx, ` UPDATE stock SET available = available - $2 WHERE sku = $1 AND available >= $2 RETURNING available`, p.SKU, p.Quantity, ).Scan(&s.Available) if errs.Code(err) == errs.NotFound { return nil, &errs.Error{Code: errs.FailedPrecondition, Message: "not enough stock"} } return s, err }
-- inventory/migrations/1_create_stock.up.sql CREATE TABLE stock ( sku TEXT PRIMARY KEY, available INTEGER NOT NULL CHECK (available >= 0) ); INSERT INTO stock (sku, available) VALUES ('mug-blue', 3);
~/shop
$ encore run$ curl -X POST localhost:4000/inventory/reserve -d '{"sku":"mug-blue","quantity":2}'{"sku":"mug-blue","available":1}$ curl -X POST localhost:4000/inventory/reserve -d '{"sku":"mug-blue","quantity":2}'{"code":"failed_precondition","message":"not enough stock","details":null}

encore run starts Postgres locally and applies the migration, so day-to-day development needs no proxy and no access to the cloud database at all. The Go database docs cover queries, transactions and db.Stdlib() for libraries that expect database/sql.

Reaching cloud databases from your laptop

When you need the cloud database, for a one-off query or a BI tool, the Encore CLI plays the role the Auth Proxy plays on a laptop:

~/shop
# psql into staging, read-only unless you pass --write or --admin$ encore db shell inventory --env=staging # A local tunnel to the environment's databases for other tools$ encore db proxy --env=staging --port 5433 # A temporary connection string$ encore db conn-uri inventory --env=staging

Access goes through your Encore login and app permissions rather than a Google account with Cloud SQL Client on the project, and the managing infrastructure docs cover connecting external tools, including the CA certificate for Cloud SQL. To use an existing instance, importing a Cloud SQL instance points an environment at it instead of creating a new one.

AI coding agents can work against the same setup: an agent that adds a table writes the migration and the query in one change and checks it under encore run, with no instance connection name or credentials to hand it.

Best fit: teams on GCP that want Cloud SQL for PostgreSQL in their own project, connected to Cloud Run or GKE services.

Frequently asked questions

What does the Cloud SQL Auth Proxy do?

It runs next to your application, listens on a local TCP port or Unix socket, and forwards each connection to a Cloud SQL instance over TLS 1.3 using short-lived certificates it fetches with your IAM identity. Your app connects to localhost with a normal Postgres driver, and access is controlled by the cloudsql.instances.connect permission instead of authorized networks.

How do I run the Cloud SQL Auth Proxy locally?

Run gcloud auth application-default login, download the cloud-sql-proxy binary, and start it with your instance connection name, for example ./cloud-sql-proxy --port 5432 my-project:europe-west1:orders-db. Then connect psql or your app to 127.0.0.1:5432. Your Google account needs the Cloud SQL Client role.

How do I run the Cloud SQL Auth Proxy as a sidecar on GKE?

Add it to the pod under initContainers with restartPolicy: Always, which makes it a native sidecar on Kubernetes 1.29 and later, pass the instance connection name and --port, and give the pod a Kubernetes service account bound to a Google service account with roles/cloudsql.client through Workload Identity. The app then connects to 127.0.0.1 on that port.

Should I use the Cloud SQL Auth Proxy or a Cloud SQL connector?

Google recommends the language connectors for Go, Java and Python, and there is one for Node.js too. A connector does the same certificate and IAM work inside your process, so there is no second container to size, start before the app and shut down after it. The proxy is the choice for languages without a connector and for tools like psql.

Does Encore use the Cloud SQL Auth Proxy?

Encore provisions Cloud SQL in a private network for apps it deploys to GCP and connects services to it without any proxy flag, sidecar or connector in your code or manifests. Locally, encore run starts Postgres on your machine, and encore db proxy --env=NAME opens a local tunnel to a cloud environment's databases for other tools.

Deploy to your cloud on AWS and Google Cloud
without managing infrastructure

Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders