Postgres Management — Cloud SQL Access via Proxy

On-boarding and reference document for connecting to the Postgres instances hosted in Google Cloud SQL, using the Cloud SQL Auth Proxy (v2).

Scope: all Cloud SQL Postgres instances reachable through the shared connect-cloudsql script
Verified on: 2026-08-25
Proxy version: cloud-sql-proxy v2.8.0

1. Installing the Tooling

Two separate pieces of software are required. Installing the Google Cloud CLI does not give you the proxy — the modern v2 proxy is a standalone executable.

Prerequisites

Requirement	Value
Google Cloud SDK	Installed — see the official install guide
IAM	An account with access to the target projects, and Cloud SQL IAM database authentication enabled for it
Local ports	Each instance needs a free, unique local port (see the appendix)

Install the Cloud SQL Auth Proxy

Download the binary:

curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.8.0/cloud-sql-proxy.linux.amd64

Make it executable:

chmod +x cloud-sql-proxy

Move it onto your PATH (requires admin password):

sudo mv cloud-sql-proxy /usr/local/bin/

The URL above is the Linux/amd64 build. Use the matching artefact name for other platforms.

2. Creating the Connection Script

A single wrapper script clears any stale listeners and then opens one tunnel per instance, so all databases become available on localhost in one command.

Script contents

#!/bin/bash

# Create tunnels for Cloud SQL instances using query params for ports.
# This is the correct, modern syntax for the v2 proxy.
# Install this beforehand: curl -o cloud_sql_proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.8.0/cloud-sql-proxy.linux.amd64
# If desire, Move it to your PATH so the script can find it
# Note: Make sure you ran: sudo mv cloud_sql_proxy /usr/local/bin/

# gcloud auth application-default login

lsof -ti:33306 | xargs kill 2>/dev/null
lsof -ti:55434 | xargs kill 2>/dev/null
lsof -ti:33307 | xargs kill 2>/dev/null
lsof -ti:55435 | xargs kill 2>/dev/null
lsof -ti:55439 | xargs kill 2>/dev/null
lsof -ti:5432 | xargs kill 2>/dev/null
lsof -ti:55440 | xargs kill 2>/dev/null
lsof -ti:55441 | xargs kill 2>/dev/null
lsof -ti:55442 | xargs kill 2>/dev/null
lsof -ti:55443 | xargs kill 2>/dev/null


cloud-sql-proxy \
  --auto-iam-authn \
  --debug \
  "attracs-services-195009:europe-north1:attracs-sql?port=33306" \
  "attracs-backups:europe-north1:attracs-postgre-test?port=55434" \
  "att-nightly:europe-north1:attracs-sql-nightly?port=33307" \
  "pg-databases-nightly:europe-north1:pg-1-nightly?port=55435" \
  "pg-databases-stable:europe-north1:pg-1-stable?port=55439" \
  "attracs-logistics-nightly-6519:europe-north1:pg-road-nightly?port=5432" \
  "adi-eazytms-stable:europe-north1:pg-eazytms-stable?port=55440" \
  "attracs-logistics:europe-north1:pg-road-stable?port=55441"\
  "adi-eazytms-nightly:europe-north1:pg-eazytms-nightly?port=55442"

Install the script

The file can be given any name — connect-cloudsql is only a convention.

Create the file:

nano connect-cloudsql

Paste the script above, then save and exit. Any editor works; nano is used here for illustration.
Make it executable and move it onto your user PATH:

chmod +x connect-cloudsql

# Move it to your personal user bin folder so you can run it from anywhere
# (If the folder doesn't exist yet, run: mkdir -p ~/.local/bin)
mv connect-cloudsql ~/.local/bin/

3. Authenticating and Connecting

Before the first run you must authenticate with Google Cloud so the proxy has permission to reach the databases.

# Log in with your Google account
gcloud auth application-default login

# Run the script to open the database tunnels
connect-cloudsql

The proxy stays in the foreground while the tunnels are open. Leave the terminal running and connect your client to localhost on the relevant port.

4. Troubleshooting the gcloud Configuration

The Google Cloud CLI uses configurations (profiles) to determine which project you are working in. The Application Default Credentials (ADC) used by the proxy script rely on your active configuration to authenticate properly.

If the script produces connection or permission errors, the wrong configuration is most likely active.

Check the active configuration

gcloud config configurations list

Look at the IS_ACTIVE column — your main/default configuration must be True.

Switch configuration

gcloud config configurations activate <NAME_OF_CONFIGURATION>

For example gcloud config configurations activate default, or whichever configuration holds the correct default project.

Any time you switch the active configuration, refresh the application default credentials before running the script again:

gcloud auth application-default login
connect-cloudsql

5. Adding a New Database to the Script

When a new database is created in Google Cloud, add it to connect-cloudsql so it is tunnelled alongside the others.

Connection string format

The proxy identifies an instance by its connection name, combined with the local port to bind:

"PROJECT_ID:REGION:INSTANCE_NAME?port=LOCAL_PORT"

Worked example — "attracs-services-195009:europe-north1:attracs-sql?port=33306":

Part	Value	Meaning
Project ID	`attracs-services-195009`	The exact Google Cloud project where the database lives
Region	`europe-north1`	The physical Google Cloud region hosting the database
Instance name	`attracs-sql`	The actual name of the Cloud SQL database instance
Local port	`?port=33306`	The port on your own machine used to reach this database

Every database in the script must have a unique local port.

Update the script

Two edits are required per new instance.

Add a kill command at the top. Find the list of lsof commands and add one for the new port, so it is cleared before the proxy tries to bind it:

lsof -ti:NEW_PORT_NUMBER | xargs kill 2>/dev/null

Add the connection string at the bottom. Append it to the cloud-sql-proxy command, and put a backslash (\) at the end of the previous line so the shell knows the command continues.

Appendix — Current Instance and Port Map

Instance	Project	Region	Local port
`attracs-sql`	`attracs-services-195009`	`europe-north1`	`33306`
`attracs-postgre-test`	`attracs-backups`	`europe-north1`	`55434`
`attracs-sql-nightly`	`att-nightly`	`europe-north1`	`33307`
`pg-1-nightly`	`pg-databases-nightly`	`europe-north1`	`55435`
`pg-1-stable`	`pg-databases-stable`	`europe-north1`	`55439`
`pg-road-nightly`	`attracs-logistics-nightly-6519`	`europe-north1`	`5432`
`pg-eazytms-stable`	`adi-eazytms-stable`	`europe-north1`	`55440`
`pg-road-stable`	`attracs-logistics`	`europe-north1`	`55441`
`pg-eazytms-nightly`	`adi-eazytms-nightly`	`europe-north1`	`55442`

Notes:

Port 55443 is cleared by the script but not bound to any instance — a leftover from a removed tunnel.
pg-road-nightly binds the default Postgres port 5432, which will collide with a locally installed Postgres server. Stop the local service, or re-map this tunnel to a spare port.