Google Cloud SQL for PostgreSQL¶

Constraints¶

Custom extensions cannot be installed. pg_relay is deployed via SQL, as described in Why the Extension Can't Just Be Installed.
The postgres user has the cloudsql_superuser role, not a true PostgreSQL superuser. It has enough privileges for every pg_relay setup step regardless.
Google strongly recommends connecting via the Cloud SQL Auth Proxy rather than directly to the instance's IP address. The proxy handles SSL and IAM (Identity and Access Management) authentication automatically, and is required for instances that do not have a public IP address.

Connection method: proxy vs direct IP¶

Method	When to use
Cloud SQL Auth Proxy	Recommended. Required for private-IP instances. Handles SSL and IAM authentication automatically.
Direct IP	Public-IP instances only. Requires authorised network rules and SSL.

The steps below use the Auth Proxy. Direct IP instructions follow in Step 5 (alternate).

Step 1 — Install the Cloud SQL Auth Proxy¶

On the machine where you will run the setup commands:

# Linux AMD64
curl -o cloud-sql-proxy \
  https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.14.0/cloud-sql-proxy.linux.amd64
chmod +x cloud-sql-proxy
sudo mv cloud-sql-proxy /usr/local/bin/

For macOS and other platforms, see the Cloud SQL Auth Proxy documentation.

Step 2 — Start the proxy¶

Find your instance's connection name in the Cloud SQL Console (format: project:region:instance):

cloud-sql-proxy --port 5432 your-project:us-central1:your-instance &

The proxy listens on 127.0.0.1:5432. The machine running the proxy needs the Cloud SQL Client IAM role, either on its service account, or via gcloud auth application-default login for a user account.

Step 3 — Deploy the pgrelay schema¶

With the proxy running, connect via localhost. No SSL configuration is needed here — the proxy handles it for you:

psql -h 127.0.0.1 \
     -U postgres \
     -d your_database \
     -c "CREATE SCHEMA pgrelay;"

psql -h 127.0.0.1 \
     -U postgres \
     -d your_database \
     -f sql/pg_relay--1.0.sql

psql -h 127.0.0.1 \
     -U postgres \
     -d your_database \
     -f sql/pg_relay--1.0--1.1.sql

ALTER ROLE pgrelay WITH LOGIN PASSWORD 'choose-a-strong-password';

When using the proxy, the Processor connects to the proxy locally. Create the .pgpass file using the proxy's address:

127.0.0.1:5432:your_database:pgrelay:choose-a-strong-password

chmod 600 ~/.pgpass

Processor environment variables. Note PGSSLMODE=disable here — the connection between the Processor and the proxy is local and does not need encryption; the proxy's own connection to Cloud SQL is always encrypted regardless:

PGHOST=127.0.0.1
PGPORT=5432
PGDATABASE=your_database
PGUSER=pgrelay
PGPASSFILE=/path/to/.pgpass
PGSSLMODE=disable

The proxy must run on the same machine as the Processor. See Running the Processor for running both as systemd services together.

Step 5 (alternate) — Direct IP connection¶

Use this only if your instance has a public IP address and you are not using the Auth Proxy.

In the Cloud SQL Console, go to your instance → Connections → Networking → Authorised networks, and add the IP address of the machine running the Processor.

Processor environment variables for a direct connection:

PGHOST=<cloud-sql-public-ip>
PGPORT=5432
PGDATABASE=your_database
PGUSER=pgrelay
PGPASSFILE=/path/to/.pgpass
PGSSLMODE=require

The .pgpass entry uses the public IP:

<cloud-sql-public-ip>:5432:your_database:pgrelay:choose-a-strong-password

High availability¶

Cloud SQL's HA mode pairs a primary with a standby in the same region. Failover is automatic, and the instance's FQDN (fully qualified domain name) or proxy connection name always routes to the current primary. The Processor's reconnect loop handles the outage without any configuration change on your part.

Continue to Other Cloud Providers.