Debug connection issues

MySQL  |  PostgreSQL  |  SQL Server

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

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:

Verify how you connect

If you get an error message like:

FATAL: database `user` does not exist.

Thegcloud sql connect --user command only works with the defaultuser (postgres). The workaround is to connect using the default user, then usethe"\c" psql command to reconnect as the different user.

Determine how connections are being initiated

You can see information about your current connections by connecting to yourdatabase and running the following command:

SELECT*frompg_stat_activity;

Connections that show an IP address, such as1.2.3.4, are connecting using IP.Connections withcloudsqlproxy~1.2.3.4 are using the Cloud SQL Auth Proxy, or else theyoriginated from App Engine. Connections fromlocalhost may beused by some internal Cloud SQL processes.

Connection limits

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

To see the processes that are running on your database, use thepg_stat_activity table:

select*frompg_stat_activity;

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

Tools for debugging connectivity

Note: Tools that are based on the Internet Control Message Protocol (ICMP), suchasping andtraceroute, do not work with Cloud SQL.Do not use these tools for troubleshooting because they can return falsenegatives.

tcpdump

Thetcpdump is a tool to capture packets. It's highly encouraged to runtcpdump to capture and inspect the packets between your host and the Cloud SQL instances when you are debugging the connectivity problems.

Locate your local IP address

If you don't know the local address of your host, then run theip -br address show command. On Linux, this shows the network interface,the status of the interface, the local IP, and MAC addresses. For example:eth0 UP 10.128.0.7/32 fe80::4001:aff:fe80:7/64.

Alternatively, you can runipconfig orifconfig to seethe status of your network interfaces.

Test with Connectivity Test

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 psql client to test your ability to connectfrom your local environment. For more information, seeConnecting the psql client using IP addresses andConnecting the psql 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 PostgreSQL database running, then port 5432 should beup and listening. 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.

If your Cloud SQL instance is running a PostgreSQL database, for example,then you should be able to telnet to it on port 5432:telnet 35.193.198.159 5432.

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

Client authentication

Client authentication is controlled by a configuration file, which is namedpg_hba.conf (HBA stands for host-based authentication).

Make sure the replication connections section of thepg_hba.conffile on the source database is updated to accept connections from theCloud SQL VPC's IP address range.

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:

Console

  1. In the Google Cloud console, go to theCloud Logging page.

    Go to Cloud Logging

  2. Select an existing Cloud SQL project at the top of the page.
  3. In the Query builder, add the following:
    • Resource: SelectCloud SQL Database. In the dialog, select a Cloud SQL instance.
    • Log names: Scroll to the Cloud SQL section and select appropriate log files for your instance. For example:
      • cloudsql.googleapis.com/postgres.log
    • Severity: Select a log level.
    • Time range: Select a preset or create a custom range.

gcloud

Use thegcloud loggingcommand to view log entries. In the example below, replacePROJECT_ID.Thelimitflag is an optional parameter that indicates the maximum number of entries toreturn.

gcloudloggingread"projects/PROJECT_ID/logs/cloudsql.googleapis.com/postgres.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-postgres-googleapis-com
--network=NETWORK
--export-subnet-routes-with-public-ip
--project=PROJECT_ID

VPN troubleshooting

See theCloud VPN troubleshooting page.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-07-14 UTC.