Quickstart for using the Cloud SQL Auth proxy

This page shows you how to connect to Cloud SQL from a local test environment using the Cloud SQL Auth proxy. Connecting through the Cloud SQL Auth proxy enables you to test an App Engine application in your local environment, or establish a secure connection for database administration.

Do not use these instructions to set up the Cloud SQL Auth proxy for a production environment. For more connection options, see Connecting using the Cloud SQL Auth proxy.

Before you begin

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

  • Create a Google Cloud project and a Cloud SQL instance.
  • If you are using a pre-existing project, ensure that your Google Cloud user is an owner of your project, or has the IAM Cloud SQL Client role.

  • Install a psql client.

    The client enables you to test your connection to your instance. The psql client can be installed with the server package or alone. See the PostgreSQL installation instructions.

  • Enable the Admin API.

  • Install and authenticate the gcloud command-line tool.

    1. If you haven't already, install the gcloud command-line tool. See the gcloud installation instructions.
    2. Initialize the gcloud tool: 
      gcloud init
    3. Authenticate the gcloud tool: 
      gcloud auth login

Install the Cloud SQL Auth proxy client on your local machine

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 are unsure whether your machine is running a 64-bit kernel, use the uname -a command for Linux or macOS, or click Computer > Properties in the Start Menu for Windows.

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. 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, the Cloud SQL team maintains several container images that contain the Cloud SQL Auth proxy for use by our customers. For more information about these images, see the Cloud SQL Auth proxy repo on GitHub. 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. Go to the Cloud SQL Instances page
  2. Click the instance name to open its Instance details page.
  3. Under Connect to this instance, note the Instance connection name.

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 myproject:myregion:myinstance.
Ready for new connections

Connect to your database using the psql client

This section is optional, but is recommended for testing your connection. See the PostgreSQL installation instructions.

In a different terminal window from where you started the Cloud SQL Auth proxy, run the following command, replacing <USERNAME> with your PostgreSQL username, and <DB_NAME> with the name of the database to connect to.

psql "host=127.0.0.1 port=5432 sslmode=disable dbname=<DB_NAME> user=<USER_NAME>"

The psql prompt appears, and a message similar to the following is in the Cloud SQL Auth proxy terminal:

New connection for "myproject:us-central1:myinstance"

Clean up

To avoid incurring charges to your Google Cloud account for the resources used in this quickstart, follow these steps.

  1. Go to the Cloud SQL Instances page in the Google Cloud Console.
    Go to the Cloud SQL Instances page
  2. Select the myinstance instance to open the Instance details page.
  3. In the icon bar at the top of the page, click Delete.

  4. In the Delete instance window, type myinstance, then click Delete to delete the instance.

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

What's next