GcpHow-ToBeginner · 4 min read

How to Connect Cloud Run to Cloud SQL on GCP

To connect Cloud Run to Cloud SQL, deploy your Cloud Run service with the Cloud SQL instance connection name and enable the Cloud SQL Auth proxy by specifying the --add-cloudsql-instances flag. Then, configure your application to connect to the database using the Unix socket or TCP connection provided by the proxy.

📐

Syntax

Use the gcloud run deploy command with the --add-cloudsql-instances flag to connect Cloud Run to Cloud SQL. Your app connects to the database via a Unix socket path or TCP host and port.

--add-cloudsql-instances=INSTANCE_CONNECTION_NAME: Specifies the Cloud SQL instance to connect.
INSTANCE_CONNECTION_NAME: Found in Cloud SQL instance details, format project:region:instance.
Set environment variables for DB user, password, and name.

bash

gcloud run deploy SERVICE_NAME \
  --image=IMAGE_URL \
  --add-cloudsql-instances=PROJECT:REGION:INSTANCE \
  --set-env-vars=DB_USER=youruser,DB_PASS=yourpass,DB_NAME=yourdb \
  --region=REGION \
  --platform=managed

💻

Example

This example deploys a Cloud Run service named my-service connected to a Cloud SQL instance my-project:us-central1:my-instance. The app uses environment variables to connect to a PostgreSQL database via Unix socket.

bash

gcloud run deploy my-service \
  --image=gcr.io/my-project/my-app-image \
  --add-cloudsql-instances=my-project:us-central1:my-instance \
  --set-env-vars=DB_USER=postgres,DB_PASS=secretpassword,DB_NAME=mydb \
  --region=us-central1 \
  --platform=managed

Output

Deploying service [my-service]... Done. Service URL: https://my-service-xyz.a.run.app

⚠️

Common Pitfalls

Not enabling the Cloud SQL Admin API causes connection failures.
Missing --add-cloudsql-instances flag means the Cloud SQL Auth proxy won't run.
Incorrect instance connection name format leads to errors.
Not setting correct environment variables for DB credentials causes authentication errors.
Trying to connect via TCP without configuring the proxy or public IP is insecure and often blocked.

bash

Wrong (missing Cloud SQL instances):
gcloud run deploy my-service \
  --image=gcr.io/my-project/my-app-image \
  --region=us-central1 \
  --platform=managed

Right (with Cloud SQL instances):
gcloud run deploy my-service \
  --image=gcr.io/my-project/my-app-image \
  --add-cloudsql-instances=my-project:us-central1:my-instance \
  --region=us-central1 \
  --platform=managed

📊

Quick Reference

Remember these key points when connecting Cloud Run to Cloud SQL:

Use --add-cloudsql-instances to enable the Cloud SQL Auth proxy.
Set environment variables for database credentials securely.
Connect using Unix socket path /cloudsql/INSTANCE_CONNECTION_NAME inside your app.
Enable the Cloud SQL Admin API in your GCP project.
Grant your Cloud Run service the Cloud SQL Client IAM role.

✅

Key Takeaways

Always deploy Cloud Run with the --add-cloudsql-instances flag to enable secure Cloud SQL connections.

Use environment variables to pass database credentials safely to your Cloud Run service.

Connect to Cloud SQL using the Unix socket path /cloudsql/INSTANCE_CONNECTION_NAME inside your app.

Ensure Cloud SQL Admin API is enabled and Cloud Run has Cloud SQL Client role.

Avoid using public IPs for Cloud SQL; prefer the Cloud SQL Auth proxy for security.