Quickstart for using the Cloud SQL Auth proxy

MySQL   |  PostgreSQL   |  SQL Server

This page shows you how to connect to Cloud SQL from a local test environment using the Cloud SQL Auth proxy. The Cloud SQL Auth proxy provides secure access to your Cloud SQL instance without the need for authorized networks or for configuring SSL. By using the Cloud SQL Auth proxy, you can connect to your Cloud SQL instance securely.

Don't use these instructions to set up the Cloud SQL Auth proxy for a production environment. Also, for more connection options for authenticating and using the proxy, see Connecting using the Cloud SQL Auth proxy.

Set up your project

Before performing the steps in this quickstart, complete the following tasks:

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

4. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

5. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

6. Make sure you have the Cloud SQL Admin role on your user account.
   • Go to the IAM page. Go to the IAM page
   • Click Add.
   • In New Principles, add your user account name.
   • In Select a role, filter for Cloud SQL Admin and select it from the list.
   • Click Save.
7. Enable the Cloud SQL Admin API.

   Enable the API

Create a Cloud SQL instance

In this procedure, you use the Google Cloud Console. To use the gcloud command-line tool, cURL, or PowerShell, see Creating instances.

1. In the Google Cloud Console, go to the Cloud SQL Instances page.

   Go to Cloud SQL Instances

2. Click Create Instance.
3. Click PostgreSQL.
4. If you're prompted to enable the Compute API, click the Enable API button.
5. Enter myinstance for Instance ID.
6. Enter a password for the postgres user.
7. Use the default values for the other fields.

8. Click Create.

   You are returned to the instances list; you can click into the new instance right away to see the details, but it won't be available until it initializes and starts.

   Note: In this example, the instance is created using default settings, including a public IP address.

Install a psql client.

Debian/Ubuntu

Install the psql client from the package manager:

sudo apt-get update
sudo apt-get install postgresql-client

CentOS/RHEL

Install the psql client from the package manager:

sudo yum install postgresql

openSUSE

Install the psql client from the package manager:

sudo zypper install postgresql

Other platforms

1. Download the PostgreSQL Core Distribution for your platform from the PostgreSQL Downloads page.
   The Core Distribution includes the psql client.
2. Install the PostgreSQL database, following the directions on the download page.

Install the Cloud SQL Auth proxy client

The Cloud SQL Auth proxy binary you download depends on your operating system, and whether it uses a 32-bit or 64-bit kernel. Most newer hardware uses a 64-bit kernel. If you're unsure whether your machine is running a 32-bit or 64-bit kernel, then use the name -a command for Linux or macOS. For Windows, see the Windows documentation.

Linux 64-bit

1. Download the Cloud SQL Auth proxy:

   wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
   

2. Make the Cloud SQL Auth proxy executable:

   chmod +x cloud_sql_proxy
   

Linux 32-bit

1. Download the Cloud SQL Auth proxy:

   wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
   

2. If the wget command is not found, run sudo apt-get install wget and repeat the download command.
3. Make the Cloud SQL Auth proxy executable:

   chmod +x cloud_sql_proxy
   

macOS 64-bit

1. Download the Cloud SQL Auth proxy:

   curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64
   

2. Make the Cloud SQL Auth proxy executable:

   chmod +x cloud_sql_proxy
   

macOS 32-bit

1. Download the Cloud SQL Auth proxy:

   curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
   

2. Make the Cloud SQL Auth proxy executable:

   chmod +x cloud_sql_proxy
   

Windows 64-bit

Right-click https://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe and select Save Link As to download the Cloud SQL Auth proxy. Rename the file to cloud_sql_proxy.exe.

Windows 32-bit

Right-click https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe and select Save Link As to download the Cloud SQL Auth proxy. Rename the file to cloud_sql_proxy.exe.

Cloud SQL Auth proxy Docker image

For convenience, several container images that contain the Cloud SQL Auth proxy are available on GitHub in the Cloud SQL Auth proxy repo. You can pull the latest image to your local machine using Docker with the following command:

docker pull gcr.io/cloudsql-docker/gce-proxy:1.19.1

Other OS

For other operating systems not included here, you can compile the Cloud SQL Auth proxy from source.

Get the instance connection name

1. In the Google Cloud Console, go to the Cloud SQL Instances page.

   Go to Cloud SQL Instances

2. Click the instance name to open its Overview page.
3. In the Connect to this instance section, copy the Connection name. The connection name is in the format projectID:region:instanceID.

Start the Cloud SQL Auth proxy

Start the Cloud SQL Auth proxy in its own terminal so you can monitor its output. Replace INSTANCE_CONNECTION_NAME with the instance connection name you copied in the previous step.

For Linux environments, use this command to launch the Cloud SQL Auth proxy:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:5432

In PowerShell on Windows, use this command to launch the Cloud SQL Auth proxy:

.\cloud_sql_proxy.exe -instances=INSTANCE_CONNECTION_NAME=tcp:5432

A message similar to the following appears:

Listening on 127.0.0.1:5432 for INSTANCE_CONNECTION_NAME
Ready for new connections

Run the following command:

psql "host=127.0.0.1 port=5432 sslmode=disable dbname=DB_NAME user=USERNAME"

At the Enter password: prompt, enter the password of your PostgreSQL account.

Verify that the PostgreSQL prompt appears. You have connected to your database using the psql client.

Return to the terminal window where you started the Cloud SQL Auth proxy. You should see a message similar to the following:

New connection for myInstance

Cleanup

1. In the Google Cloud Console, go to the Cloud SQL Instances page.

   Go to Cloud SQL Instances

2. Select the your instance's name to open the Overview page.
3. In the icon bar at the top of the page, click Delete.

4. In the Delete instance window, type your instance's name, then click Delete to delete the instance.

   You cannot reuse an instance name for about 7 days after the instance is deleted.

What's next

• See troubleshooting information for the Cloud SQL Auth proxy.
• Learn more about the Cloud SQL Auth proxy.
• Learn more about other connection options.