Three layers that must all be true

"I can't connect to the database" is three completely different problems wearing the same sentence. They live in different systems, are fixed by different people, and fail at different moments.

Once you can name which layer an error belongs to, this stops being mysterious and becomes a lookup.

Reading the failure

The gift of this design is that each layer fails at a different moment as well as with a different message. The moment alone narrows it to one:

Layer 1 — the two roles, and why both

Google's documentation describes the second as a predefined role that contains the necessary Cloud SQL IAM cloudsql.instances.login permission. You need this permission to login to a database instance with IAM database authentication (Cloud SQL docs). Grant both, together, to a group:

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="group:db-users@example.com" \
  --role="roles/cloudsql.client"

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="group:db-users@example.com" \
  --role="roles/cloudsql.instanceUser"

Layer 2 — becoming a database user

Holding the roles does not make you a database user. That is a separate record on the instance, and there are three kinds:

# a person
gcloud sql users create you@example.com \
  --instance=INSTANCE_NAME --type=cloud_iam_user

# a service account — full email here, suffix and all
gcloud sql users create app@PROJECT_ID.iam.gserviceaccount.com \
  --instance=INSTANCE_NAME --type=cloud_iam_service_account

# a group — the one to reach for
gcloud sql users create db-users@example.com \
  --instance=INSTANCE_NAME --type=cloud_iam_group

Groups are the answer to offboarding

With group authentication, Google's documentation notes that a member gains the ability to log in to the Cloud SQL instance because the user or service account belongs to the group and automatically inherits any database privileges that have been granted to the group (IAM authentication). Removing them from the group removes both. No Terraform run, no SQL, no instance change.

One constraint worth knowing before you design around it: you cannot add an individual user to an instance and add a group they belong to. Pick one model per instance.

Layer 3 — grants, which are not Google's problem

A fresh IAM database user has nothing. From the docs: when an IAM user is added to a database, by default the new database user has no privileges to any database. So the third layer is plain SQL, run by someone who already has it:

-- as a role that can grant
GRANT app_rw TO "you@example.com";

That grants membership of a group role which carries the actual privileges, rather than granting tables directly. Why that is the right shape — and how it goes wrong on an instance holding more than one database — is lesson 7.

The diagnosis, as a routine

• Did the proxy start? No → layer 1. Check the roles, and check you are pointed at the right project.
• Did it start and then hang? → not a layer. Egress to port 3307 is blocked.
• Did login fail? → layer 2. Check the user exists and that a service-account username has its suffix dropped.
• Did it work yesterday and fail today with nothing changed? → not a layer. Credentials expired; restart the proxy.
• Are you in, but denied on a table? → layer 3. Someone re-runs the grants.
• Does SELECT current_user return what you expect? No → you are on a different connection than you think.

Check yourself