GcpHow-ToBeginner · 4 min read

How to Use Cloud Run with Cloud SQL on Google Cloud

To use Cloud Run with Cloud SQL, deploy your Cloud Run service with the Cloud SQL instance connection name and enable the Cloud SQL Auth proxy by adding the --add-cloudsql-instances flag. Then, connect to the database using the Unix socket path or TCP with proper credentials inside your service.

📐

Syntax

When deploying a Cloud Run service that connects to Cloud SQL, use the following pattern:

gcloud run deploy SERVICE_NAME: Deploys your Cloud Run service.
--image IMAGE_URL: Specifies the container image.
--add-cloudsql-instances INSTANCE_CONNECTION_NAME: Enables the Cloud SQL Auth proxy for your Cloud SQL instance.
--set-env-vars: Sets environment variables like database user, password, and socket path.

Inside your service, connect to Cloud SQL using the Unix socket at /cloudsql/INSTANCE_CONNECTION_NAME or TCP on localhost with the proxy.

bash

gcloud run deploy SERVICE_NAME \
  --image IMAGE_URL \
  --add-cloudsql-instances INSTANCE_CONNECTION_NAME \
  --set-env-vars DB_USER=your_user,DB_PASS=your_pass,DB_NAME=your_db \
  --region REGION

💻

Example

This example shows deploying a Cloud Run service that connects to a Cloud SQL Postgres instance using environment variables and the Cloud SQL Auth proxy.

bash

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

# Inside your app, connect using the Unix socket:
# socketDir = '/cloudsql/my-project:us-central1:my-instance'
# Connect string example (Postgres):
# postgresql://postgres:secretpassword@/mydb?host=/cloudsql/my-project:us-central1:my-instance

Output

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

⚠️

Common Pitfalls

Common mistakes when using Cloud Run with Cloud SQL include:

Not specifying the --add-cloudsql-instances flag, so the proxy is not enabled.
Using incorrect instance connection name format (should be project:region:instance).
Failing to set environment variables for database credentials.
Trying to connect via TCP without the proxy or proper IP whitelisting.
Not granting the Cloud Run service account the Cloud SQL Client role.

Example of wrong and right deployment:

Wrong:
gcloud run deploy my-service --image gcr.io/my-project/my-app:latest

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

📊

Quick Reference

Tips for smooth Cloud Run and Cloud SQL integration:

Always use the Cloud SQL Auth proxy via --add-cloudsql-instances.
Use Unix socket path /cloudsql/INSTANCE_CONNECTION_NAME inside your app.
Set database credentials as environment variables, not hardcoded.
Grant your Cloud Run service account the Cloud SQL Client IAM role.
Test your connection locally with the Cloud SQL Auth proxy before deploying.

✅

Key Takeaways

Use the --add-cloudsql-instances flag to enable Cloud SQL Auth proxy in Cloud Run.

Connect to Cloud SQL via Unix socket at /cloudsql/INSTANCE_CONNECTION_NAME inside your service.

Set database credentials securely using environment variables.

Grant Cloud Run service account the Cloud SQL Client role for access.

Test connections locally with the Cloud SQL Auth proxy before deploying.