Database error catalogue

1. An honest note about verbatim strings

The Cloud SQL pages read for this release publish no verbatim connection error messages. So this catalogue is indexed by symptom and configuration rather than by string, and it says so rather than inventing plausible-looking messages. Engine-level errors (FATAL: from PostgreSQL, ERROR 1045 from MySQL) come from the engine, not from Google Cloud, and are documented by the engine's own project.

Where this hub does hold a verbatim string for a database-caused failure, it is a Cloud Run string — §4 — because that is where the failure surfaces.

2. Cannot connect

Symptom	Cause	Check	Fix
connection refused or hangs, from inside Google Cloud	the instance has private IP and the client is not on a network that reaches it	which connection path is configured? Is the client in the VPC, or reaching it over Private Service Connect / private services access?	put the client in the VPC, or use a connector
connection refused from outside Google Cloud, instance has a public IP	authorized networks does not include the caller	what is in the authorized-networks list?	the vendor's own recommendation: "If you're connecting to an instance by a public IP address, use a Cloud SQL connector (either the Cloud SQL Auth Proxy or one of the Cloud SQL Language Connectors)." An allowlist of addresses is the weaker answer
the connector itself cannot connect	the client identity lacks roles/cloudsql.client	does the workload's service account hold it?	grant roles/cloudsql.client. This is an IAM failure wearing a database costume
authentication fails with a correct password	the user is an IAM database authentication user, not a built-in one — or the reverse	which authentication type is this user? Built-in uses a username and password; IAM uses a short-lived access token for an IAM principal	use the matching mechanism. A password will never work for an IAM user

3. Available, then briefly not

Symptom	Cause	Check	Fix
the instance restarted, apparently unprompted	a maintenance update — the one update category that "require[s] an instance restart", causing downtime	was it inside the configured maintenance window?	schedule the window at creation. If the restart itself is intolerable, that is the Enterprise Plus argument: it can achieve "sub-second downtime"
a failover happened	HA uses a standby VM in another zone; that is the mechanism working	—	ensure the client reconnects. A connection pool that does not retry turns a designed failover into an outage

4. The cross-family row, and it is the most common of all

A Cloud Run service that cannot reach its database frequently presents as:

HTTP 503  The request failed because the instance could not start successfully.

whose documented causes include missing secrets, IAM, and network configuration. In practice the order to check is:

1. can the runtime identity read the secret holding the connection details?

roles/secretmanager.secretAccessor, not roles/secretmanager.viewer;

1. does it hold roles/cloudsql.client?
2. is the egress path to the database open?

See reference/compute/errors.md §4 and patterns/cloud-run-to-cloud-sql-with-iam.md.

5. Not an error: Bigtable's consistency changed under you

Adding a second cluster to a Bigtable instance changes it from strongly consistent to eventually consistent by default. Nothing fails; reads simply become stale sometimes.

Check	Fix
how many clusters does this instance have?	if more than one, configure read-your-writes or strong consistency explicitly — both are available and neither is the default

This belongs in an error catalogue precisely because it produces no error. It is the hardest class of failure to diagnose from a stack trace, and it is introduced by an availability change that looks unrelated.

Next: guides/databases/connect-to-cloud-sql-with-iam-auth.md, guides/parity/databases.md.