Overview to connecting

This page provides an overview of the ways in which you can connect to your Cloud SQL instance and describes the available authentication and authorization options.

Overview

When considering how to connect to your Cloud SQL instance, there are many choices to keep in mind, including:

  • Do you want your Cloud SQL instance to be accessible from the internet, or kept private within a Virtual Private Cloud (VPC) network?
  • Are you planning to write your own connection code, or connect using publicly available tools such as the Cloud SQL Auth proxy or a psql client?
  • Do you want to require encryption through SSL/TLS or allow unencrypted traffic?

In the following sections, we discuss the options Cloud SQL provides for connecting, authorizing, and authenticating to your database.

  • How to connect - which network path you use to reach your instance:
    • An internal, VPC-only (Private) IP address.
    • An external, internet-accessible (Public) IP address.
  • How to authorize - which connections are authorized and allowed to connect to your Cloud SQL instance:
    • Cloud SQL Auth proxy and Cloud SQL connector libraries for Java and Python - these provide access based on IAM.
    • Self-managed SSL/TLS certificates - these only allow connections based on specific public keys.
    • Authorized networks - a list of IP addresses allowed to connect.
  • How to authenticate - the method to login to your database.
    • Built-in database authentication - log in with a username/password set in the database engine.
    • IAM database authentication - log in with an email or with an OAuth 2.0 token as a password.

Use the information that follows to decide which connection, authorization, and authentication options work best for you.

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

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.

Private IP

A private IP is an IPv4 or IPv6 address that's accessible on a Virtual Private Cloud (VPC).

You can use this address to connect from other resources with access to the VPC. Connections over private IP typically provide lower latency and limited attack vectors because they don't require traversing the internet. Optionally, you can require that all connections use either the Cloud SQL proxy or self-managed SSL certificates.

Configuring your instance with a private IP is preferred when connecting from a client on a resource with access to a VPC. For more information about what resources can use private IP, see Requirements for Private IP.

For private IP paths, the following services and applications connect directly to your instance through Serverless VPC Access:

  • App Engine standard environment
  • App Engine flexible environment
  • Cloud Functions
  • Cloud Run

Learn more about using private IP with Cloud SQL

For instructions on adding a private IP to your instance, see Configuring Private IP Connectivity.

Public IP

A public IP is an IPv4 or IPv6 address that's available externally on the public internet. This address can receive connections from devices both inside and outside of Google's network, including from locations like your home or office.

To help keep your instance secure, any connections to a Cloud SQL instance using a public IP must be authorized using either the Cloud SQL Auth proxy or authorized networks.

Configuring your instance with a public IP is best when connecting from a client that doesn't meet the requirements for a VPC.

For instructions about adding a public IP to your instance, see Configuring Public IP Connectivity.

For information about connecting a psql client to a Cloud SQL instance using public IP, see Connecting using a database client.

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 Auth proxy.

Authorization options

Cloud SQL Auth Proxy

The Cloud SQL Auth proxy lets you authorize and secure your connections by using Identity and Access Management (IAM) permissions. The Cloud SQL Auth proxy validates connections using credentials for a user or service account and wrapping the connection in a SSL/TLS layer that's authorized for a Cloud SQL instance. For more details about how the Cloud SQL Auth proxy works, see About the Cloud SQL Auth proxy.

Using the Cloud SQL Auth proxy is the recommended method for authenticating connections to a Cloud SQL instance because it's the most secure method.

The Cloud SQL Auth proxy is an open source library distributed as an executable binary. The Cloud SQL Auth proxy acts as an intermediary server that listens for incoming connections, wraps them in SSL/TLS, and then passes them to a Cloud SQL instance.

Some environments provide a mechanism that connects using the Cloud SQL Auth proxy. For instructions about connecting using these environments, see one of the following:

Cloud SQL connector libraries for Java and Python

Cloud SQL offers client libraries that provide encryption and IAM-based authorization when connecting to a Cloud SQL instance by using Java and Python connectors.

You can use these libraries directly from the language environment. They provide the same authentication as the Cloud SQL Auth proxy without requiring an external process. To get started, see Connecting using the Cloud SQL Connectors.

Self-managed SSL/TLS certificates

Instead of using the Cloud SQL Auth proxy to encrypt your connections, it's possible to set up client/server SSL/TLS certificates that are specific to a Cloud SQL instance. These certificates are used to both validate the client and server to each other and encrypt connections between them.

It's strongly recommended to use self-managed SSL/TLS certificates to provide encryption when not using the Cloud SQL Auth proxy. Failing to do so means your data is being transmitted insecurely and might be intercepted or inspected by a third party.

To get started with self-managed SSL/TLS certificates, see Authorizing with SSL/TLS certificates.

Authorized networks

Unless using the Cloud SQL Auth proxy, connections to the public IP address of an instance are allowed only if the connection come from an authorized network. Authorized networks are IP addresses or ranges that the user has specified as having permission to connect.

To get started with authorized networks, see Authorizing with Authorized Networks.

Authentication options

Authentication provides access control by verifying the identity of a user. For end users, authentication is achieved when the user enters credentials (a username and password). For applications, authentication is achieved when a user's credentials are assigned to a service account.

Cloud SQL uses the database's built-in authentication that authenticates using a username and password. For more information, see creating and managing PostgreSQL users.

Cloud SQL is also integrated with IAM to help you better monitor and manage the database access of users and service accounts. This feature is called IAM database authentication.

Learn more about IAM database authentication.

Learn more about creating and managing users that use IAM database authentication.

Tools for connecting

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

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

Code samples

You can connect to the Cloud SQL Auth proxy from any language that enables you to connect to a Unix or TCP socket. Below are some code snippets from complete examples on GitHub to help you understand how they work together in your application.

Troubleshooting

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

What's next