Connecting to Cloud SQL from External Applications

This page describes how to connect to Google Cloud SQL from an application running outside of the Google Cloud Platform, and manage IP access to your instance.

For information about the various options for connecting to Cloud SQL, see Connection Options for External Applications.

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.

You can connect to a Cloud SQL instance using the following methods:

Connecting from an external application using the proxy

1. Enable the API

  • Enable the Cloud SQL Administration 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
      

    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. Determine how you will authenticate the proxy

    Learn more about proxy authentication options.

    4. If required by your authentication method, create a 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 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.

    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.

    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:5432
        
        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:5432 \
                          -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.

    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 or Unix socket (depending on how you invoked the proxy):

    TCP sockets

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

    127.0.0.1:5432
    

    Unix sockets

    With Unix sockets, the proxy is available using the following path:

    <PROXY_PATH>/<INSTANCE_CONNECTION_NAME>
    
    Where PROXY_PATH is the path to the directory you set with the -dir option when you started the proxy. The examples in this documentation use /cloudsql. You can find the connection name of your instance on its Instance details page in the Google Cloud Platform Console, or use <PROJECT-ID>:<REGION>:<INSTANCE_NAME>.

    Need help? See our Cloud SQL Support page.

    Language-specific information and examples

    You can connect to the proxy from any language that enables you to connect to a Unix or TCP socket. Below are a few sample proxy invocation and connection statements to help you understand how they work together in your application.

    Python

    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. Learn more.

    Psycopg2 & TCP

    Invoke the proxy:

    ./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:5432 &
    

    Connection statement:

    import psycopg2
    conn = psycopg2.connect(user=<USER>, password=<PASSWORD>,
                            host='localhost', port='5432')
    

    Psycopg2 & Unix

    Invoke the proxy:

    ./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME> -dir=/cloudsql &
    

    Connection statement:

    import psycopg2
    conn = psycopg2.connect(user=<USER>, password=<PASSWORD>,
                            host='/cloudsql/<INSTANCE_CONNECTION_NAME>')
    

    SQLAlchemy & TCP

    Invoke the proxy:

    ./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:5432 &
    

    Connection statement:

    from sqlalchemy import create_engine
    engine = create_engine('postgresql+psycopg2://<USER>:<PASSWORD>@localhost:5432/')
    

    SQLAlchemy & Unix

    Invoke the proxy:

    ./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME> -dir=/cloudsql &
    

    Connection statement:

    from sqlalchemy import create_engine
    engine = create_engine('postgresql+psycopg2://<USER>:<PASSWORD>@/?host=/cloudsql/<INSTANCE_CONNECTION_NAME>')
    

    Java

    The Java programming language does not provide native support for Unix sockets. You can use TCP sockets or a library that provides Unix socket support with the proxy, but the easiest way to connect to a Cloud SQL instance without whitelisting IP addresses is to use the JDBC socket factory.

    The JDBC socket factory provides an alternative to the client-side proxy software, and requires the Cloud SQL API to be enabled, just as the proxy does. It authenticates with Cloud SDK credentials, so the Cloud SDK must be installed and authenticated.

    String jdbcUrl = String.format(
        "jdbc:postgresql://google/%s?socketFactory=com.google.cloud.sql.postgres.SocketFactory"
            + "&socketFactoryArg=%s",
        databaseName,
        instanceConnectionName);
    
    Connection connection = DriverManager.getConnection(jdbcUrl, username, password);

    For more information, see the JDBC socket factory GitHub page.

    Go

    You can use the Cloud SQL Proxy with the Go programming language two ways:

    • Go Proxy library
    • Companion Process
    Go Proxy library

    The library provides the easiest way to use the Proxy from a Go program, because you do not need to explicitly start the proxy as its own process.

    import (
    	"github.com/GoogleCloudPlatform/cloudsql-proxy/proxy/dialers/postgres"
    )
    ...
    dsn := fmt.Sprintf("host=%s dbname=%s user=%s password=%s sslmode=disable",
                       <INSTANCE_CONNECTION_NAME>,
                       <DATABASE_NAME>,
                       <DATABASE_USER>,
                       <PASSWORD>)
    db, err := sql.Open("cloudsqlpostgres", dsn)
    

    For more information, see the Cloud SQL Proxy Github 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. Learn more.

    TCP

    Proxy invocation statement:

    ./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:5432 &
    

    Connection statement:

    import (
    	"github.com/lib/pq"
    )
    
    dsn := fmt.Sprintf("host=localhost port=5432 user=%s password=%s dbname=%s sslmode=disable",
           dbUser,
           dbPassword,
           dbName)
    db, err := sql.Open("postgres", dsn)
    

    Unix sockets

    Proxy invocation statement:

    ./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME> -dir=/cloudsql &
    

    Connection statement:

    import (
    	"github.com/lib/pq"
    )
    
    dsn := fmt.Sprintf("host=/cloudsql/%s user=%s password=%s dbname=%s sslmode=disable",
           INSTANCE_CONNECTION_NAME,
           dbUser,
           dbPassword,
           dbName)
    db, err := sql.Open("postgres", dsn)
    

    Configuring access for IP connections

    You can grant any application access to a Google Cloud SQL instance by authorizing the IP addresses that the application uses to connect.

    You can not specify a private network (for example, 10.x.x.x) as an authorized network.

    PostgreSQL instances support only IPv4 addresses. They are automatically configured with a static IP address.

    To configure access over IP connections:

    Console

    1. Determine the IP address of your application. Learn more.
    2. Authorize your application's IP address to connect to your instance.

      For more information, see Adding an authorized address.

    3. You can find the IP address assigned to your instance in its Instance details page. This is the value you need for your application's connection string.

    gcloud

    1. Determine the IP address of your client machine. Learn more.
    2. Authorize your application's IP address to connect to your instance.

      For more information, see Adding an authorized address.

    3. Retrieve the IP address for the instance:
      gcloud sql instances describe [INSTANCE_NAME]
      

      In the output, find the ipAddress field. This is the value you need for your application's connection string.

    cURL

    1. Determine the IP address of your application. Learn more.
    2. Authorize your application's IP address to connect to your instance.

      For more information, see Adding an authorized address.

    3. Retrieve the IP address for the instance:
      ACCESS_TOKEN="$(gcloud auth application-default print-access-token)"
      curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
             -X GET \
             https://www.googleapis.com/sql/v1beta4/projects/[PROJECT-ID]/instances/[INSTANCE_NAME]
      

      Note the value for ipAddresses.ipAddress. This is the value you need for your application's connection string.

    Need help? See our Cloud SQL Support page.

    Configuring access for applications with dynamically assigned IP addresses

    Some applications need to connect to your Cloud SQL instance using a dynamically assigned, or ephemeral, IP address. This is the case for Platform as a Service (Paas) applications, among others.

    In these cases, you must use the Cloud SQL Proxy.

    Testing your connection

    You can use the psql client to test your ability to connect from your local environment. For more information, see Connecting the psql Client using IP Addresses and Connecting the psql Client using the Cloud SQL Proxy.

    Need help? See our Cloud SQL Support page.

    Determining the IP address for your application

    To determine the IP address of a computer running your application so you can authorize access to your Cloud SQL instance from that address, use one of the following options:

    • If the computer is not behind a proxy, log in to the computer and use this link to determine its IP address.
    • If the computer is behind a proxy, log in to the computer and use a tool or service like Proxy Test to determine its true IP address.

    What's next

    Monitor your resources on the go

    Get the Google Cloud Console app to help you manage your projects.

    Send feedback about...

    Cloud SQL for PostgreSQL