About Cloud SQL connections

MySQL   |  PostgreSQL   |  SQL Server

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, or make it both publicly and privately accessible?
• Are you planning to write your own connection code, or connect using publicly available tools such as the Cloud SQL Auth Proxy or a mysql 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.

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

You can create an account to evaluate how Cloud SQL performs in real-world scenarios. New customers also get $300 in free credits to spend on Cloud SQL to run, test, and deploy workloads. You won't be charged until you upgrade.

Sign up to try Cloud SQL for free.

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. For more information, see Manage users with built-in authentication.

How to connect to Cloud SQL

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.

Public and private IP

In Cloud SQL, public IP means that the instance is accessible through the public internet. In contrast, instances using only private IP are not accessible through the public internet, but are accessible through a Virtual Private Cloud (VPC). Cloud SQL instances can have both a public and a private IP address.

Private IP

A private IP is an IPv4 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 Run functions
• Cloud Run

Learn more about using private IP with Cloud SQL

For instructions on adding a private IP to your instance, see one of the following:

• Configuring Private IP Connectivity.
• Connect to an instance using Private Service Connect

Public IP

A public IP is an IPv4 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 mysql 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.

The best solution for these applications is to connect by using the Cloud SQL Auth Proxy. This solution provides the best access control for your instance.

Connection options for instances

This section contains features that Cloud SQL supports for connecting to instances. The section also contains supported connection options for creating, deactivating, and enabling instances.

Supported features

The following table lists the features that Cloud SQL supports for connecting to instances by using private connections.

Feature	Instance with private services access only	Instance with Private Service Connect only	Instance with both private services access and Private Service Connect
Connect from multiple VPCs	Not supported.	Supported.	Supported by using the Private Service Connect endpoint.
External replicas	Supported.	Not supported.	Supported by using outbound connectivity for private services access.
Write endpoint	Supported.	Not supported.	Supported for private services access.
Change the associated VPC network for private services access	Supported.	Not applicable.	Not supported for private services access because the instance has Private Service Connect enabled for it. Not applicable for Private Service Connect.
Visibility of the client IP address to Cloud SQL	Supported.	Not supported.	Supported by using the private services access IP address. Not supported by using the Private Service Connect endpoint.

Connection options for creating instances

Cloud SQL supports private IP and public IP configurations. You can choose connection options based on your application requirements.

You can configure private IP to keep your Cloud SQL instances private within a VPC network. The following types of private connections are supported:

• Private services access: connect to Cloud SQL instances from a single VPC network
• Private Service Connect: connect to Cloud SQL instances from multiple VPC networks that belong to different groups, teams, projects, or organizations

If you want your instance to access connections from clients both inside and outside of Google Cloud's network over the public internet, then configure public IP for the instance.

Cloud SQL supports the following connection options for creating instances:

• Private services access only
• Private Service Connect only
• Public IP only
• Both private services access and Private Service Connect
• Both public IP and private services access
• Public IP, private services access, and Private Service Connect

Deactivate connection options

Cloud SQL supports deactivating the following connection options for instances:

• Public IP on an instance with both private services access and public IP
• Public IP on an instance with public IP, private services access, and Private Service Connect
• Private Service Connect on an instance with both Private Service Connect and private services access
• Private Service Connect on an instance with Private Service Connect, private services access, and public IP

Enable connection options

Cloud SQL supports enabling the following connection options for instances:

• Private services access on an instance with public IP only
• Private Service Connect on an instance with private services access only
• Private Service Connect on an instance with both private services access and public IP
• Public IP on an instance with private services access only

Limitations

• Creating an instance with both public IP and Private Service Connect isn't supported.
• Deactivating private services access on an instance with both private services access and Private Service Connect isn't supported.
• Deactivating private services access on an instance with both private services access and public IP isn't supported.
• If you have an instance that uses only public IP, then enabling both private services access and Private Service Connect together isn't supported. First, enable private services access, and then enable Private Service Connect.
• IP-based allowlisting by using authorized networks isn't supported for instances that have Private Service Connect enabled for them.

How to authorize to Cloud SQL

Note: These options only let you control which connections are allowed to connect to your instance. You must still provide a database username and password to authenticate with the database engine.

Cloud SQL Language Connectors

Cloud SQL Language Connectors are client libraries that provide encryption and IAM authorization when connecting to a Cloud SQL instance. Cloud SQL recommends using the Cloud SQL Language Connectors to connect to your Cloud SQL instance over other connection options.

You can use these libraries directly from their supported programming language. They provide the same authentication as the Cloud SQL Auth Proxy without requiring an external process. This provides improved security and reduced configuration requirements to connect to Cloud SQL. Cloud SQL Language Connectors also use the same code when connecting using a public IP address or a private IP address.

To get started, see About the Cloud SQL Language Connectors.

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:

• Connecting from Cloud Run
• Connecting from Cloud Run functions
• Connecting from the App Engine standard environment
• Connecting from the App Engine flexible environment
• Connecting from Google Kubernetes Engine

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

Note: It's strongly encouraged to always use self-managed SSL/TLS certificates when using authorized networks to authenticate connections. Unless encrypted, your traffic might be vulnerable to interception by third parties.

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

Warning: Use caution when adding authorized networks. Because all devices on a network often share the same external IP address, authorizing a single address might authorize all devices on the same network instead of a single client.

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

How to authenticate to Cloud SQL

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

Tools for connecting to Cloud SQL

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

Connection option	More information
Cloud SQL Auth Proxy	About the Cloud SQL Auth Proxy Connecting using the Cloud SQL Auth Proxy Connecting using the Cloud SQL Auth Proxy Docker Image
gcloud CLI	gcloud sql connect
Cloud SQL language connectors	Connect using Cloud SQL Connectors for Java, Python and Go.
Cloud Shell	Connecting using the Cloud Shell
Apps Script	External connections with Apps Script Apps Script sample GitHub page
Cloud Code	Connecting using Cloud Code in JetBrains IDE
Connect using third-party database administration tools
MySQL Workbench	Connecting with MySQL Workbench
Toad for MySQL	Connecting with Toad for MySQL
SQuirrel SQL	Connecting with SQuirrel SQL
phpMyAdmin	Using phpMyAdmin with Cloud SQL on App Engine

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.

Connecting with TCP

Cloud SQL Auth Proxy invocation statement:

./cloud-sql-proxy INSTANCE_CONNECTION_NAME &

Python

To see this snippet in the context of a web application, view the README on GitHub.

import os

import sqlalchemy


def connect_tcp_socket() -> sqlalchemy.engine.base.Engine:
    """Initializes a TCP connection pool for a Cloud SQL instance of MySQL."""
    # Note: Saving credentials in environment variables is convenient, but not
    # secure - consider a more secure solution such as
    # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
    # keep secrets safe.
    db_host = os.environ[
        "INSTANCE_HOST"
    ]  # e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
    db_user = os.environ["DB_USER"]  # e.g. 'my-db-user'
    db_pass = os.environ["DB_PASS"]  # e.g. 'my-db-password'
    db_name = os.environ["DB_NAME"]  # e.g. 'my-database'
    db_port = os.environ["DB_PORT"]  # e.g. 3306

    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # mysql+pymysql://<db_user>:<db_pass>@<db_host>:<db_port>/<db_name>
        sqlalchemy.engine.url.URL.create(
            drivername="mysql+pymysql",
            username=db_user,
            password=db_pass,
            host=db_host,
            port=db_port,
            database=db_name,
        ),
        # ...
    )
    return pool

Java

To see this snippet in the context of a web application, view the README on GitHub.

Note:

• INSTANCE_CONNECTION_NAME should be represented as <MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME>
• Using the argument ipTypes=PRIVATE will force the SocketFactory to connect with an instance's associated private IP
• See the JDBC socket factory version requirements for the pom.xml file here .

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;

public class TcpConnectionPoolFactory extends ConnectionPoolFactory {

  // Saving credentials in environment variables is convenient, but not secure - consider a more
  // secure solution such as https://cloud.google.com/secret-manager/ to help keep secrets safe.
  private static final String DB_USER = System.getenv("DB_USER");
  private static final String DB_PASS = System.getenv("DB_PASS");
  private static final String DB_NAME = System.getenv("DB_NAME");

  private static final String INSTANCE_HOST = System.getenv("INSTANCE_HOST");
  private static final String DB_PORT = System.getenv("DB_PORT");


  public static DataSource createConnectionPool() {
    // The configuration object specifies behaviors for the connection pool.
    HikariConfig config = new HikariConfig();

    // The following URL is equivalent to setting the config options below:
    // jdbc:mysql://<INSTANCE_HOST>:<DB_PORT>/<DB_NAME>?user=<DB_USER>&password=<DB_PASS>
    // See the link below for more info on building a JDBC URL for the Cloud SQL JDBC Socket Factory
    // https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory#creating-the-jdbc-url

    // Configure which instance and what database user to connect with.
    config.setJdbcUrl(String.format("jdbc:mysql://%s:%s/%s", INSTANCE_HOST, DB_PORT, DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", "mysql"
    config.setPassword(DB_PASS); // e.g. "my-password"


    // ... Specify additional connection properties here.
    // ...

    // Initialize the connection pool using the configuration object.
    return new HikariDataSource(config);
  }
}

Node.js

To see this snippet in the context of a web application, view the README on GitHub.

const mysql = require('promise-mysql');
const fs = require('fs');

// createTcpPool initializes a TCP connection pool for a Cloud SQL
// instance of MySQL.
const createTcpPool = async config => {
  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  const dbConfig = {
    host: process.env.INSTANCE_HOST, // e.g. '127.0.0.1'
    port: process.env.DB_PORT, // e.g. '3306'
    user: process.env.DB_USER, // e.g. 'my-db-user'
    password: process.env.DB_PASS, // e.g. 'my-db-password'
    database: process.env.DB_NAME, // e.g. 'my-database'
    // ... Specify additional properties here.
    ...config,
  };
  // Establish a connection to the database.
  return mysql.createPool(dbConfig);
};

Go

To see this snippet in the context of a web application, view the README on GitHub.

package cloudsql

import (
	"crypto/tls"
	"crypto/x509"
	"database/sql"
	"errors"
	"fmt"
	"log"
	"os"

	"github.com/go-sql-driver/mysql"
)

// connectTCPSocket initializes a TCP connection pool for a Cloud SQL
// instance of MySQL.
func connectTCPSocket() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Fatal Error in connect_tcp.go: %s environment variable not set.", k)
		}
		return v
	}
	// Note: Saving credentials in environment variables is convenient, but not
	// secure - consider a more secure solution such as
	// Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
	// keep secrets safe.
	var (
		dbUser    = mustGetenv("DB_USER")       // e.g. 'my-db-user'
		dbPwd     = mustGetenv("DB_PASS")       // e.g. 'my-db-password'
		dbName    = mustGetenv("DB_NAME")       // e.g. 'my-database'
		dbPort    = mustGetenv("DB_PORT")       // e.g. '3306'
		dbTCPHost = mustGetenv("INSTANCE_HOST") // e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
	)

	dbURI := fmt.Sprintf("%s:%s@tcp(%s:%s)/%s?parseTime=true",
		dbUser, dbPwd, dbTCPHost, dbPort, dbName)


	// dbPool is the pool of database connections.
	dbPool, err := sql.Open("mysql", dbURI)
	if err != nil {
		return nil, fmt.Errorf("sql.Open: %w", err)
	}

	// ...

	return dbPool, nil
}

C#

To see this snippet in the context of a web application, view the README on GitHub.

using MySql.Data.MySqlClient;
using System;

namespace CloudSql
{
    public class MySqlTcp
    {
        public static MySqlConnectionStringBuilder NewMysqlTCPConnectionString()
        {
            // Equivalent connection string:
            // "Uid=<DB_USER>;Pwd=<DB_PASS>;Host=<INSTANCE_HOST>;Database=<DB_NAME>;"
            var connectionString = new MySqlConnectionStringBuilder()
            {
                // Note: Saving credentials in environment variables is convenient, but not
                // secure - consider a more secure solution such as
                // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
                // keep secrets safe.
                Server = Environment.GetEnvironmentVariable("INSTANCE_HOST"),   // e.g. '127.0.0.1'
                // Set Host to 'cloudsql' when deploying to App Engine Flexible environment
                UserID = Environment.GetEnvironmentVariable("DB_USER"),   // e.g. 'my-db-user'
                Password = Environment.GetEnvironmentVariable("DB_PASS"), // e.g. 'my-db-password'
                Database = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'

                // The Cloud SQL proxy provides encryption between the proxy and instance.
                SslMode = MySqlSslMode.Disabled,
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;

        }
    }
}

Ruby

To see this snippet in the context of a web application, view the README on GitHub.

tcp: &tcp
  adapter: mysql2
  # Configure additional properties here
  # Note: Saving credentials in environment variables is convenient, but not
  # secure - consider a more secure solution such as
  # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  # keep secrets safe.
  username: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_development" } %>
  host: "<%= ENV.fetch("INSTANCE_HOST") { "127.0.0.1" }%>" # '172.17.0.1' if deployed to GAE Flex
  port: <%= ENV.fetch("DB_PORT") { 3306 }%>

PHP

To see this snippet in the context of a web application, view the README on GitHub.

namespace Google\Cloud\Samples\CloudSQL\MySQL;

use PDO;
use PDOException;
use RuntimeException;
use TypeError;

class DatabaseTcp
{
    public static function initTcpDatabaseConnection(): PDO
    {
        try {
            // Note: Saving credentials in environment variables is convenient, but not
            // secure - consider a more secure solution such as
            // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
            // keep secrets safe.
            $username = getenv('DB_USER'); // e.g. 'your_db_user'
            $password = getenv('DB_PASS'); // e.g. 'your_db_password'
            $dbName = getenv('DB_NAME'); // e.g. 'your_db_name'
            $instanceHost = getenv('INSTANCE_HOST'); // e.g. '127.0.0.1' ('172.17.0.1' for GAE Flex)

            // Connect using TCP
            $dsn = sprintf('mysql:dbname=%s;host=%s', $dbName, $instanceHost);

            // Connect to the database
            $conn = new PDO(
                $dsn,
                $username,
                $password,
                # ...
            );
        } catch (TypeError $e) {
            throw new RuntimeException(
                sprintf(
                    'Invalid or missing configuration! Make sure you have set ' .
                        '$username, $password, $dbName, and $instanceHost (for TCP mode). ' .
                        'The PHP error was %s',
                    $e->getMessage()
                ),
                $e->getCode(),
                $e
            );
        } catch (PDOException $e) {
            throw new RuntimeException(
                sprintf(
                    'Could not connect to the Cloud SQL Database. Check that ' .
                        'your username and password are correct, that the Cloud SQL ' .
                        'proxy is running, and that the database exists and is ready ' .
                        'for use. For more assistance, refer to %s. The PDO error was %s',
                    'https://cloud.google.com/sql/docs/mysql/connect-external-app',
                    $e->getMessage()
                ),
                $e->getCode(),
                $e
            );
        }

        return $conn;
    }
}

Connecting with Unix sockets

Cloud SQL Auth Proxy invocation statement:

./cloud-sql-proxy --unix-socket /cloudsql INSTANCE_CONNECTION_NAME &

Python

To see this snippet in the context of a web application, view the README on GitHub.

import os

import sqlalchemy


def connect_unix_socket() -> sqlalchemy.engine.base.Engine:
    """Initializes a Unix socket connection pool for a Cloud SQL instance of MySQL."""
    # Note: Saving credentials in environment variables is convenient, but not
    # secure - consider a more secure solution such as
    # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
    # keep secrets safe.
    db_user = os.environ["DB_USER"]  # e.g. 'my-database-user'
    db_pass = os.environ["DB_PASS"]  # e.g. 'my-database-password'
    db_name = os.environ["DB_NAME"]  # e.g. 'my-database'
    unix_socket_path = os.environ[
        "INSTANCE_UNIX_SOCKET"
    ]  # e.g. '/cloudsql/project:region:instance'

    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # mysql+pymysql://<db_user>:<db_pass>@/<db_name>?unix_socket=<socket_path>/<cloud_sql_instance_name>
        sqlalchemy.engine.url.URL.create(
            drivername="mysql+pymysql",
            username=db_user,
            password=db_pass,
            database=db_name,
            query={"unix_socket": unix_socket_path},
        ),
        # ...
    )
    return pool

Java

To see this snippet in the context of a web application, view the README on GitHub.

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;

public class ConnectorConnectionPoolFactory extends ConnectionPoolFactory {

  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  private static final String INSTANCE_CONNECTION_NAME =
      System.getenv("INSTANCE_CONNECTION_NAME");
  private static final String INSTANCE_UNIX_SOCKET = System.getenv("INSTANCE_UNIX_SOCKET");
  private static final String DB_USER = System.getenv("DB_USER");
  private static final String DB_PASS = System.getenv("DB_PASS");
  private static final String DB_NAME = System.getenv("DB_NAME");

  public static DataSource createConnectionPool() {
    // The configuration object specifies behaviors for the connection pool.
    HikariConfig config = new HikariConfig();

    // The following URL is equivalent to setting the config options below:
    // jdbc:mysql:///<DB_NAME>?cloudSqlInstance=<INSTANCE_CONNECTION_NAME>&
    // socketFactory=com.google.cloud.sql.mysql.SocketFactory&user=<DB_USER>&password=<DB_PASS>
    // See the link below for more info on building a JDBC URL for the Cloud SQL JDBC Socket Factory
    // https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory#creating-the-jdbc-url

    // Configure which instance and what database user to connect with.
    config.setJdbcUrl(String.format("jdbc:mysql:///%s", DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", "mysql"
    config.setPassword(DB_PASS); // e.g. "my-password"

    config.addDataSourceProperty("socketFactory", "com.google.cloud.sql.mysql.SocketFactory");
    config.addDataSourceProperty("cloudSqlInstance", INSTANCE_CONNECTION_NAME);

    // Unix sockets are not natively supported in Java, so it is necessary to use the Cloud SQL
    // Java Connector to connect. When setting INSTANCE_UNIX_SOCKET, the connector will 
    // call an external package that will enable Unix socket connections.
    // Note: For Java users, the Cloud SQL Java Connector can provide authenticated connections
    // which is usually preferable to using the Cloud SQL Proxy with Unix sockets.
    // See https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory for details.
    if (INSTANCE_UNIX_SOCKET != null) {
      config.addDataSourceProperty("unixSocketPath", INSTANCE_UNIX_SOCKET);
    }


    // ... Specify additional connection properties here.
    // ...

    // Initialize the connection pool using the configuration object.
    return new HikariDataSource(config);
  }
}

Node.js

To see this snippet in the context of a web application, view the README on GitHub.

const mysql = require('promise-mysql');

// createUnixSocketPool initializes a Unix socket connection pool for
// a Cloud SQL instance of MySQL.
const createUnixSocketPool = async config => {
  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  return mysql.createPool({
    user: process.env.DB_USER, // e.g. 'my-db-user'
    password: process.env.DB_PASS, // e.g. 'my-db-password'
    database: process.env.DB_NAME, // e.g. 'my-database'
    socketPath: process.env.INSTANCE_UNIX_SOCKET, // e.g. '/cloudsql/project:region:instance'
    // Specify additional properties here.
    ...config,
  });
};

C#

To see this snippet in the context of a web application, view the README on GitHub.

using MySql.Data.MySqlClient;
using System;

namespace CloudSql
{
    public class MySqlUnix
    {
        public static MySqlConnectionStringBuilder NewMysqlUnixSocketConnectionString()
        {
            // Equivalent connection string:
            // "Server=<INSTANCE_UNIX_SOCKET>;Uid=<DB_USER>;Pwd=<DB_PASS>;Database=<DB_NAME>;Protocol=unix"
            var connectionString = new MySqlConnectionStringBuilder()
            {
                // The Cloud SQL proxy provides encryption between the proxy and instance.
                SslMode = MySqlSslMode.Disabled,

                // Note: Saving credentials in environment variables is convenient, but not
                // secure - consider a more secure solution such as
                // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
                // keep secrets safe.
                Server = Environment.GetEnvironmentVariable("INSTANCE_UNIX_SOCKET"), // e.g. '/cloudsql/project:region:instance'
                UserID = Environment.GetEnvironmentVariable("DB_USER"),   // e.g. 'my-db-user
                Password = Environment.GetEnvironmentVariable("DB_PASS"), // e.g. 'my-db-password'
                Database = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'
                ConnectionProtocol = MySqlConnectionProtocol.UnixSocket
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;
        }
    }
}

Go

To see this snippet in the context of a web application, view the README on GitHub.

package cloudsql

import (
	"database/sql"
	"fmt"
	"log"
	"os"

	_ "github.com/go-sql-driver/mysql"
)

// connectUnixSocket initializes a Unix socket connection pool for
// a Cloud SQL instance of MySQL.
func connectUnixSocket() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Fatal Error in connect_unix.go: %s environment variable not set.", k)
		}
		return v
	}
	// Note: Saving credentials in environment variables is convenient, but not
	// secure - consider a more secure solution such as
	// Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
	// keep secrets safe.
	var (
		dbUser         = mustGetenv("DB_USER")              // e.g. 'my-db-user'
		dbPwd          = mustGetenv("DB_PASS")              // e.g. 'my-db-password'
		dbName         = mustGetenv("DB_NAME")              // e.g. 'my-database'
		unixSocketPath = mustGetenv("INSTANCE_UNIX_SOCKET") // e.g. '/cloudsql/project:region:instance'
	)

	dbURI := fmt.Sprintf("%s:%s@unix(%s)/%s?parseTime=true",
		dbUser, dbPwd, unixSocketPath, dbName)

	// dbPool is the pool of database connections.
	dbPool, err := sql.Open("mysql", dbURI)
	if err != nil {
		return nil, fmt.Errorf("sql.Open: %w", err)
	}

	// ...

	return dbPool, nil
}

Ruby

To see this snippet in the context of a web application, view the README on GitHub.

unix: &unix
  adapter: mysql2
  # Configure additional properties here.
  # Note: Saving credentials in environment variables is convenient, but not
  # secure - consider a more secure solution such as
  # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  # keep secrets safe.
  username: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_development" } %>
  # Specify the Unix socket path as host
  socket: "<%= ENV["INSTANCE_UNIX_SOCKET"] %>"

PHP

To see this snippet in the context of a web application, view the README on GitHub.

namespace Google\Cloud\Samples\CloudSQL\MySQL;

use PDO;
use PDOException;
use RuntimeException;
use TypeError;

class DatabaseUnix
{
    public static function initUnixDatabaseConnection(): PDO
    {
        try {
            // Note: Saving credentials in environment variables is convenient, but not
            // secure - consider a more secure solution such as
            // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
            // keep secrets safe.
            $username = getenv('DB_USER'); // e.g. 'your_db_user'
            $password = getenv('DB_PASS'); // e.g. 'your_db_password'
            $dbName = getenv('DB_NAME'); // e.g. 'your_db_name'
            $instanceUnixSocket = getenv('INSTANCE_UNIX_SOCKET'); // e.g. '/cloudsql/project:region:instance'

            // Connect using UNIX sockets
            $dsn = sprintf(
                'mysql:dbname=%s;unix_socket=%s',
                $dbName,
                $instanceUnixSocket
            );

            // Connect to the database.
            $conn = new PDO(
                $dsn,
                $username,
                $password,
                # ...
            );
        } catch (TypeError $e) {
            throw new RuntimeException(
                sprintf(
                    'Invalid or missing configuration! Make sure you have set ' .
                        '$username, $password, $dbName, ' .
                        'and $instanceUnixSocket (for UNIX socket mode). ' .
                        'The PHP error was %s',
                    $e->getMessage()
                ),
                (int) $e->getCode(),
                $e
            );
        } catch (PDOException $e) {
            throw new RuntimeException(
                sprintf(
                    'Could not connect to the Cloud SQL Database. Check that ' .
                        'your username and password are correct, that the Cloud SQL ' .
                        'proxy is running, and that the database exists and is ready ' .
                        'for use. For more assistance, refer to %s. The PDO error was %s',
                    'https://cloud.google.com/sql/docs/mysql/connect-external-app',
                    $e->getMessage()
                ),
                (int) $e->getCode(),
                $e
            );
        }

        return $conn;
    }
}

Troubleshoot

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

• Debugging connection issues
• Known connectivity errors
• Troubleshooting Cloud SQL Auth Proxy connection
• Common connection issues

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 from a local machine or Compute Engine.
• Learn about configuring IP connectivity.
• Learn about connecting with other MySQL tools.
• Learn about MySQL connectors.
• Learn about the Cloud SQL Auth Proxy.
• Learn about options for support.