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.
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
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 authorize and secure your connections using Identity and Access Management (IAM) permissions. The proxy validates connections using credentials for a user or service account, and wrapping the connection in a SSL/TLS layer that is authorized 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 executable 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.
To get started using the Cloud SQL proxy as a binary, see Authorizing with the Cloud SQL proxy.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:
Finally, some environments such as Cloud Run, Cloud Functions, and App Engine provide a mechanism that connects using the Cloud SQL Proxy. For instructions about connecting using these environments, see one of the following:- Connecting from Cloud Run
- Connecting from Cloud Functions
- Connecting from App Engine standard environment
- Connecting from App Engine flexible environment
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 and 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.
Connecting from external applications
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.
Connection options compared
The following table compares the options for connecting 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 mysql 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. |
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.
The best solution for these applications is to connect by using the Cloud SQL Proxy. This solution provides the best access control for your instance.
Testing your connection
You can use the mysql client to test your ability to connect from your local environment. For more information, see Connecting the mysql client using IP addresses and Connecting the mysql client using the Cloud SQL Proxy.
Need help? For help troubleshooting the proxy, see Troubleshooting Cloud SQL Proxy connections. Or, 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 whatismyipaddress.com to determine its true IP address.
Code samples
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..NET
After starting the proxy, edit your appsettings.json
file
and define a connection string in CloudSql:ConnectionString
.
For example:
{ "CloudSQL" : { ConnectionString": "Host=127.0.0.1;Uid=DATABASE_USER;Pwd=PASSWORD;Database=DATABASE_NAME" } }
Then, in your Startup.cs
file, create a database connection:
Go
You can use the Cloud SQL Proxy with the Go programming language in two ways:
- Using the Go Proxy library
- Running the proxy as a companion process
Go Proxy library
The library provides the easiest way to connect to Cloud SQL 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/mysql" ) ... cfg := mysql.Cfg(INSTANCE_CONNECTION_NAME, DATABASE_USER, PASSWORD) cfg.DBName = DATABASE_NAME db, err := mysql.DialCfg(cfg)
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. See Options for authenticating the Cloud SQL Proxy.
TCP Sockets
Proxy invocation statement:
./cloud_sql_proxy -instances=[INSTANCE_CONNECTION_NAME]=tcp:3306 &
Connection statement:
import ( "database/sql" _ "github.com/go-sql-driver/mysql" ) dsn := fmt.Sprintf("%s:%s@tcp(%s)/%s", DATABASE_USER, PASSWORD, "127.0.0.1:3306", DATABASE_NAME) db, err := sql.Open("mysql", dsn)
Unix sockets
Proxy invocation statement:
./cloud_sql_proxy -instances=[INSTANCE_CONNECTION_NAME] -dir=/cloudsql &
Connection statement:
import ( "database/sql" _ "github.com/go-sql-driver/mysql" ) dsn := fmt.Sprintf("%s:%s@unix(/cloudsql/%s)/%s", DATABASE_USER, PASSWORD, INSTANCE_CONNECTION_NAME, DATABASE_NAME) db, err := sql.Open("mysql", dsn)
Java
The Java programming language does not provide built-in support for Unix sockets. You can use TCP sockets or a library that provides Unix socket support with the Cloud SQL Proxy, but the easiest way to connect to a Cloud SQL instance without adding authorized network addresses is to use the JDBC socket factory.
The JDBC socket factory provides an alternative to the client-side proxy software, and requires you to enable the Cloud SQL Admin API, just as the Cloud SQL Proxy does. The socket factory provides the same level of encryption as the proxy, and authenticates with Cloud SDK credentials. You must install and authenticate the Cloud SDK before using the socket factory.
See Cloud SQL Socket Factory for JDBC drivers for code examples. Review the README for instructions.
PHP
PDO & TCP
Invoke the proxy:
./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:3306 &
The following examples connect to Cloud SQL using PHP Data Objects (PDO):
// Use a Data source name (DSN) to connect to Cloud SQL through the proxy $dsn = 'mysql:host=127.0.0.1;port=3306;dbname=DATABASE_NAME'; // Instantiate your DB using the DSN, username, and password $dbUser = 'DATABASE_USER'; $dbPass = 'PASSWORD'; $db = new PDO($dsn, $dbUser, $dbPass);
PDO & Unix sockets
Invoke the proxy:
./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME -dir=/cloudsql &
The following examples connect to Cloud SQL using PDO:
// Use a Data source name (DSN) to connect to Cloud SQL through the proxy $dsn = sprintf('mysql:unix_socket=/cloudsql/INSTANCE_CONNECTION_NAME;dbname=DATABASE_NAME'; // Instantiate your DB using the DSN, username, and password $dbUser = 'DATABASE_USER'; $dbPass = 'PASSWORD'; $db = new PDO($dsn, $dbUser, $dbPass);
mysqli & TCP
Invoke the proxy:
./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:3306 &
The following examples connect to Cloud SQL using mysqli:
// Instantiate your DB using the database host, port, name, username, and password $dbName = 'DATABASE_NAME'; $dbUser = 'DATABASE_USER'; $dbPass = 'PASSWORD'; $mysqli = new mysqli('127.0.0.1', $dbUser, $dbPass, $dbName, 3306);
mysqli & Unix Sockets
Invoke the proxy:
./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME -dir=/cloudsql &
The following examples connect to Cloud SQL using mysqli:
// Instantiate your DB using the database name, socket, username, and password $dbName = 'DATABASE_NAME'; $dbUser = 'DATABASE_USER'; $dbPass = 'PASSWORD'; $dbSocket = '/cloudsql/INSTANCE_CONNECTION_NAME'; $mysqli = new mysqli(null, $dbUser, $dbPass, $dbName, null, $dbSocket);
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.
PyMySQL & TCP
Invoke the proxy:
./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:3306 &
Connection statement:
import pymysql connection = pymysql.connect(host='127.0.0.1', user='DATABASE_USER', password='PASSWORD', db='DATABASE_NAME')
PyMySQL & Unix
Invoke the proxy:
./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME -dir=/cloudsql &
Connection statement:
import pymysql connection = pymysql.connect(unix_socket='/cloudsql/' + INSTANCE_CONNECTION_NAME, user='DATABASE_USER', password='PASSWORD', db='DATABASE_NAME')
SQLAlchemy & TCP
Invoke the proxy:
./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:3306 &
Connection statement:
from sqlalchemy import create_engine engine = create_engine('mysql+pymysql://DATABASE_USER:PASSWORD@127.0.0.1/DATABASE_NAME')
SQLAlchemy & Unix
Invoke the proxy:
./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME -dir=/cloudsql &
Connection statement:
from sqlalchemy import create_engine engine = create_engine('mysql+pymysql://DATABASE_USER:PASSWORD@/DATABASE_NAME?unix_socket=/cloudsql/INSTANCE_CONNECTION_NAME')
Ruby
mysql2 & TCP
Invoke the proxy:
./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:3306 &
The following examples connect to Cloud SQL using the mysql2 RubyGem:
require "mysql2" client = Mysql2::Client.new host: "127.0.0.1", port: 3306, database: "DATABASE_NAME", username: "DATABASE_USER", password: "PASSWORD"
>mysql2 & Unix Sockets
Invoke the proxy:
./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME -dir=/cloudsql &
The following examples connect to Cloud SQL using the mysql2 RubyGem:
require "mysql2" client = Mysql2::Client.new socket: "/cloudsql/CONNECTION_NAME", database: "DATABASE_NAME", username: "DATABASE_USER", password: "PASSWORD"
Rails & TCP
Invoke the proxy:
./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:3306 &
In config/databases.yml
, use the following configuration:
mysql_settings: &mysql_settings adapter: mysql2 encoding: utf8 pool: 5 username: DATABASE_USER password: PASSWORD database: DATABASE_NAME host: 127.0.0.1:3306
Rails & Unix Sockets
Invoke the proxy:
./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME -dir=/cloudsql &
In config/databases.yml
, use the following configuration:
mysql_settings: &mysql_settings adapter: mysql2 encoding: utf8 pool: 5 username: DATABASE_USER password: PASSWORD database: DATABASE_NAME socket: /cloudsql/INSTANCE_CONNECTION_NAME
Troubleshooting
Click the links in the table for details:
For this problem... | The issue might be... | Try this... |
---|---|---|
Aborted connection . |
Error reading packets or connection aborted. | See these things to try. |
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. |
Cannot parse certificates in some operating systems. | Clients using x509 libraries from mac OS 11.0 (Big Sur) may fail to parse some certificates of mysql instances. This may be surfaced to the client as a generic error, like "cancelled". | The workaround is to rotate the server certificate and recreate client certificates. |
Cannot modify allocated ranges in CreateConnection. Please use UpdateConnection . |
VPC peerings were not updated after an allocated range was modified or removed. | See Things to try for VPC peering update details. |
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:
- Exponential backoff. Increase the time interval between each retry, exponentially.
- Add randomized backoff also.
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-mysql-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.
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.
You can also try using these gcloud
commands to assign the role
to the project
gcloud beta services identity create --service=servicenetworking.googleapis.com --project=project-id
gcloud projects add-iam-policy-binding project-id --member="service-account-prefix@service-networking.iam.gserviceaccount.com" --role="roles/servicenetworking.serviceAgent"
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.
Cannot parse certificates in some operating systems
When you use x509 libraries from mac OS 11.0 (Big Sur), you may fail to parse the certificates of mysql instances. This may be surfaced as a generic error, like "cancelled."
Things to try
The bug is fixed and the new instances won't hit this problem. For old instances hitting this problem, rotate the server certificate and recreate client certificates.
Cannot modify allocated ranges in CreateConnection. Please use UpdateConnection
You see the error message Cannot modify allocated ranges in CreateConnection. Please use UpdateConnection
.
The issue might be ...
When a range was reserved and then removed, the private connection is also removed. You get this error when you attempt to make a connection using a different reserved range without first recreating the private connection.
Things to try
You need to recreate the private connection.
Use the following command, and make sure to use the --force
argument:
gcloud services vpc-peerings update --network=VPC_NETWORK --ranges=ALLOCATED_RANGES --service=servicenetworking.googleapis.com --force
What's next
- Learn how to connect with the Quickstart for Cloud SQL for mysql.
- Learn best practices for managing database connections.
- Learn about IAM database authentication.
- Learn about connecting using a mysql client.
- Learn about configuring IP connectivity.
- Learn about connecting with other MySQL tools.
- Learn about MySQL connectors.
- Learn about the proxy.
- Learn about options for support.