Connect to the database (SQL)¶

What this is: opening a direct SQL connection to a deployment's PostgreSQL database from your laptop, using a GUI client like DataGrip, psql, or any JDBC tool. When you'd do it: inspecting or debugging live data — chat history, principals, track hits — that the app doesn't surface in its UI. How long it takes: about five minutes the first time (installing the proxy and getting IAM access), seconds thereafter.

Who can do this: a developer or infra operator whose Google account holds roles/cloudsql.client on the waypoint-servers project. This is not an operator task — it needs a GCP identity, not a Directory login.

The databases run on Cloud SQL with no authorised networks and ssl_mode = ENCRYPTED_ONLY. That means you cannot point a client straight at a host:port — there is no public endpoint to dial. The only way in is the Cloud SQL Auth Proxy, which opens a local tunnel authenticated by your own GCP IAM (not by IP allow-listing). You run the proxy on your laptop; your client connects to localhost.

Which database¶

server-demo has no SQL database. The two Cloud SQL instances are:

Stack	Connection name	Database	App user	Password secret
web-demo	`waypoint-servers:europe-west2:bedrock-web-demo`	`waypoint`	`waypoint`	`bedrock-web-demo-db-password`
auth	`waypoint-servers:europe-west2:bedrock-auth`	`waypoint_directory`	`waypoint`	`bedrock-auth-db-password`

The waypoint user is the app's runtime role (limited grants). For schema/superuser work use the postgres user instead, with the …-cloudsql-postgres secret.

The shape of it¶

flowchart LR
    A["Auth Proxy on<br/>your laptop"] -->|"IAM-authenticated<br/>TLS tunnel"| B["Cloud SQL<br/>instance"]
    C["DataGrip / psql"] -->|"localhost:5433"| A

The proxy holds the only connection to Cloud SQL; your client only ever sees localhost.

Before you start¶

You have the gcloud CLI installed and are logged in to your @bedrockdefence.com account.
Your account has roles/cloudsql.client (granted below if not).
You have a SQL client — these steps use DataGrip, but psql or any JDBC tool works.

Steps¶

Log in to gcloud and set the project.

gcloud auth login
gcloud config set project waypoint-servers
gcloud auth application-default login   # the proxy reads these ADC credentials

Check you have cloudsql.client.

gcloud projects get-iam-policy waypoint-servers \
  --flatten="bindings[].members" \
  --filter="bindings.role:roles/cloudsql.client" \
  --format="value(bindings.members)"

If your account isn't listed, ask a project admin to grant it (or run this yourself if you hold project admin):

gcloud projects add-iam-policy-binding waypoint-servers \
  --member="user:you@bedrockdefence.com" \
  --role="roles/cloudsql.client"

Install the Auth Proxy.

brew install cloud-sql-proxy

(Or grab the v2 binary from the GoogleCloudPlatform/cloud-sql-proxy releases.)

Start the proxy — pick the connection name from the table above. Leave this running in its own terminal:

cloud-sql-proxy --port 5433 \
  waypoint-servers:europe-west2:bedrock-web-demo

It prints Listening on 127.0.0.1:5433 and The proxy has started successfully. The proxy terminates TLS for you — your client does not need any cert or SSL config.

Fetch the password for the user you're connecting as:

gcloud secrets versions access latest \
  --secret=bedrock-web-demo-db-password \
  --project=waypoint-servers

Connect from DataGrip. New data source → PostgreSQL, then:

Field	Value
Host	`localhost`
Port	`5433`
Database	`waypoint`
User	`waypoint`
Password	(from step 5)
SSL	off — the proxy already encrypts

The equivalent JDBC URL is:

jdbc:postgresql://localhost:5433/waypoint

Note the connection name (waypoint-servers:europe-west2:bedrock-web-demo) is not a hostname — it goes in the proxy command, never in the JDBC URL.

How to know it worked¶

The proxy terminal shows The proxy has started successfully and stays running.
DataGrip's Test Connection returns green, and the schema tree populates with the app's tables.
psql "host=localhost port=5433 dbname=waypoint user=waypoint" connects and \dt lists tables.

If something goes wrong¶

connection refused from the client. The proxy isn't running, or you used a different port. Check the proxy terminal is still up and that your port matches --port.
Proxy exits with a permission/IAM error. Your account lacks cloudsql.client, or gcloud auth application-default login was never run. Redo steps 1–2.
password authentication failed. You fetched the wrong secret, or mixed up the waypoint vs postgres user. The app user and superuser have different passwords — match the user to its secret.
Client insists on SSL / cert errors. Turn SSL off in the client. The proxy handles encryption end-to-end; layering client SSL on top of localhost breaks it.

Direct JDBC without the proxy (advanced)¶

If you can't run a separate proxy process, the postgres-socket-factory lets the JDBC driver dial Cloud SQL itself via IAM. Add the jar (plus its dependencies) to your driver and use:

jdbc:postgresql:///waypoint?cloudSqlInstance=waypoint-servers:europe-west2:bedrock-web-demo&socketFactory=com.google.cloud.sql.postgres.SocketFactory

It's more setup than the proxy for no real gain — prefer the proxy unless you have a reason.