Connecting to Cloud SQL from external applications

This page describes how to establish a connection to Cloud SQL from an application running outside of Google Cloud.

Database connections consume resources on the server and the connecting application. Always use good connection management practices to minimize your application's footprint and reduce the likelihood of exceeding Cloud SQL connection limits. For more information, see Managing database connections.

Before you start

Granting access to an application does not automatically enable a database user account to connect to the instance. Before you can connect to an instance, you must have a database user account you can connect with. For new instances, this means you must have configured the default user account. Learn more.

Connection options

The following table compares the options for connecting to a Cloud SQL instance from an external application:

Connection option Secure, encrypted? More information Notes
Public IP address with SSL Yes SSL certificate management required.
Public IP address without SSL No Not recommended for production instances.
Cloud SQL Proxy Yes
Cloud SQL Proxy Docker image Yes
JDBC Socket Library Yes Java programming language only.
Go Proxy Library Yes Go programming language only.
Cloud Shell No Uses the Cloud SQL Proxy to connect from the Google Cloud Console. Best for administration tasks requiring the sqlcmd command-line tool.
Apps Script Yes Apps Script can connect to external databases through the JDBC service, a wrapper around the standard Java Database Connectivity technology.

Connecting from an external application using the proxy

If you are setting up the Cloud SQL Proxy for a local test environment (not for production), you can use the Proxy Quickstart instead of these instructions.

If you are using the Java or Go programming languages, you have some alternatives to using the Cloud SQL Proxy. Learn more.

1. Enable the API

Enable the Cloud SQL Admin API.

Enable the API

2. Install the proxy client on your local machine

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. 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 proxy. Rename the file to cloud_sql_proxy.exe.
If your operating system isn't included here, you can also compile the proxy from source.

3. Determine how you will authenticate the proxy

Learn more about proxy authentication options.

4. If required by your authentication method, create a service account

When you use a service account to provide the credentials for the proxy, you must create it with sufficient permissions. If you are using the finer-grained Identity Access and Management (IAM) roles to manage your Cloud SQL permissions, you must give the service account a role that includes the cloudsql.instances.connect permission. The predefined Cloud SQL roles that include this permission are:

  • Cloud SQL Client
  • Cloud SQL Editor
  • Cloud SQL Admin

If you are using the legacy project roles (Viewer, Editor, Owner), the service account must have at least the Editor role.

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

    Go to the Service accounts page

  2. 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 one of the following roles:
    • Cloud SQL > Cloud SQL Client
    • Cloud SQL > Cloud SQL Editor
    • Cloud SQL > Cloud SQL Admin

    Alternatively, you can use the basic Editor role by selecting Project > Editor, but the Editor role includes permissions across Google Cloud.

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

  6. Change the Service account ID to a unique, recognizable value.
  7. Click Furnish a new private key and confirm that the key type is JSON.
  8. Click Create.

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

5. Determine how you will specify your instances for the proxy

Learn more about proxy instance specification options.

6. Start the proxy

The options you pass to the proxy depend on the authentication and instance specification options you chose previously.

You can start the proxy using TCP sockets.

TCP sockets

  1. Copy your instance connection name from the Instance details page.

    For example: myproject:myregion:myinstance.

  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:1433
      
      The specified port must not already be in use, for example, by a local database server.
    • Using a service account and explicitly including the name of the instance connection (recommended for production environments):
      ./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:1433 \
                        -credential_file=<PATH_TO_KEY_FILE> &
      

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

7. Update your application to connect to Cloud SQL using the proxy

The exact code statement required to use the proxy to connect to your Cloud SQL instance depends on the language and framework you are using.

You connect to the proxy the same way you would to a TCP socket.

TCP sockets

With TCP sockets, the proxy is available as local host:

127.0.0.1:1433

Need help? For help troubleshooting the proxy, see Troubleshooting Cloud SQL Proxy connections. Or, see our Cloud SQL Support page.

Companion process

You can also run the proxy as a companion process, and connect to it from your application.

The proxy invocation statements below use local Cloud SDK authentication for brevity; your invocation statement might vary, depending on how you are authenticating and how you are specifying your instances. See Options for authenticating the Cloud SQL Proxy.

What's next