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 PostgreSQL protocol access. When using protocol access, confirm whether you connect to the database instance or the pool.
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
- Confirm that the host, port, database name, username, and password belong to the same instance, or to the same pool entry point.
- Confirm that the account was not deleted or its password changed.
- Confirm that the runtime environment can reach the database network.
- Confirm that the connection pool does not exceed the database connection limit.
- 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.