Introduction

Generally, connection issues fall into one of the following three areas:

• Connecting - are you able to reach your instance over the network?
• Authorizing - are you authorized to connect to the instance?
• Authenticating - does the database accept your database credentials?

Each of those can be further broken down into different paths forinvestigation. The following section includes examples of questions you can askyourself to help further narrow down the issue:

Connection issues checklist

• Connecting
• Private IP
• Have youenabled theService Networking API for your project?
• Are youusing a Shared VPC?
• Does your user or service account have therequired IAM permissions to manage a private services access connection?
• Isprivate services access connection configured for your project?
• Did youallocate an IP address range for the private connection?
• Did yourallocated IP address ranges contain at least a /24 space for every region where you are planning to create mysql instances?
• If you are specifying anallocated IP address range for your mysql instances, does the range contain at least a /24 space for every region where you are planning to create mysql instances in this range?
• Is theprivate connection created?
• If the private connection was changed, were thevpc-peerings updated?
• Do theVPC logs indicate any errors?
• Is your source machine's IP anon-RFC 1918 address?
• Public IP
• Is your source IP listed as anauthorized network?
• Are SSL/TLS certificatesrequired?
• Does your user or service account have therequired IAM permissions to connect to a Cloud SQL instance?
• Authorizing
• Cloud SQL Auth Proxy
• Is the Cloud SQL Auth Proxyup to date?
• Is the Cloud SQL Auth Proxyrunning?
• Is the instanceconnection name formed correctly in theCloud SQL Auth Proxy connection command?
• Have you checked the Cloud SQL Auth Proxy output? Pipe the output to a file, or watch the Cloud Shell terminal where you started the Cloud SQL Auth Proxy.
• Does your user or service account have therequired IAM permissions to connect to a Cloud SQL instance?
• Have youenabled theCloud SQL Admin API for your project?
• If you have an outbound firewall policy, make sure it allows connections to port 3307 on the target Cloud SQL instance.
• If you are connecting using UNIX domain sockets, confirm that the sockets were created by listing the directory specified with the-dir when you started the Cloud SQL Auth Proxy.
• Cloud SQL connectors and language-specific code
• Is theconnection string formed correctly?
• Have you compared your code with thesample code for your programming language?
• Are you using a runtime or framework for which we don't havesample code?
• If so, have youlooked to the community for relevant reference material?
• Self-managed SSL/TLS certificates
• Is the client certificateinstalled on the source machine?
• Is the client certificate spelled correctly in theconnection arguments?
• Is the client certificatestill valid?
• Are you getting errors whenconnecting using SSL?
• Is the server certificatestill valid?
• Authorized networks
• Is thesource IP address included?
• Are you using anon-RFC 1918 IP address?
• Are you using anunsupported IP address?
• Connection failures
• Are youauthorized to connect?
• Are you seeingconnection limit errors?
• Is your applicationclosing connections properly?
• Authenticating
• Native database authentication (username/password)
• Are you seeingaccess denied errors?
• Are theusername and password correct?
• IAM database authentication
• Have youenabled thecloudsql.iam_authentication flagon your instance?
• Did youadd a policy binding for the account?
• Are you using the Cloud SQL Auth Proxy with the-enable_iam_login or an Oauth 2.0 token as the database password?
• If using a service account, are you using theshortened email name?
• Learn more aboutIAM database authentication in PostgreSQL.

Error messages

For specific API error messages, see theError messages reference page.

Additional connectivity troubleshooting

For other issues, see theConnectivity section in the troubleshooting page.

Common connection issues

Verify that your application is closing connections properly

If you see errors containing "Aborted connection nnnn to db:", it usuallyindicates that your application is not stopping connections properly. Network issues can also cause this error. The error does not mean thatthere are problems with your Cloud SQL instance. You are also encouraged to runtcpdump to inspect the packets to track down the source of the problem.

For examples of best practices for connection management, seeManaging database connections.

Verify that your certificates have not expired

If your instance is configured to use SSL, go to theCloud SQL Instances pagein the Google Cloud console and open the instance. Open itsConnections page, select theSecurity tab and make sure that your server certificate is valid. If it has expired, you mustadd a new certificate and rotate to it.

Verify that you are authorized to connect

If your connections are failing, check that you are authorized to connect:

• If you are having trouble connecting using an IP address, for example,you are connecting from your on-premises environment with the mysqlclient, then make sure that the IP address you are connecting fromis authorized to connectto the Cloud SQL instance.

  Connections to a Cloud SQL instance using a private IP address areautomatically authorized forRFC 1918address ranges. This way, all private clients can access the databasewithout going through the Cloud SQL Auth Proxy. Non-RFC 1918 address ranges must be configuredasauthorized networks.

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

  gcloudcomputenetworkspeeringsupdatecloudsql-mysql-googleapis-com\--network=NETWORK\--export-subnet-routes-with-public-ip\--project=PROJECT_ID

• Here's yourcurrent IP address.

• Try thegcloud sql connectcommand to connect to your instance. This command authorizes your IP address for ashort time. You can run this command in an environment withgcloud CLI and mysql client installed. You can also run this commandinCloud Shell, which is available in theGoogle Cloud console and hasgcloud CLI and the mysql client pre-installed.Cloud Shell provides a Compute Engine instance that you can useto connect to Cloud SQL.
• Temporarily allow all IP addresses to connect to an instance. For IPv4authorize0.0.0.0/0 (for IPv6, authorize::/0.Note: Authorizing all IP addresses opens yourdatabase to any client that tries to connect. If you have sensitive orproprietary data in your database, don't use this method to investigateconnectivity issues.

Verify how you connect

ERROR 1045 (28000): Access denied for user 'root'@'1.2.3.4' (using password: NO)

ERROR 1045 (28000): Access denied for user 'root'@'1.2.3.4' (using password: YES)

SHOWPROCESSLIST;

There are no QPS limits for Cloud SQL instances. However, there are connection,size, and App Engine specific limits in place. SeeQuotas and Limits.

Database connections consume resources on the server and the connectingapplication. Always use good connection management practices to minimizeyour application's footprint and reduce the likelihood of exceedingCloud SQLconnection limits.For more information, seeManaging database connections.

Show connections and threads

If you get the "too many connections" error message, or want to find out what ishappening on an instance, you can show the number of connections and threadswithSHOW PROCESSLIST.

From aMySQL client, run:

mysql>SHOWPROCESSLIST;

You get output similar to the following:

+----+-----------+--------------+-----------+---------+------+-------+----------------------+| Id | User      | Host         | db        | Command | Time | State | Info                 |+----+-----------+--------------+-----------+---------+------+-------+----------------------+|  3 | user-name | client-IP    | NULL      | Query   |    0 | NULL  | SHOW processlist     ||  5 | user-name | client-IP    | guestbook | Sleep   |    1 |       | SELECT * from titles || 17 | user-name | client-IP    | employees | Query   |    0 | NULL  | SHOW processlist     |+----+-----------+--------------+-----------+---------+------+-------+----------------------+3 rows in set (0.09 sec)

For information about how to interpret the columns returned fromPROCESSLIST, see theMySQL reference.

To get a thread count, you can use:

mysql>SHOWSTATUSWHEREVariable_name='Threads_connected';

You get output similar to the following:

+-------------------+-------+| Variable_name     | Value |+-------------------+-------+| Threads_connected | 7     |+-------------------+-------+1 row in set (0.08 sec)

Connections timeout (from Compute Engine)

Connections with a Compute Engine instance timeout after 10 minutes ofinactivity, which can affect long-lived unused connections between yourCompute Engine instance and your Cloud SQL instance. For moreinformation, seeNetworking and Firewallsin the Compute Engine documentation.

To keep long-lived unused connections alive, you can set theTCP keepalive.The following commands set the TCP keepalive value to one minute and make theconfiguration permanent across instance reboots.

Display the current tcp_keepalive_time value.

cat/proc/sys/net/ipv4/tcp_keepalive_time

Set tcp_keepalive_time to 60 seconds and make it permanent across reboots.

echo'net.ipv4.tcp_keepalive_time = 60'|sudotee-a/etc/sysctl.conf

Apply the change.

sudo/sbin/sysctl--load=/etc/sysctl.conf

Display the tcp_keepalive_time value to verify the change was applied.

cat/proc/sys/net/ipv4/tcp_keepalive_time

Connect with IPv6

If you get either of the error messages

Can't connect to MySQL server on '2001:1234::4321' (10051)Can't connect to MySQL server on '2001:1234::4321' (101)

when you connect it is likely that you are attempting to connect to the IPv6address of your instance but do not have IPv6 available on your workstation. Youcan verify whether IPv6 is functional on your workstation by going toipv6.google.com. If it does not load thenyou do not have IPv6 available. Connect to the IPv4address or your Cloud SQL instance instead. You may need toadd an IPv4 address to your instance first.

Occasional connection failures (Legacy HA)

When Cloud SQL restarts an instance due to maintenance events,connections might be routed to the failover replica. When connecting to thefailover replica:

• Read requests from clients using unencrypted connections succeed as normal.However, write requests fail and return an error message, such as 'Error1290: The MySQL server is running with the --read-only option so it cannotexecute this statement.'
• Read and write requests from clients using encrypted connections fail andreturn an error message, such as 'x509: certificate is valid formaster-instance, not failover-instance.'

After the event is over, Cloud SQL resets the connection.Retry the connection. We recommend that you design your applications to handleoccasional connection failures by implementing an error handling strategy likeexponential backoff. SeeApplication implementation for more information.

Tools for debugging connectivity

Connectivity Test is a diagnostics tool that lets you check connectivity between endpoints in your network. It analyzes your configuration and in some cases performs run-time verification. It supportsCloud SQL now. Followthese instructions to run tests with your Cloud SQL instances.

Test your connection

You can use the mysql client to test your ability to connectfrom your local environment. For more information, seeConnecting the mysql client using IP addresses andConnecting the mysql client using the Cloud SQL Auth Proxy.

Determine the IP address for your application

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

• If the computer is not behind a proxy or firewall, log in to the computer and use theWhat is my IP? site to determine its IP address.
• If the computer is behind a proxy or firewall, log in to the computer anduse a tool or service likewhatismyipaddress.comto determine its true IP address.

Open local ports

To verify that your host is listening on the ports you think it is, run thess -tunlp4 command. This tells you what ports are open andlistening.For example, if you have a MySQL database running, then port 3306 should be up andlistening. For SSH, you should see port 22.

All local port activity

Use thenetstat command to see all the local port activity. Forexample,netstat -lt shows all the currently active ports.

Connect to your Cloud SQL instance using telnet

To verify that you can connect to your Cloud SQL instance usingTCP, runthetelnet command. Telnet attempts to connect to the IP address andport you give it.

On success, you see the following:

Trying 35.193.198.159...

Connected to 35.193.198.159..

On failure, you seetelnet hangs until you force-close the attempt:

Trying 35.193.198.159...

^C..

Cloud Logging

Cloud SQL and Cloud SQL use Cloud Logging. See theCloud Logging documentationfor complete information and review theCloud SQL sample queries.

View logs

You can view logs for Cloud SQL instances and other Google Cloudprojects such as Cloud VPN or Compute Engine instances. To view logs foryour Cloud SQL instance log entries:

gcloudloggingread"projects/PROJECT_ID/logs/cloudsql.googleapis.com/mysql-general.log"\--limit=10

Private IP addresses

Connections to a Cloud SQL instance using a private IP address areautomatically authorized forRFC 1918address ranges. Non-RFC 1918 address ranges must be configuredin Cloud SQL asauthorizednetworks. You also need to update the network peering to Cloud SQL toexport any Non-RFC 1918 routes. For example:

gcloudcomputenetworkspeeringsupdatecloudsql-mysql-googleapis-com
--network=NETWORK
--export-subnet-routes-with-public-ip
--project=PROJECT_ID

VPN troubleshooting

See theCloud VPN troubleshooting page.