Quickstart for Using the Proxy for Local Testing

This page shows you how to connect to Cloud SQL from a local test environment using the Cloud SQL Proxy. Connecting through the 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 proxy for a production environment. For more connection options, see Connection Options for External Applications.

Before you begin

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

  • Create a GCP project and a Second Generation instance.
  • If you are using a pre-existing project, make sure your GCP user is an owner of your project, or has a Cloud SQL role other than Cloud SQL Viewer. Otherwise, you should set up the proxy using the instructions outlined in Connecting using the Cloud SQL Proxy.
  • Optionally, install the mysql client.

    The client enables you to test your connection to your instance. The mysql client is installed with the server package. Some operating systems support a client-only package. See the MySQL installation instructions.

Enable the Cloud SQL API

Enable the Cloud SQL Admin API.

Enable the 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 application-default login
    

Install the Cloud SQL Proxy client on your local machine

The 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 proxy:
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
    
  2. Make the proxy executable:
    chmod +x cloud_sql_proxy
    

Linux 32-bit

  1. Download the proxy:
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
    
  2. Make the proxy executable:
    chmod +x cloud_sql_proxy
    

macOS 64-bit

  1. Download the proxy:
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64
    
  2. Make the proxy executable:
    chmod +x cloud_sql_proxy
    

macOS 32-bit

  1. Download the proxy:
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
    
  2. Make the 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 proxy, renaming it 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 proxy, renaming it to cloud_sql_proxy.exe.
If your operating system is not included here, you can also compile the proxy from source.

Get the instance connection name

  1. Go to the Cloud SQL Instances page in the Google Cloud Platform Console.

    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.

    You will use this value in the next step.

Start the proxy

Start the 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.

./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:3306

You should see a message similar to:

Listening on 127.0.0.1:3306 for myproject:us-central1:myinstance".
Ready for new connections

Connect to your database using the mysql client

This step is optional, but recommended so you can test your connection. See the MySQL installation instructions.

In a different terminal window than where you started the proxy, run the following command, replacing <USERNAME> with your MySQL username.

mysql -u <USERNAME> -p --host 127.0.0.1 --port 3306

You should see the mysql prompt, and a message similar to the following example should appear in the proxy terminal:

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

What's next

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud SQL for MySQL