Connection failures

Connection failures are usually related to the address, account password, network path, SSL configuration, or connection count. First confirm whether you are using SDK, HTTP API, DMC, or a PostgreSQL direct connection.

Common symptoms

Symptom	Possible cause
password authentication failed	Wrong username or password, account revoked
connection timeout	Network unreachable, wrong address, access policy limitation
too many connections	Pool too large, connections not released, too many scaled instances
database does not exist	Wrong database name or mismatched instance information
SSL error	SSL configuration does not match instance requirements

Basic checks

1. Confirm that the host, port, database name, username, and password belong to the same instance.
2. Confirm that the account was not deleted or its password changed.
3. Confirm that the runtime environment can reach the database network.
4. Confirm that the connection pool does not exceed the database connection limit.
5. Confirm that the application uses the correct environment variables.

Verify with psql

Use psql from a machine that can access the database.

psql "host=$PGHOST port=$PGPORT dbname=$PGDATABASE user=$PGUSER sslmode=require"

If psql cannot connect, check network, account, and instance status first. If psql works but the app fails, check application config and connection pool code.

Connection exhaustion

View current connection states:

select state, count(*)
from pg_stat_activity
group by state
order by count(*) desc;

If there are too many idle connections, reduce pool max and idle timeout, and ensure manually acquired clients are released.

Cloud Functions and CloudBase Run

In elastic environments, do not create a connection pool for every request. Define the pool at module scope so runtime instances can reuse it.

If connections are still exhausted, evaluate maximum instance count, per-instance pool size, slow queries, and lock waits.

For more, see Connection management.