Connecting MySQL Client Using the Cloud SQL Proxy Docker Image

This page describes how to connect a mysql client to your Google Cloud SQL instance, from a client machine running Linux or Compute Engine Linux instance, using the Cloud SQL Proxy Docker image.

Before you begin

You must have:

  • Installed the gcloud command-line tool. Learn more.
  • Authorized the gcloud tool. Learn more.
  • Set the default project for the gcloud tool. Learn more.
  • Configured a database user on your Cloud SQL instance. Learn more.

Connecting a mysql client using the proxy Docker image

To connect using the proxy Docker image:

  1. Enable the Cloud SQL Administration API.

    Enable the API

  2. If you are using a Compute Engine instance, prepare the instance:
    1. Display the Compute Engine instance properties:
      gcloud compute instances describe [GCE_INSTANCE_NAME]
    2. Verify the scopes enabled on the instance.

      Authenticating using scopes requires both of the following scopes:

      • https://www.googleapis.com/auth/sqlservice.admin
      • https://www.googleapis.com/auth/devstorage.read_write

      Alternatively, the https://www.googleapis.com/auth/cloud-platform scope enables all Google Cloud Platform APIs.

      If your Compute Engine instance does not have the proper scopes, you can update the instance to include them. For more information, see the Compute Engine documentation.

    3. Open a terminal connection to the instance, using the instructions at Connecting to Linux Instances.
  3. Install the mysql client on the Compute Engine instance or client machine, if it is not already installed.

    Debian/Ubuntu

    Install the MySQL client from the package manager:

    sudo apt-get update
    sudo apt-get install mysql-client
    

    CentOS/RHEL

    Install the MySQL client from the package manager:

    sudo yum install mysql
    

    openSUSE

    Install the MySQL client from the package manager:

    sudo zypper install mysql-client
    

    Other platforms

    1. Download the MySQL Community Server for your platform from the MySQL Community Server download page.
      The Community Server includes the MySQL client.
    2. Install the Community Server, following the directions on the download page.

    For more information about installing MySQL, see the MySQL Reference Manual Installing and Upgrading MySQL.

  4. If needed, install the Docker client:
    curl https://get.docker.com | sh
    sudo usermod -aG docker $USER
    

    If you are using a container-optimized Compute Engine instance, it already has the Docker client installed.

  5. Install the Proxy Docker image from the Google Container Registry.
    docker pull gcr.io/cloudsql-docker/gce-proxy:1.11
  6. If you are running the Proxy Docker image on a local machine (not a Compute Engine instance), or your Compute Engine instance does not have the proper scopes, create a Google Cloud Platform service account.
    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 Project > Editor, but the Editor role includes permissions across Google Cloud Platform.

      If you do not see these roles, your Google Cloud Platform user might not have the resourcemanager.projects.setIamPolicy permission. You can check your permissions by going to the IAM page in the Google Cloud Platform Console and searching for your user id.

    6. Change the Service account ID to a unique value that you will recognize so you can easily find this service account later 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.

    You provide the path to the key file as "PATH_TO_KEY_FILE" when you start the proxy.

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

    Go to the Cloud SQL Instances page

  8. Select the instance to open its Instance details page and copy the Instance connection name.
  9. Start the proxy.

    Depending on your language and environment, you can start the proxy using either TCP sockets or Unix sockets. Unix sockets are not supported for applications written in the Java programming language or for the Windows environment.

    TCP sockets

    docker run -d -v /cloudsql:/cloudsql \
      -v [PATH_TO_KEY_FILE]:/config \
      -p 127.0.0.1:3306:3306 \
      gcr.io/cloudsql-docker/gce-proxy:1.11 /cloud_sql_proxy \
      -instances=[INSTANCE_CONNECTION_NAME]=tcp:0.0.0.0:3306 -credential_file=/config
    

    If you are using a Compute Engine instance, do not include the credential_file parameter and the -v [PATH_TO_KEY_FILE]:/config line.

    If you are using a container optimized image, use a writeable directory in place of /cloudsql, for example:

    -v /mnt/stateful_partition/cloudsql:/cloudsql

    Always specify 127.0.0.1 prefix in -p so that the proxy is not exposed outside the local host. The "0.0.0.0" in the instances parameter is required to make the port accessible from outside of the Docker container.

    Unix sockets

    docker run -d -v /cloudsql:/cloudsql \
      -v [PATH_TO_KEY_FILE]:/config \
      gcr.io/cloudsql-docker/gce-proxy /cloud_sql_proxy -dir=/cloudsql \
      -instances=[INSTANCE_CONNECTION_NAME] -credential_file=/config
    

    If you are using a Compute Engine instance, do not include the credential_file parameter.

    If you are using a container optimized image, use a writeable directory in place of /cloudsql, for example:

    -v /mnt/stateful_partition/cloudsql:/cloudsql

    You can specify more than one instance, separated by commas. You can also use Compute Engine metadata to dynamically determine the instances to connect to. Learn more about the proxy parameters.

  10. Start the 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? For help troubleshooting the proxy, see Troubleshooting Cloud SQL Proxy connections. Or, see our Cloud SQL Support page.

Keeping the Proxy Docker image up to date

The Proxy Docker image is based on a specific version of the Cloud SQL Proxy. When a new version of the Cloud SQL Proxy becomes available, you should pull the new version of the Proxy Docker image to keep your environment up to date. You can see the current version of the Cloud SQL Proxy by checking the Cloud SQL Proxy Github releases page. Future proxy releases will also be noted in the Google Groups Cloud SQL announce forum.

What's next

Send feedback about...

Cloud SQL for MySQL