How to Fix Cloud SQL Connection Refused in GCP

Simple explanation: where Cloud SQL connections break

When your application connects to Cloud SQL, the request passes through several layers. A failure at any layer produces a different error message.

Here is the path from your app to the database:

1. Your application or client sends a connection request to a host and port (or Unix socket).
2. Proxy or connector handles IAM auth and encryption. This could be the Cloud SQL Auth Proxy, a language connector, or the Cloud Run built-in connector.
3. Network path carries traffic through your VPC, VPC peering, or the public internet to reach the Cloud SQL instance.
4. Cloud SQL instance is the managed database engine that listens for incoming connections.
5. Database authentication is the final gate where the engine checks username, password or IAM token, SSL requirements, and grants.

“Connection refused” almost always means nothing is listening where your app is trying to connect: wrong host, wrong port, proxy not running, or wrong connection method. “Connection timed out” usually means the network path is broken: wrong VPC, missing peering, or a firewall blocking traffic. “Password authentication failed” or “SSL required” means the connection reached the database but was rejected at the auth layer.

Quick diagnosis: match your error to the fix

Find your error message in the table below. Each row points to the most likely cause and the section that covers the fix.

How Cloud SQL connections work

Cloud SQL supports three main connection patterns. Choosing the wrong one is the most common cause of connection failures.

Cloud SQL Auth Proxy and language connectors

The Auth Proxy runs as a local process (or sidecar) and creates an authenticated, encrypted tunnel to Cloud SQL. Your application connects to 127.0.0.1 or a Unix socket, and the proxy handles IAM auth and TLS behind the scenes. Language-specific connectors (Python, Java, Go, Node.js) do the same thing as a library instead of a sidecar.

Best for: local development, GKE sidecars, VMs, and any environment where you want automatic certificate management. This is the recommended secure connection method.

Private IP (direct TCP)

Cloud SQL allocates a private IP address inside your VPC via private services access (VPC peering with Google). Applications in the same VPC connect directly over TCP without a proxy.

Best for: production services that already run inside the VPC and need minimal latency or cannot run a sidecar.

Public IP with authorised networks

Cloud SQL exposes a public IP and you allowlist specific client CIDRs. Traffic goes over the internet (encrypted by SSL).

Best for: quick testing, legacy apps, or environments where running a proxy is not possible. Not recommended for production. Use Auth Proxy or private IP instead.

Fix 1: Auth Proxy or Cloud SQL connector issues

Most “connection refused on 127.0.0.1” errors during local development mean the Auth Proxy is not running, is running on a different port, or the service account lacks permissions.

Check that the proxy is running and listening

# Start the Auth Proxy for PostgreSQL on port 5432
./cloud-sql-proxy --port=5432 PROJECT_ID:REGION:INSTANCE_NAME

# For MySQL, use port 3306
./cloud-sql-proxy --port=3306 PROJECT_ID:REGION:INSTANCE_NAME

# Verify it is listening
# Linux/macOS:
ss -tlnp | grep 5432
# Windows:
netstat -an | findstr 5432

If the proxy is running but your app still gets connection refused, confirm your app is connecting to exactly the same host and port the proxy is listening on. A mismatch of even one digit causes a refusal.

Grant the required IAM role

The service account running the proxy needs roles/cloudsql.client. Without it, the proxy starts but silently fails every connection attempt. This is the single most common Auth Proxy problem. See Permission Denied Errors for more on IAM troubleshooting.

# Grant Cloud SQL Client role to the proxy's service account
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:my-sa@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/cloudsql.client"

Verify the instance connection name

# Get the exact instance connection name
gcloud sql instances describe INSTANCE_NAME \
  --format="value(connectionName)"

# Output format: PROJECT_ID:REGION:INSTANCE_NAME
# This must match exactly what you pass to the proxy

Fix 2: Cloud Run and Cloud Functions connectivity

Cloud Run and Cloud Functions handle Cloud SQL connections differently from VMs or containers. The most common mistake is using a TCP connection string (127.0.0.1:5432) when the platform expects a Unix socket.

Built-in Cloud SQL connector (recommended)

When you attach a Cloud SQL instance to Cloud Run, the platform creates a Unix socket at /cloudsql/PROJECT_ID:REGION:INSTANCE_NAME. Your app must connect to this socket path, not to a TCP host and port.

# Attach the Cloud SQL instance to Cloud Run
gcloud run services update my-service \
  --region=REGION \
  --add-cloudsql-instances=PROJECT_ID:REGION:INSTANCE_NAME

# In your app, connect to the Unix socket:
# PostgreSQL: host=/cloudsql/PROJECT_ID:REGION:INSTANCE_NAME
# MySQL:      socket=/cloudsql/PROJECT_ID:REGION:INSTANCE_NAME
# Do NOT use: host=127.0.0.1 port=5432

Service account permissions

The Cloud Run (or Cloud Functions) service account needs roles/cloudsql.client. If the service account lacks this role, connections fail with an authentication error from the Cloud SQL API even though the socket path is correct.

# Check the service account used by your Cloud Run service
gcloud run services describe my-service \
  --region=REGION \
  --format="value(spec.template.spec.serviceAccountName)"

# Grant the role
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
  --role="roles/cloudsql.client"

Private IP options for serverless workloads

If you need to connect to Cloud SQL via private IP from Cloud Run (instead of using the built-in connector), you have several options:

• Direct VPC egress lets Cloud Run send traffic directly into your VPC without a separate connector resource. Configure this with —network and —subnet flags, or through the VPC access settings in the console. This avoids the overhead of a dedicated Serverless VPC Access connector.
• Serverless VPC Access connector is a dedicated connector resource that routes traffic from Cloud Run into your VPC. Still supported and works well, but direct VPC egress is simpler for new deployments.

# Option A: Direct VPC egress (no separate connector needed)
gcloud run services update my-service \
  --region=REGION \
  --network=my-vpc \
  --subnet=my-subnet \
  --vpc-egress=private-ranges-only

# Option B: Serverless VPC Access connector
gcloud run services update my-service \
  --region=REGION \
  --vpc-connector=my-vpc-connector \
  --vpc-egress=private-ranges-only

Fix 3: Private IP routing issues

Cloud SQL private IPs are allocated inside a Google-managed VPC that is peered to your project VPC via private services access. If your application is outside that peered network, the private IP is unreachable and the connection times out.

Verify the network and peering

# Check which VPC the Cloud SQL instance is peered with
gcloud sql instances describe INSTANCE_NAME \
  --format="value(settings.ipConfiguration.privateNetwork)"

# Check whether private services access is configured
gcloud services vpc-peerings list \
  --network=my-vpc \
  --service=servicenetworking.googleapis.com

# Get the private IP address
gcloud sql instances describe INSTANCE_NAME \
  --format="value(ipAddresses[].ipAddress)"

Common private IP failures

• Client not in the same VPC. Your VM, GKE pod, or Cloud Run service must be in the VPC that is peered with Cloud SQL, or in a VPC that has connectivity to it. If you are connecting from a different VPC, you need VPC peering or a shared VPC setup.
• Private services access not configured. The google-managed-services-* peering must exist between your VPC and Google’s service networking. Without it, the private IP range is not routed.
• Subnet range conflict. The allocated IP range for private services must not overlap with your existing subnet ranges.
• Timeout vs refused. A timeout means the packet is being dropped (routing issue). A refusal means something is listening but rejecting the connection (wrong port, or the IP belongs to a different service). Use VPC Connectivity Tests to trace the exact failure point.

# Test connectivity from a VM in the same VPC
# Replace PRIVATE_IP with the Cloud SQL private IP
nc -zv PRIVATE_IP 5432

# If this times out, the routing or peering is broken
# If this connects, the network path is fine and the issue is elsewhere

Fix 4: Public IP and authorised networks

Connecting via public IP without the Auth Proxy requires your source IP to be in the Cloud SQL instance’s authorised networks list. This is a separate allowlist from VPC firewall rules.

When public IP is acceptable

Public IP is fine for quick local testing or one-off admin access. It is weaker operationally than Auth Proxy or private IP because you must maintain an IP allowlist that drifts as your infrastructure changes.

Common public IP mistakes

• Adding your home IP but deploying to cloud. The deployed service has a different egress IP. The connection works locally but fails in production.
• Using broad CIDRs. Adding 0.0.0.0/0 opens the database to the entire internet. Never do this. If you need broad access, use the Auth Proxy instead.
• Dynamic IP changes. Home ISPs reassign IPs regularly. Your authorised network entry goes stale and connections start failing. The Auth Proxy avoids this entirely.

# Add an authorised network
gcloud sql instances patch INSTANCE_NAME \
  --authorized-networks=203.0.113.10/32

# View current authorised networks
gcloud sql instances describe INSTANCE_NAME \
  --format="value(settings.ipConfiguration.authorizedNetworks)"

# Check your current external IP
curl -s ifconfig.me

Fix 5: SSL/TLS and database authentication

If the TCP connection reaches the database but is rejected, the problem is at the database engine level. These errors look different from network-level failures. See Troubleshooting Authentication Errors for a deeper guide on auth issues.

SSL mode mismatch

# Check the SSL mode on the instance
gcloud sql instances describe INSTANCE_NAME \
  --format="value(settings.ipConfiguration.sslMode)"

# ENCRYPTED_ONLY: SSL required, no client cert needed
# TRUSTED_CLIENT_CERTIFICATE_REQUIRED: SSL + client cert required
# ALLOW_UNENCRYPTED_AND_ENCRYPTED: SSL optional

If the instance requires SSL and your client connects without it, the connection is dropped immediately. The Auth Proxy handles SSL automatically, so if you use the proxy you do not need to configure SSL in your application.

Wrong username or password

# List database users
gcloud sql users list --instance=INSTANCE_NAME

# Reset a user's password
gcloud sql users set-password USER_NAME \
  --instance=INSTANCE_NAME \
  --password=NEW_PASSWORD

IAM database authentication

IAM database authentication uses IAM tokens instead of passwords. If you configured an IAM user but are passing a password (or vice versa), authentication fails. These are distinct user types. A built-in database user and an IAM database user are not interchangeable.

# Create an IAM-authenticated database user
gcloud sql users create SERVICE_ACCOUNT_EMAIL \
  --instance=INSTANCE_NAME \
  --type=CLOUD_IAM_SERVICE_ACCOUNT

# The Auth Proxy can handle IAM DB auth automatically:
./cloud-sql-proxy --auto-iam-authn PROJECT_ID:REGION:INSTANCE_NAME

User exists but has no grants

A user can authenticate successfully but have no permissions on any database. This produces “permission denied” errors at the SQL level, not during connection. Connect as a privileged user and grant the necessary permissions. For PostgreSQL, use GRANT statements. For MySQL, use GRANT or ALTER USER.

When to use this guide

This page covers Cloud SQL connection troubleshooting for these scenarios:

• Local development with the Auth Proxy connecting from your workstation.
• Cloud Run using the built-in Cloud SQL connector, direct VPC egress, or Serverless VPC Access.
• Cloud Functions using the same connector patterns as Cloud Run.
• VMs and GKE connecting via Auth Proxy sidecar, private IP, or public IP.
• Teams using private IP who need to diagnose VPC peering, routing, and private services access issues.
• SSL and IAM auth issues including certificate mismatches, password failures, and IAM token problems.

If your error is not Cloud SQL specific (for example, a general VPC routing problem), see Debugging VPC Connectivity instead.

Auth Proxy vs private IP vs public IP

Choosing the wrong connection method is the root cause of many Cloud SQL failures. Use this table to pick the right one.