highIntermediateUSE#cloud sql#connections#limit#too many connections

Cloud SQL connection limit hit — too many connections

App logs show 'too many connections' from the database driver

Likely source:availabilityperformance

Focused incident mode — strips away everything but this runbook.

Symptoms

  • App logs show 'too many connections' from the database driver
  • Cloud SQL metrics show current connections at the limit
  • New query attempts hang or fail intermittently
  • gcloud sql instances describe shows the connection limit reached

The fastest relief is trimming stale idle sessions; the durable fix is right-sizing the pool so (replicas × pool) stays well under the tier's max_connections.

Evidence to grab

Collect these artifacts before you change anything — they prove (or rule out) each cause.

  • Connection count vs limit

    gcloud sql instances describe <INSTANCE> --format='value(settings.tier,settings.databaseFlags)'

  • Database-level connection metrics

    gcloud monitoring metrics list --filter='metric.type=cloudsql.googleapis.com/database/postgresql/num_backends' --format='value(metric.type)'

Diagnostic flow

Run the steps in order, marking each claim confirmed or refuted. The evidence you gather feeds the ranked causes below.

Guided decision tree is ready.

Steps with commands, expected output, and pass/fail branches.

Ranked root causes

Evidence checklist

  • App has multiple replicas each with a large pool
  • num_backends/num_client_conns hits the limit at peak
  • Reducing replicas frees connections immediately

Confirm before fixing

gcloud sql instances describe <INSTANCE> --format='value(settings.activeConnections)'
READ

Confirm the live connection count

Fix

gcloud sql instances patch <INSTANCE> --database-flags=max_connections=<HIGHER_VALUE>
CHANGE

Raise max_connections via a database flag

Expected: Updated [<INSTANCE>].

Resolution runbook

Apply from top to bottom after the cause is confirmed. Review every command before running it — risk tags are shown on each.

1
gcloud sql instances describe <INSTANCE> --format='value(settings.tier,settings.activeConnections)'
READ

Confirm the connection ceiling

2
SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE state='idle' AND age(now(), state_change) > interval '10 minutes';
CHANGE

Clear stale idle sessions to free connections immediately

3
gcloud sql instances patch <INSTANCE> --database-flags=max_connections=<HIGHER_VALUE>
CHANGE

Raise the connection limit (or scale the tier)

4
gcloud sql instances describe <INSTANCE> --format='value(settings.activeConnections)'
READ

Verify connections drop below the limit

Prevention

  • Size connection pools so replicas × poolMax fits under max_connections.
  • Set idle timeouts and connectionLifeTime on the pool.
  • Alert on active connections above ~80% of max_connections.
  • Review tier capacity when adding replicas or scaling traffic.

Related runbooks

Same stack, same failure family — worth a skim.

Cloud SQL read replica lagging behind primaryhigh

Reads from the replica return stale data

Google CloudAdvancedUSE3 causes
Open runbook
Cloud SQL storage auto-grow failed — disk fullcritical

gcloud sql instances describe shows dataDiskSizeGb at capacity

Google CloudIntermediateUSE3 causes
Open runbook

Commands marked READ CHANGE DESTRUCTIVE — never run DESTRUCTIVE commands against production data you cannot restore. Copy → verify → execute.