> ## Documentation Index
> Fetch the complete documentation index at: https://docs.isotopes.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Cloud SQL

If your PostgreSQL database runs on Google Cloud SQL, aidnn can reach it without allowlisting IP addresses, even when the database has only a private IP. You still add a regular **Postgres** connector; you only choose a different **Connection method**.

## Choose a connection method

| Your database | Connection method | What you set up in Google Cloud |
| - | - | - |
| Public IP, aidnn's IPs allowlisted | **Direct** | Nothing extra. Follow the [Postgres connector](https://docs.isotopes.ai/data-sources/postgres.md) guide. |
| Public IP, no IP allowlist | **Cloud SQL Auth Proxy** (recommended) | A service account for aidnn |
| Private IP only | **IAP tunnel** | A service account for aidnn and a small proxy VM |

With **Cloud SQL Auth Proxy** and **IAP tunnel**, aidnn signs in to Google with a service account key you provide. Google checks the account's roles before any traffic reaches your database.

## 1. Prerequisites - Google Cloud admin setup

These steps run in the Google Cloud project that holds the database. The examples use project *acme-analytics*, region *us-central1* and instance *acme-pg*; substitute your own names.

First, enable the APIs the connection uses (the IAP tunnel also needs the last two):

```bash theme={null}
gcloud services enable sqladmin.googleapis.com iap.googleapis.com compute.googleapis.com --project=acme-analytics
```

### Create a read-only database user

Connect as an admin user (for example in Cloud SQL Studio) and create a user that can only read:

```sql theme={null}
CREATE ROLE aidnn_reader LOGIN PASSWORD 'choose-a-strong-password';
GRANT CONNECT ON DATABASE acme_db TO aidnn_reader;
GRANT USAGE ON SCHEMA public TO aidnn_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO aidnn_reader;
-- Tables created later are readable too
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO aidnn_reader;
```

Repeat the last three statements for each schema aidnn should read.

### Create a service account for aidnn

Create a dedicated service account and a key for it. You paste the key into aidnn later. If your organization blocks service account keys (the `iam.disableServiceAccountKeyCreation` policy), ask your organization admin for an exception for this account.

```bash theme={null}
gcloud iam service-accounts create aidnn-connector --project=acme-analytics

gcloud iam service-accounts keys create aidnn-key.json \
  --iam-account=aidnn-connector@acme-analytics.iam.gserviceaccount.com
```

Give the account the roles for your connection method:

* **Cloud SQL Auth Proxy** - Cloud SQL Client (`roles/cloudsql.client`).
* **IAP tunnel** - IAP-secured Tunnel User (`roles/iap.tunnelResourceAccessor`) and Compute Viewer (`roles/compute.viewer`).

For example, for the Cloud SQL Auth Proxy (for the IAP tunnel, run it once for each of its two roles):

```bash theme={null}
gcloud projects add-iam-policy-binding acme-analytics \
  --member=serviceAccount:aidnn-connector@acme-analytics.iam.gserviceaccount.com \
  --role=roles/cloudsql.client
```

### IAP tunnel only - run a proxy VM

With the IAP tunnel, aidnn reaches a small VM in your network through Google IAP, and the VM forwards to the database's private IP. The VM has no public IP. The database needs a private IP on the same VPC network as the VM.

* Give the VM its **own** service account with the Cloud SQL Client role. This is not the aidnn service account, and its key is never shared.
* Turn on Private Google Access for the VM's subnet, so the VM can reach Google without a public IP.
* Allow Google IAP's address range, `35.235.240.0/20`, to reach the VM on port 5432.

The VM runs Google's Cloud SQL Auth Proxy from a startup script. Write the script to a file, then create the VM with it:

```bash theme={null}
cat > proxy-startup.sh <<'EOF'
iptables -w -A INPUT -p tcp --dport 5432 -j ACCEPT
docker rm -f csql-proxy 2>/dev/null
docker run -d --name csql-proxy --restart=always --net=host \
  gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.27.0 \
  --address 0.0.0.0 --port 5432 --private-ip acme-analytics:us-central1:acme-pg
EOF

gcloud compute instances create aidnn-sql-proxy \
  --project=acme-analytics --zone=us-central1-a \
  --machine-type=e2-micro --no-address \
  --image-family=cos-stable --image-project=cos-cloud \
  --service-account=aidnn-sql-proxy-vm@acme-analytics.iam.gserviceaccount.com \
  --scopes=cloud-platform \
  --metadata-from-file=startup-script=proxy-startup.sh

gcloud compute firewall-rules create allow-iap-to-aidnn-sql-proxy \
  --project=acme-analytics --network=default \
  --allow=tcp:5432 --source-ranges=35.235.240.0/20 \
  --target-service-accounts=aidnn-sql-proxy-vm@acme-analytics.iam.gserviceaccount.com
```

> [!WARNING]
>
> For the IAP tunnel, paste the key of the **aidnn** service account into aidnn, not the proxy VM's service account. The VM's account has no tunnel permission, and the test fails with `Required 'compute.instances.get' permission`.

## 2. Add the connector in aidnn

Open **Connectors**, click **Add New Connector** and select **Postgres**, as in the [Postgres connector](https://docs.isotopes.ai/data-sources/postgres.md) guide. Choose a **Connection method**, then fill in its fields. Both methods ask for:

* **Database**, **User**, **Password** - the database and the read-only user from step 1.
* **Service account key (JSON)** - the full contents of *aidnn-key.json*.

### Cloud SQL Auth Proxy

* **Instance connection name** - the **Connection name** on the instance's **Overview** page, for example *acme-analytics:us-central1:acme-pg*.

![Postgres connector form with the Cloud SQL Auth Proxy method](https://mintcdn.com/isotopesai-e9db0a5b/hSxbVmVfr_oOjuXd/images/postgres-cloud-sql-proxy.png?fit=max\&auto=format\&n=hSxbVmVfr_oOjuXd\&q=85\&s=ec1e3c073819b2a42193ad7be988d416)

### IAP tunnel

* **IAP project**, **IAP zone**, **Proxy VM name** - the proxy VM's project, zone and name, for example *acme-analytics*, *us-central1-a*, *aidnn-sql-proxy*.
* **Proxy VM port** - 5432, the port the proxy listens on.

![Postgres connector form with the IAP tunnel method](https://mintcdn.com/isotopesai-e9db0a5b/hSxbVmVfr_oOjuXd/images/postgres-cloud-sql-iap.png?fit=max\&auto=format\&n=hSxbVmVfr_oOjuXd\&q=85\&s=5d041792b719fcb18bbcb5470d2d14af)

You don't need to allowlist aidnn's IPs for these methods. The connection method can't be changed after the connector is created.

## 3. Test, create and sync

Click **Test Connection**. It takes about 20 seconds, and up to a minute the first time, while aidnn opens the connection to Google. Then click **Create** and sync the schemas you want, as in the [Postgres connector](https://docs.isotopes.ai/data-sources/postgres.md) guide.

### If the test fails

The test shows Google's own message. The most common ones:

| Message contains | Fix |
| - | - |
| `Required 'compute.instances.get' permission` | Use the aidnn service account's key and give it the IAP tunnel roles. |
| `The resource '.../instances/...' was not found` | Check the IAP zone and proxy VM name. |
| `4003: 'failed to connect to backend'` | The proxy VM isn't listening: check its startup script and the firewall rule. |
| `The Cloud SQL instance does not exist` | Check the instance connection name. |
| `password authentication failed` | Check the database user and password. |
| `has not been used in project` ... `or it is disabled` | Enable the API named in the message. |

> [!TIP]
>
> **To rotate the key**, paste a new key on the connector's edit page, then delete the old one in Google Cloud.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.