Connecting Overview

This page provides a summary of options for connecting to your Cloud SQL instance.

Overview

In order to connect to your Cloud SQL instance, there are two considerations:

  • How to connect - which network path you use to reach your instance; either an external, internet accessible (public) IP address, or an internal, VPC-only (private) IP address.
  • How to authenticate - which connections are authorized and allowed to connect to your Cloud SQL instance.

Use the information below to decide which connection and authentication options work best for you.

Connection options

Private IP

A private IP is an IPv4 or IPv6 address that is 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, as they don't require traversing the internet.

Connections to a Cloud SQL instance using a private IP address are automatically authorized for RFC 1918 address ranges. This way, all private clients can access the database without going through the proxy. Non-RFC 1918 address ranges must be configured as authorized networks.

Optionally, it is possible to require all connections use either the Cloud SQL proxy or self-managed SSL certificates.

Connecting 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 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 is 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.

In order 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 proxy or authorized networks.

Connecting 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.

Authentication options

Cloud SQL proxy

The Cloud SQL proxy allows you to authenticate and secure your connections using Identity and Access Management (IAM) permissions. The proxy validates connections using credentials user or service account, and wrapping the connection in a SSL/TLS layer that is authenticated for a Cloud SQL instance. For more details about how the Cloud SQL proxy works, see About the Cloud SQL proxy.

Using the Cloud SQL proxy is the recommended method for authenticating connections to a Cloud SQL instance, as it is the most secure method.

The client proxy is an open source library distributed as an exectuable binary. The client 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.

Additionally, some languages have the option of using a client library. You can use these libraries directly from the language environment; they provide the same authentication as the proxy without requiring an external process. To get started, see the following pages:

Self-managed SSL/TLS certificates

Instead of using the Cloud SQL Proxy to encrypt your connections, it is 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/server to each other and encrypt connections between them.

It is strongly recommended to use self-managed SSL/TLS certificates to provide encryption when not using the Cloud SQL Proxy. Failing to do so means your data is being transmitted unsecurely, and may be intercepted or inspected by a third-party.

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

Authorized networks

Unless using the Cloud SQL proxy, connections to an instance's public IP address are only allowed if the connection come from 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.

Troubleshooting

Click the links in the table for details:

For this problem... The issue might be... Try this...
Unauthorized to connect errors. There can be many root causes. See these things to try.
Network association failed. Service Networking API is not enabled in the project. Enable the Service Networking API in the project.
Remaining connection slots are reserved. The maximum number of connections has been reached. Increase the max_connections flag.
Set Service Networking service account as servicenetworking.serviceAgent role on consumer project. Networking permissions on the service account are missing or incorrect. Disable and re-enable the Service Networking API.
error x509: certificate is not valid for any names, but wanted to match project-name:db-name. Known issue: The Cloud SQL Proxy Dialer is not compatible with Go 1.15 at this time. Until fixed, see this discussion on GitHub, which includes a workaround.

Aborted connection

You see the error message Got an error reading communication packets , or Aborted connection xxx to db: DB_NAME.

The issue might be

  • Networking instability.
  • No response to TCP keep-alive commands (either the client or the server is not responsive, possibly overloaded).
  • The database engine connection lifetime was exceeded and the server ends the connection.

Things to try

Applications must tolerate network failures and follow best practices such as connection pooling and retrying. Most connection poolers catch these errors where possible. Otherwise the application must either retry or fail gracefully.

For connection retry, we recommend the following methods:

  1. Exponential backoff. Increase the time interval between each retry, exponentially.
  2. Add randomized backoff also.
Combining these methods helps reduce throttling.

Unauthorized to connect

You see the error message Unauthorized to connect.

The issue might be

There can be many causes, as authorization occurs at many levels.

  • At the database level, the database user must exist and its password must match.
  • At the project level, the user may lack the correct IAM permissions.

  • At the Cloud SQL level, the root cause can depend on how you connect to your instance. If you are connecting directly to an instance through the public IP, the connection's source IP must be in the authorized network of the instance.

    Private IP connectivity is allowed by default, except when you are connecting from a non-RFC 1918 address. Non-RFC 1918 client addresses must be configured as authorized networks.

    Cloud SQL doesn't learn Non-RFC 1918 subnet routes from your VPC by default. You need to update the network peering to Cloud SQL to export any Non-RFC 1918 routes. For example:

    gcloud compute networks peerings update cloudsql-sqlserver-googleapis-com --network=NETWORK --export-subnet-routes-with-public-ip --project=PROJECT

    If you are connecting through the Cloud SQL Proxy, ensure that the IAM permissions are set up correctly.

  • At the network level, if the Cloud SQL instance is using public IP, the connection's source IP must be in an authorized network.

Things to try

  • Check the username and password.
  • Check the user's IAM roles and permissions.
  • If using public IP, make sure the source is in the authorized networks.

Network association failed

You see the error message Error: Network association failed due to the following error: set Service Networking service account as servicenetworking.serviceAgent role on consumer project.

The issue might be

The Service Networking API is not enabled in the project.

Things to try

Enable the Service Networking API in your project. If you see this error when you are trying to assign a private IP address to a Cloud SQL instance, and you are using a shared VPC, you also need to enable the Service Networking API for the host project.

Remaining connection slots are reserved

You see the error message FATAL: remaining connection slots are reserved for non-replication superuser connections.

The issue might be

The maximum number of connections has been reached.

Things to try

Edit the max_connections flag value. Increasing max_connections above a certain value can result in losing SLA support.

Set Service Networking service account as servicenetworking.serviceAgent role on consumer project

You see the error message set Service Networking service account as servicenetworking.serviceAgent role on consumer project..

The issue might be

User or service account permissions are not correct. This can happen during automated setup scripts, such as a Terraform configuration script.

Things to try

To repair service permissions, disable the Service Networking API , wait five minutes and then re-enable it.

Error x509: certificate is not valid for any names

You see the error message error x509: certificate is not valid for any names, but wanted to match project-name:db-name

The issue might be ...

Known issue: The Cloud SQL Proxy Dialer is not compatible with Go 1.15 at this time.

Things to try

Until the bug is fixed, see this discussion on GitHub, which includes a workaround.

What's next