Google Cloud SQL Connection

Connect ForceCnx to a Cloud SQL for PostgreSQL instance using the native Cloud SQL connector. No public IP required.

Prerequisites

A Google Cloud project with the Cloud SQL Admin API enabled
A Cloud SQL for PostgreSQL instance
A GCP service account with appropriate permissions

Step 1: Create a Service Account

Create the service account

In the Google Cloud Console, go to IAM & Admin → Service Accounts and create a new service account for ForceCnx.

# Using gcloud CLI
gcloud iam service-accounts create forcecnx-reader \
  --display-name="ForceCnx Database Reader"

Grant Cloud SQL Client role

Assign the Cloud SQL Client role to the service account. This allows it to connect to Cloud SQL instances in the project.

gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:forcecnx-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/cloudsql.client"

Download the service account key

Create and download a JSON key file for the service account. You'll upload this to ForceCnx.

gcloud iam service-accounts keys create key.json \
  --iam-account=forcecnx-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com

Step 2: Configure IAM Database Authentication (Optional)

Recommended: IAM database authentication eliminates the need for a static database password. The service account authenticates directly to PostgreSQL using its GCP identity.

To use IAM auth, enable it on your Cloud SQL instance and create a database user mapped to the service account:

# Enable IAM authentication on the instance
gcloud sql instances patch YOUR_INSTANCE \
  --database-flags=cloudsql.iam_authentication=on

# Create an IAM database user
gcloud sql users create forcecnx-reader@YOUR_PROJECT_ID.iam \
  --instance=YOUR_INSTANCE \
  --type=CLOUD_IAM_SERVICE_ACCOUNT

Then grant the IAM user access to your tables:

-- Connect to your database and run:
GRANT USAGE ON SCHEMA public TO "forcecnx-reader@YOUR_PROJECT_ID.iam";
GRANT SELECT ON TABLE customers, orders TO "forcecnx-reader@YOUR_PROJECT_ID.iam";

Step 3: Create the Connection in ForceCnx

Open the New Connection form

From your ForceCnx Dashboard, click + New Connection and select the GCP Cloud SQL tab.

Enter connection details

Fill in your Cloud SQL connection parameters:

Field	Description	Example
`Instance Connection Name`	Found on the Cloud SQL instance overview page	`my-project:us-central1:my-db`
`Database`	Database name	`myapp`
`Username`	Database user (or IAM user)	`forcecnx_reader`
`Password`	Database password (leave blank if using IAM auth)	—
`Use IAM Auth`	Enable for IAM database authentication	Checked
`Service Account JSON`	Paste the contents of your key.json file	—

Test and save

Click Create Connection. ForceCnx uses the Cloud SQL connector to establish a secure tunnel to your instance — no public IP or firewall rules needed.

How It Works

ForceCnx uses Google's Cloud SQL connector library to connect to your instance. This provides:

No public IP required — The connector establishes a secure tunnel using the Cloud SQL Admin API
Automatic SSL — All connections are encrypted with managed certificates
IAM authentication — Eliminate static passwords with GCP identity-based access

Security: Keep your service account key JSON secure. ForceCnx encrypts it at rest using AES-256-GCM, but you should also restrict access to the key in GCP and rotate it periodically.

Next Steps

Once connected, follow the Getting Started guide to map entities, configure field mappings, and set up Salesforce Connect.