Choose how to connect to Cloud SQL

This page provides an overview of the ways in which you can connect to your Cloud SQL instance.

Before you can connect to a Cloud SQL instance, you need to decide how to deploy and configure your Cloud SQL instance and supporting networking resources. If your Cloud SQL instance is already configured and deployed, then this page can help you understand the different ways that you can connect your clients to the existing instance.

IP address type: private or public

When you first create your Cloud SQL instance, you can choose whether to configure the instance with a public IP address, a private IP address, or a combination of both.

You choose the IP address configuration of your instance based on your application requirements. Then after you configure your instance, you specify either a public IP address, a private IP address, or in some cases a DNS name in your client connection string.

Private IP address Public IP address
Description Internal, Virtual Private Cloud (VPC) network-only (private) IP address An external, internet-accessible (public) IP address
Decision points

Do you need to connect from clients hosted on VPC networks inside Google Cloud or from clients that have access to those VPC networks?

If yes, then choose a private IP address for the instance.

Do you need to connect from clients outside the Google Cloud VPC network over the public internet?

If yes, then choose a public IP address for the instance.
Configuration options

The following types of private networking configurations are supported:

When you connect directly to an instance using a public IP address, you must configure authorized networks.

Another more secure alternative for connecting to a Cloud SQL instance that uses public IP is to use a Cloud SQL connector (such as the Cloud SQL Auth Proxy or one of the Cloud SQL Language Connectors).

For instructions about adding a public IP to your instance, see Configure public IP.

To connect to a Cloud SQL instance using a public IP address, you can use the psql client or another available client.
Summary

Recommendation: For improved security, we recommend that you configure your instance with a private IP address type unless you have specific requirements for an internet-accessible Cloud SQL instance, or if you're connecting from a client that doesn't meet the requirements for a VPC.

Connection type: Cloud SQL connector or direct

When you make the connection to a Cloud SQL instance, you can use a Cloud SQL connector, or you can make a direct connection.

A Cloud SQL connector is either the Cloud SQL Auth Proxy or one of the Cloud SQL Language Connectors.

Cloud SQL connector Direct connection
Description Cloud SQL Auth Proxy, a client-side proxy, and Cloud SQL Language Connectors, client-side libraries, provide simplified and secure access to your Cloud SQL instances, especially when you connect to an instance using a public IP address. A direct connection from a client to a Cloud SQL instance provides a lower latency connection. A direct connection can be made from either a public or a private IP address.
Decision points

Cloud SQL connectors are beneficial in the following scenarios:

  • When you want to connect to a Cloud SQL instance using a public IP address without having to configure authorized networks.
  • When you want to encrypt traffic to and from the database automatically with server and client identity verification without having to manage SSL certificates.
  • When you're using IAM database authentication and want to refresh your OAuth 2.0 access tokens automatically.
  • When you're connecting from a client or application that uses a dynamically assigned or ephemeral IP address. Dynamic IP configuration can be common for Platform as a Service (PaaS) applications.

Using a direct connection provides the following benefits:

  • Lower latency compared to connections using Cloud SQL connectors.
  • No additional package or library dependency unlike Cloud SQL connectors.
  • When you use a direct connection, you're responsible for configuring the SSL/TLS settings.
Configuration options

To configure SSL/TLS certificates on the Cloud SQL instance and for your client, do the following:

  1. Choose a server CA mode for your instance.
  2. Configure your instance to enforce SSL/TLS encryption for connections on the instance.
  3. Create client certificates.
  4. Download your server and client certificates.
Summary

When you connect to a Cloud SQL instance, you can use either a Cloud SQL connector, or connect directly from clients.

General recommendation: If you're connecting to an instance by a private IP address, use a direct connection. We also recommend that you enforce SSL and configure SSL/TLS certificates for your connection.

If you're connecting to an instance by a public IP address, use a Cloud SQL connector (either the Cloud SQL Auth Proxy or one of the Cloud SQL Language Connectors).

Database authentication type: IAM or built-in

When you connect to an instance, you must authenticate as a database user. You can choose between built-in authentication or IAM database authentication.

IAM database authentication Built-in authentication
Description IAM database authentication lets you authenticate to databases with Google Cloud IAM user and service accounts by using short-lived access tokens instead of passwords. You can manage database privileges by using IAM principals such as users, service accounts, and groups. Built-in authentication uses database local usernames and passwords to authenticate database users.
Decision points Do you prefer to centralize user management across Google Cloud services using IAM in Google Cloud? If yes, then use IAM database authentication. Do you have applications or workflows that depend on built-in database authentication? If yes, then use built-in authentication.
Configuration options

You can use IAM database authentication for individual IAM users, individual service accounts, and groups. For more information, see use Manage users with IAM database authentication .

If you use a Cloud SQL connector, then the connector handles the automatic refresh of the IAM access tokens. For more information, see automatic IAM database authentication.

 You can use built-in database authentication and configure password policies at the instance and user levels. For more information, see Built-in authentication.
Summary Recommendation: Unless you have applications or workflows that depend on built-in database authentication, use IAM database authentication whenever possible.

Private networking options when using a private IP address

When you configure your instance to use a private IP address, you can choose the following private networking options: private services access, Private Service Connect, or both.

Supported features

The following table lists the features that Cloud SQL supports when you connect to an instance that's configured with one or both of the private networking options.

Feature Instance with private services access only Instance with Private Service Connect only Instance with both private services access and Private Service Connect
Connect from multiple VPCs Not supported. Supported. Supported by using the Private Service Connect endpoint.
pglogical, PL/Proxy, dblink, and postgres_fdw extensions Supported. Not supported. Supported by using outbound connectivity for private services access.
External replicas Supported. Not supported. Supported by using outbound connectivity for private services access.
Write endpoint Supported. Not supported. Supported for private services access.
Change the associated VPC network for private services access Supported. Not applicable. Not supported for private services access because the instance has Private Service Connect enabled for it. Not applicable for Private Service Connect.
Visibility of the client IP address to Cloud SQL Supported. Not supported. Supported by using the private services access IP address. Not supported by using the Private Service Connect endpoint.

Remove networking options from an instance

Cloud SQL supports the removal of the following networking options from an instance:

  • Public IP from an instance with both private services access and public IP
  • Public IP from an instance with public IP, private services access, and Private Service Connect
  • Private Service Connect from an instance with both Private Service Connect and private services access
  • Private Service Connect from an instance with Private Service Connect, private services access, and public IP

Enable networking options for an instance

You can enable Cloud SQL supports enabling the following connection options for instances:

  • Private services access on an instance with public IP only
  • Private Service Connect on an instance with private services access only
  • Private Service Connect on an instance with both private services access and public IP
  • Public IP on an instance with private services access only

Limitations

  • You can't create an instance with both a public IP address and Private Service Connect.
  • You can't remove private services access from an instance with private services access and Private Service Connect.
  • You can't remove private services access from an instance with private services access and public IP.
  • If you have an instance that uses only public IP, then you can't enable both private services access and Private Service Connect at the same time. First, enable private services access, and then enable Private Service Connect.
  • You can't use authorized networks to do IP address-based allowlisting for Private Service Connect instances.

Tools for connecting to Cloud SQL

The following table contains some options for connecting to Cloud SQL:

Connection option More information
Cloud SQL Auth Proxy
gcloud CLI
Cloud SQL language connectors
Cloud Shell
Cloud Code
Connect using third-party database administration tools
pgAdmin
Toad Edge
Blendo

Troubleshoot

If you're having problems connecting, then check the following pages for help debugging or finding solutions to known issues:

What's next