Connecting mysql Client Using the Cloud SQL Proxy

This page describes how to connect a mysql client to your Google Cloud SQL instance using the Cloud SQL Proxy, rather than over IP.

For information about connecting a mysql client to a Cloud SQL instance using IP, see Connecting mysql Client Using IP Addresses.

For more information about how the proxy works, see About the Cloud SQL Proxy.

Note: The Cloud SQL Proxy is available only for Cloud SQL Second Generation instances.

Before you begin

Before you can connect a mysql to a Cloud SQL instance, you must have:

Connecting the mysql client

Connecting a mysql to your Cloud SQL instance with the proxy involves the following steps:

  1. Enable the Cloud SQL API
  2. Install the proxy
  3. Create a service account
  4. Start the proxy
  5. Start the mysql session

1. Enable the Cloud SQL API

  • Enable the Cloud SQL Administration API.

    Enable the API

  • 2. Install the proxy

    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
      

    OS X 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
      

    OS X 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.

    3. Create a service account

    When you connect using the proxy, the proxy needs to autheniticate with Google Cloud Platform. You can either use your Cloud SDK credentials, or you can provide the proxy with a path to a local key file from a service account you create (recommended for production instances). If you are using your Cloud SDK credentials, you can skip this step.

    For more information about service accounts, see the Google Cloud Platform Auth Guide.

    1. Go to the Cloud SQL Service accounts page of the Google Cloud Platform Console.

      Go to the Service accounts page

    2. If needed, select the project that contains your Cloud SQL instance.
    3. Click Create service account.
    4. In the Create service account dialog, provide a descriptive name for the service account.
    5. For Role, select Cloud SQL > Cloud SQL Client.

      Alternatively, you can use the primitive Editor role by selecting Roles > Editor, but the Editor role includes permissions across Google Cloud Platform.

    6. Change the Service account ID to a shorter value if needed.
    7. Click Furnish a new private key.
    8. The default key type is JSON, which is the correct value to use.
    9. Click Create.

      The private key file is downloaded to your machine. You can move it to another location. Keep the key file secure.

    4. Start the proxy

    Depending on your language and environment, you can start the proxy using either TCP sockets or Unix sockets.

    TCP sockets

    1. Copy your instance connection name from the Instance details page.
    2. If you are using a service account to authenticate the proxy, note the location on your client machine of the private key file that was created when you created the service account.
    3. Start the proxy.

      Some possible proxy invocation strings:

      • Using Cloud SDK authentication:
        ./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:3306
        
        The specified port must not already be in use, for example, by a local database server.
      • Using a service account and explicit instance specification (recommended for production environments):
        ./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:3306 \
                          -credential_file=<PATH_TO_KEY_FILE> &
        

      For more information about proxy options, see Options for authenticating the proxy and Options for specifying instances.

    Unix sockets

    1. If you are using explicit instance specification, copy your instance connection name from the Instance details page.
    2. Create the directory where the proxy sockets will live:
      sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
    3. If you are using a service account to authenticate the proxy, note the location on your client machine of the private key file that was created when you created the service account.
    4. Open a new terminal window and start the proxy.

      Some possible proxy invocation strings:

      • Using a service account and explicit instance specification (recommended for production environments):
        ./cloud_sql_proxy -dir=/cloudsql -instances=<INSTANCE_CONNECTION_NAME> \
                          -credential_file=<PATH_TO_KEY_FILE> &
      • Using Cloud SDK authentication and automatic instance discovery:
        ./cloud_sql_proxy -dir=/cloudsql &

      It is best to start the proxy in its own terminal so you can monitor its output without it mixing with the output from other programs.

      For more information about proxy options, see Options for authenticating the proxy and Options for specifying instances.

    5. Start the client session

    Now that you have installed and started the proxy, you can start a mysql session using the proxy. This command can be used whenever you want to connect to your Cloud SQL instance with a mysql client.

    The connection string you use depends on whether you started the proxy using a TCP socket or a UNIX socket.

    TCP sockets

    1. Start the mysql client:
      mysql -u <USERNAME> -p --host 127.0.0.1
      

      When you connect using TCP sockets, the proxy is accessed through 127.0.0.1.

    2. Enter the password.
    3. You should see the mysql prompt.

    Unix sockets

    1. Start the mysql client:
      mysql -u <USERNAME> -p -S /cloudsql/<INSTANCE_CONNECTION_NAME>
      
    2. Enter the password.
    3. You should see the mysql prompt.

    Need help? See our Cloud SQL Support page.

    What's next

    Send feedback about...

    Cloud SQL for MySQL