cloud-sql-proxy.mdx

title	Cloud SQL Auth Proxy
description	Connect to Google Cloud SQL by letting TablePro manage the Cloud SQL Auth Proxy

import HelperPort from "/snippets/helper-port.mdx";

One field carries the whole setup: the instance connection name, project:region:instance, which is on the instance's overview page in the Google Cloud console. The proxy itself runs as a child process, started on connect and killed on disconnect.

Before you start

The transport appears for Cloud SQL instances running MySQL, PostgreSQL, or SQL Server. The account you connect with needs the Cloud SQL Client role (roles/cloudsql.client) on the project, and for Application Default Credentials, one run of:

gcloud auth application-default login

Install the binary, or click Download cloud-sql-proxy… on the Network tab, which fetches 2.23.0 and checks its SHA-256 against the value pinned for your CPU architecture.

brew install cloud-sql-proxy

Auto-detection covers your PATH, /opt/homebrew/bin, /usr/local/bin, and ~/google-cloud-sdk/bin. Anywhere else, use Choose….

Setting up

On the **Network** tab, set **Connect via** to **Cloud SQL Auth Proxy**. A connection uses one transport, so choosing this one switches off whichever was selected before. Enter the **Instance connection name**, then choose **Application Default Credentials** or **Service Account Key**. The proxy encrypts the leg to Cloud SQL and hands the driver plain loopback, so SSL/TLS stays off. On **General**, click **Test Connection**. **Host** and **Port** there are never dialed: the instance connection name decides where the proxy lands. **Username** and **Database** work as usual.

Options

Option	What it does	Default
Instance connection name	project:region:instance. Three colon-separated parts, none empty, or the connect is refused outright.	-
Credentials	Application Default Credentials, or a Service Account Key pasted as JSON.	Application Default Credentials
Use IAM database authentication	Signs in as an IAM principal instead. Set Username to that principal, a user email or name@project.iam for a service account; the password goes unused.	Off
Connect over private IP	Reaches the instance on its private address instead of its public one.	Off
Path	The cloud-sql-proxy binary. Blank auto-detects.	Blank

A pasted key is kept in the macOS Keychain and written to a temporary file readable only by you while the proxy runs, then deleted. It never reaches the command line.

`GOOGLE_APPLICATION_CREDENTIALS` works too, but the proxy inherits the app's environment, and a GUI app never sees variables exported by your shell profile.

IAM sign-in without the proxy

When the instance is already reachable, over its private IP or an authorized network, you can skip the proxy and sign in as an IAM principal directly. This works for MySQL and PostgreSQL.

On the General tab, set Authentication to one of:

• Google Cloud IAM (Application Default): the credentials from gcloud auth application-default login.
• Google Cloud IAM (Service Account): a Service Account Key, as a file path or pasted JSON.

Set Host to the instance IP and Username to the database user of the principal:

Engine	User account	Service account
PostgreSQL	name@example.com	name@project.iam
MySQL	name	name

The password field disappears. The token TablePro signs in with allows a Cloud SQL sign-in and nothing else, and lasts one hour. It is reused until five minutes before it expires, then replaced, including for a reconnect and for the extra connection MySQL opens to stop a query. SSL/TLS is raised to Required if it was lower.

The principal needs the Cloud SQL Instance User role (roles/cloudsql.instanceUser), and the instance needs IAM database authentication turned on and a database user for the principal:

gcloud sql users create name@example.com --instance=INSTANCE --type=cloud_iam_user

`GOOGLE_APPLICATION_CREDENTIALS` is read from the app's environment, which never has the variables your shell profile exports. To use a key file, choose **Service Account** and give its path.

These options also work with Connect via > Cloud SQL Auth Proxy. SSL then stays as set, because the proxy encrypts the connection to the instance.

A connection synced to an iPhone or iPad keeps its method, and Application Default there needs a service account key for that device: see IAM sign-in.

Troubleshooting

cloud-sql-proxy was not found

Install it with brew install cloud-sql-proxy, download it from the Network tab, or set Path.

The proxy did not become ready in time

Run it by hand to see what it says:

cloud-sql-proxy --port 5433 --address 127.0.0.1 project:region:instance

Permission or authentication errors

The proxy reports these on its own output, which the failed connect shows. Usually the account is missing the Cloud SQL Client role, Application Default Credentials were never set up, or IAM database authentication is on with no database user for the principal.

The gcloud login does not allow Cloud SQL sign-in

The login was made with --scopes that leave out Cloud SQL sign-in. Run gcloud auth application-default login again without --scopes.