> ## Documentation Index
> Fetch the complete documentation index at: https://ngquct-docs-partner-confirmed.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Cloud SQL Auth Proxy
> Connect to Google Cloud SQL by letting TablePro manage the Cloud SQL Auth Proxy
export const binary_0 = undefined
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:
```bash theme={null}
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.
```bash theme={null}
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.
| Option | What it does | Default |
| - | - | - |
| **Choose port automatically** | Takes a free loopback port, and tries up to five times if one is claimed first | On |
| **Local port** | Pins a fixed port instead. There is no retry, so a port already in use fails the connect | - |
TablePro polls that port and gives {binary_0} 30 seconds to answer on it. Past that the connect fails
and the error carries the last lines {binary_0} printed, which is where the real reason usually is.
## 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:
```bash theme={null}
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.
## 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:
```bash theme={null}
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`.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.