This page describes how to connect to your Cloud SQL instance using theCloud SQL Auth Proxy.

For more information about how the Cloud SQL Auth Proxy works, seeAbout the Cloud SQL Auth Proxy.

Overview

Using theCloud SQL Auth Proxy is therecommended method for connecting to a Cloud SQL instance. The Cloud SQL Auth Proxy:

• Works with both public and private IP endpoints
• Validates connections using credentials for a user or service account
• Wraps the connection in a SSL/TLS layer that's authorized for a Cloud SQLinstance

Some Google Cloud services and applications use the Cloud SQL Auth Proxy to provideconnections for public IP paths with encryption and authorization, including:

• App Engine standard environment
• App Engine flexible environment
• Cloud Run

Applications running inGoogle Kubernetes Engine can connect using the Cloud SQL Auth Proxy.

See theQuickstart for usingthe Cloud SQL Auth Proxy for a basic introduction to its usage.

You can also connect, with or without the Cloud SQL Auth Proxy, using a sqlcmdclientfrom a local machine or Compute Engine.

Before you begin

Before you can connect to a Cloud SQL instance, do the following:

1. • For a user or service account, make sure the account has the Cloud SQL Client role. This role contains thecloudsql.instances.connect permission, which authorizes a principal to connect to all Cloud SQL instances in a project.

     Go to the IAM page

   • You can optionally include anIAM condition in the IAM policy binding that grants the account permission to connect only to one specific Cloud SQL instance.

2. Enable the Cloud SQL Admin API.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

   Enable the API

3. Install and initialize thegcloud CLI.
4. Optional. Install theCloud SQL Auth Proxy Docker client.

Download the Cloud SQL Auth Proxy

docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.20.0

Start the Cloud SQL Auth Proxy

You can start the Cloud SQL Auth Proxy using TCP sockets or the Cloud SQL Auth Proxy Docker image. The Cloud SQL Auth Proxy binary connectsto one or more Cloud SQL instances specified on the command line, and opens a local connectionas a TCP socket. Other applications and services, such as your application code ordatabase management client tools, can connect to Cloud SQL instancesthrough that TCP socket connection.

./cloud-sql-proxy--address0.0.0.0--port1234INSTANCE_CONNECTION_NAME

gcloudsqlinstancesdescribeINSTANCE_NAME

dockerrun-d\\-vPATH_TO_KEY_FILE:/path/to/service-account-key.json\\-p127.0.0.1:1433:1433\\gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.20.0\\--address0.0.0.0--port1433\\--credentials-file/path/to/service-account-key.jsonINSTANCE_CONNECTION_NAME

dockerrun-d-v/cloudsql:/cloudsql\\-vPATH_TO_KEY_FILE:/path/to/service-account-key.json\\gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.20.0--unix-socket=/cloudsql\\--credentials-file/path/to/service-account-key.jsonINSTANCE_CONNECTION_NAME

-v /mnt/stateful_partition/cloudsql:/cloudsql

Connect with the sqlcmd client

The connection string you use depends on whether you started the Cloud SQL Auth Proxy using a TCP socket orDocker.

Need help? For help troubleshooting the proxy, seeTroubleshooting Cloud SQL Auth Proxy connections, or see ourCloud SQL Support page.

Connect with an application

You can connect to the Cloud SQL Auth Proxy from any language that enables you to connect to aTCP socket. Below are some code snippets from complete examples on GitHub to help you understandhow they work together in your application.

./cloud-sql-proxyINSTANCE_CONNECTION_NAME&

importosimportsqlalchemydefconnect_tcp_socket()->sqlalchemy.engine.base.Engine:"""Initializes a TCP connection pool for a Cloud SQL instance of SQL Server."""# 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. 1433pool=sqlalchemy.create_engine(# Equivalent URL:# mssql+pytds://<db_user>:<db_pass>@<db_host>:<db_port>/<db_name>sqlalchemy.engine.url.URL.create(drivername="mssql+pytds",username=db_user,password=db_pass,database=db_name,host=db_host,port=db_port,),# ...)returnpool

importcom.zaxxer.hikari.HikariConfig;importcom.zaxxer.hikari.HikariDataSource;importjavax.sql.DataSource;publicclassTcpConnectionPoolFactoryextendsConnectionPoolFactory{// 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.privatestaticfinalStringDB_USER=System.getenv("DB_USER");privatestaticfinalStringDB_PASS=System.getenv("DB_PASS");privatestaticfinalStringDB_NAME=System.getenv("DB_NAME");privatestaticfinalStringINSTANCE_HOST=System.getenv("INSTANCE_HOST");privatestaticfinalStringDB_PORT=System.getenv("DB_PORT");publicstaticDataSourcecreateConnectionPool(){// The configuration object specifies behaviors for the connection pool.HikariConfigconfig=newHikariConfig();// Configure which instance and what database user to connect with.config.setJdbcUrl(String.format("jdbc:sqlserver://%s:%s;databaseName=%s",INSTANCE_HOST,DB_PORT,DB_NAME));config.setUsername(DB_USER);// e.g. "root", "sqlserver"config.setPassword(DB_PASS);// e.g. "my-password"// ... Specify additional connection properties here.// ...// Initialize the connection pool using the configuration object.returnnewHikariDataSource(config);}}

constmssql=require('mssql');// createTcpPool initializes a TCP connection pool for a Cloud SQL// instance of SQL Server.constcreateTcpPool=asyncconfig=>{// 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.constdbConfig={server:process.env.INSTANCE_HOST,// e.g. '127.0.0.1'port:parseInt(process.env.DB_PORT),// e.g. 1433user: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'options:{trustServerCertificate:true,},// ... Specify additional properties here....config,};// Establish a connection to the database.returnmssql.connect(dbConfig);};

packagecloudsqlimport("database/sql""fmt""log""os""strings"_"github.com/denisenkom/go-mssqldb")// connectTCPSocket initializes a TCP connection pool for a Cloud SQL// instance of SQL Server.funcconnectTCPSocket()(*sql.DB,error){mustGetenv:=func(kstring)string{v:=os.Getenv(k)ifv==""{log.Fatalf("Fatal Error in connect_tcp.go: %s environment variable not set.\n",k)}returnv}// 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'dbTCPHost=mustGetenv("INSTANCE_HOST")// e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)dbPort=mustGetenv("DB_PORT")// e.g. '1433'dbName=mustGetenv("DB_NAME")// e.g. 'my-database')dbURI:=fmt.Sprintf("server=%s;user id=%s;password=%s;port=%s;database=%s;",dbTCPHost,dbUser,dbPwd,dbPort,dbName)// dbPool is the pool of database connections.dbPool,err:=sql.Open("sqlserver",dbURI)iferr!=nil{returnnil,fmt.Errorf("sql.Open: %w",err)}// ...returndbPool,nil}

usingMicrosoft.Data.SqlClient;usingSystem;namespaceCloudSql{publicclassSqlServerTcp{publicstaticSqlConnectionStringBuilderNewSqlServerTCPConnectionString(){// Equivalent connection string:// "User Id=<DB_USER>;Password=<DB_PASS>;Server=<INSTANCE_HOST>;Database=<DB_NAME>;"varconnectionString=newSqlConnectionStringBuilder(){// 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.DataSource=Environment.GetEnvironmentVariable("INSTANCE_HOST"),// e.g. '127.0.0.1'// Set Host to 'cloudsql' when deploying to App Engine Flexible environmentUserID=Environment.GetEnvironmentVariable("DB_USER"),// e.g. 'my-db-user'Password=Environment.GetEnvironmentVariable("DB_PASS"),// e.g. 'my-db-password'InitialCatalog=Environment.GetEnvironmentVariable("DB_NAME"),// e.g. 'my-database'// The Cloud SQL proxy provides encryption between the proxy and instanceEncrypt=false,};connectionString.Pooling=true;// Specify additional properties here.returnconnectionString;}}}

tcp:&tcpadapter:sqlserver# 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 Flexport:<%=ENV.fetch("DB_PORT"){1433}%>

namespace Google\Cloud\Samples\CloudSQL\SQLServer;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(                'sqlsrv:server=%s;Database=%s',                $instanceHost,                $dbName            );            // 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/sqlserver/connect-external-app',                    $e->getMessage()                ),                (int) $e->getCode(),                $e            );        }        return $conn;    }}

Additional topics

Cloud SQL Auth Proxy command-line arguments

The examples above cover the most common use cases, but the Cloud SQL Auth Proxyalso has other configuration options that can be set with command-linearguments. For help on command-line arguments, use the--help flagto view the latest documentation:

./cloud-sql-proxy--help

See theREADME on the Cloud SQL Auth Proxy GitHub repositoryfor additional examples of how to use Cloud SQL Auth Proxy command-line options.

Options for authenticating the Cloud SQL Auth Proxy

All of these options use anINSTANCE_CONNECTION_NAME asthe connection string to identify a Cloud SQL instance. You can find theINSTANCE_CONNECTION_NAME on theOverview page for yourinstance in theGoogle Cloud console. or by running thefollowing command:

gcloud sql instances describe --projectPROJECT_IDINSTANCE_CONNECTION_NAME.

For example:gcloud sql instances describe --project myproject myinstance .

Some of these options use a JSON credentials file that includes the RSA privatekey for the account. For instructions on creating a JSON credentials file for aservice account, seeCreating a service account.

The Cloud SQL Auth Proxy provides several alternatives for authentication, depending onyour environment. The Cloud SQL Auth Proxy checks for each of the following items, in the followingorder, using the first one it finds to attempt to authenticate:

1. Credentials supplied by the credentials-file flag.

   Use aservice account to create and download the associated JSON file, and set the--credentials-file flag to the path of the file when you start the Cloud SQL Auth Proxy. The service account must have therequired permissions for the Cloud SQL instance.

   To use this option on the command-line, invoke thecloud-sql-proxy command with the--credentials-file flag set to the path and filename of a JSON credential file. The path can be absolute, or relative to the current working directory. For example:

   ./cloud-sql-proxy--credentials-filePATH_TO_KEY_FILE\INSTANCE_CONNECTION_NAME

   For detailed instructions about adding IAM roles to a service account, seeGranting Roles to Service Accounts.

   For more information about the roles Cloud SQL supports, seeIAM roles for Cloud SQL.

2. Credentials supplied by an access token.

   Create an access token and invoke thecloud-sql-proxy command with the--token flag set to an OAuth 2.0 access token. For example:

   ./cloud-sql-proxy--tokenACCESS_TOKEN\INSTANCE_CONNECTION_NAME

3. Credentials supplied by an environment variable.

   This option is similar to using the--credentials-file flag, except you specify the JSON credential file you set in theGOOGLE_APPLICATION_CREDENTIALS environment variable instead of using the--credentials-file command-line argument.

4. Credentials from an authenticatedgcloud CLI client.

   If you have installed thegcloud CLI and have authenticated with your personal account, the Cloud SQL Auth Proxy can use the same account credentials. This method is especially helpful for getting a development environment up and running.

   To enable the Cloud SQL Auth Proxy to use your gcloud CLI credentials, use the following command to authenticate the gcloud CLI:

   gcloudauthapplication-defaultlogin

5. Credentials associated with the Compute Engine instance.

   If you are connecting to Cloud SQL from a Compute Engine instance, theCloud SQL Auth Proxy can use the service account associated with the Compute Engine instance.If the service account has therequired permissionsfor the Cloud SQL instance, the Cloud SQL Auth Proxy authenticates successfully.

   If the Compute Engine instance is in the same project as the Cloud SQLinstance, the default service account for the Compute Engine instance has thenecessary permissions for authenticating the Cloud SQL Auth Proxy.If the two instances are in different projects, you must add the Compute Engineinstance's service account to the project containing the Cloud SQLinstance.

6. Environment's default service account

   If the Cloud SQL Auth Proxy cannot find credentials in any of the places covered earlier, itfollows the logic documented inSetting Up Authentication for Server to Server ProductionApplications. Some environment (such as Compute Engine, App Engine, and others) provide adefault service account that your application can use to authenticate by default. Ifyou use a default service account, it must have the permissions outlined inroles and permissionsFor more information about Google Cloud's approach to authentication, seeAuthentication overview.

Create a service account

Configure the service account to have either of the following access scopes:

• https://www.googleapis.com/auth/sqlservice.admin
• https://www.googleapis.com/auth/cloud-platform

1. In the Google Cloud console, go to theService accounts page.

   Go to Service accounts

2. Select the project that contains your Cloud SQL instance.
3. ClickCreate service account.
4. In theService account name field, enter a descriptive name for the service account.
5. Change theService account ID to a unique, recognizable value and then clickCreate and continue.
6. Click theSelect a role field and select one of the following roles:
   • Cloud SQL > Cloud SQL Client
   • Cloud SQL > Cloud SQL Editor
   • Cloud SQL > Cloud SQL Admin

   Note: To create a service account with the required permissions, you must haveresourcemanager.projects.setIamPolicy permission. This permission is included in the Project Owner, Project IAM Admin, and Organization Administrator roles.
   You must also have enabled the Cloud SQL Admin API. If you are using the legacy project roles (Viewer, Editor, Owner), the service account must have at least the Editor role.

7. ClickDone to finish creating the service account.
8. Click the action menu for your new service account and then selectManage keys.
9. Click theAdd key drop-down menu and then clickCreate new key.
10. Confirm that the key type is JSON and then clickCreate.

    The private key file is downloaded to your machine. You can move it to another location. Keep the key file secure.

Use the Cloud SQL Auth Proxy with private IP

To connect to a Cloud SQL instance using private IP, the Cloud SQL Auth Proxymust be on a resource with access to the same VPC network as theinstance.

The Cloud SQL Auth Proxy uses IP to establish a connection with your Cloud SQL instance.By default, the Cloud SQL Auth Proxy attempts to connect using a public IPv4 address.

If your Cloud SQL instance has only private IP or the instance has bothpublic and private IP configured, and you want the Cloud SQL Auth Proxy to use the privateIP address, then you must provide the following option when you start the Cloud SQL Auth Proxy:

--private-ip

You can use the Cloud SQL Auth Proxy to connect to a Cloud SQL primary instancethat's configured with a write endpoint. A write endpoint is a global domain nameservice (DNS) name that you can use for connections instead of an IP addressforadvanced disaster recovery (DR) such as performing a replica failoveror a switchover operation. If a replica failover or switchover operation occursfor the primary instance, then the Cloud SQL Auth Proxy detects changes to the DNSrecord automatically.

For more information on how to use the Cloud SQL Auth Proxy to connect to a write endpoint,seeConnect database clients to instances using the Cloud SQL Auth Proxy or Cloud SQL Language Connectors.

Use the Cloud SQL Auth Proxy with instances that have Private Service Connect enabled

You can use the Cloud SQL Auth Proxy to connect to a Cloud SQL instance with Private Service Connect enabled.

The Cloud SQL Auth Proxy is a connector that provides secure access to this instance without a need for authorized networks or for configuring SSL.

To allow Cloud SQL Auth Proxy client connections, you must set up aDNS record which matches the recommendedDNS name that's provided for the instance. The DNS record is a mapping between a DNS resource and a domain name.

For more information about using the Cloud SQL Auth Proxy to connect to instances with Private Service Connect enabled, seeConnect using the Cloud SQL Auth Proxy.

Run the Cloud SQL Auth Proxy in a separate process

Running the Cloud SQL Auth Proxy in a separate Cloud Shell terminal process can be useful, to avoidmixing its console output with output from other programs. Use the syntaxshown below to invoke the Cloud SQL Auth Proxy in a separate process.

./cloud-sql-proxyINSTANCE_CONNECTION_NAME--credentials-filePATH_TO_KEY_FILE&

Start-Process--filepath "cloud-sql-proxy.exe"--ArgumentList "--credentials-filePATH_TO_KEY_FILEINSTANCE_CONNECTION_NAME"

Run the Cloud SQL Auth Proxy in a Docker container

To run the Cloud SQL Auth Proxy in a Docker container, use the Cloud SQL Auth Proxy Dockerimage available from theGoogle Container Registry.You can install the Cloud SQL Auth Proxy Docker image using the following command:

dockerpullgcr.io/cloud-sql-connectors/cloud-sql-proxy:2.20.0

You can start the Cloud SQL Auth Proxy using either TCP sockets or Unix sockets, with thecommands shown below.

dockerrun-d\-vPATH_TO_KEY_FILE:/path/to/service-account-key.json\-p127.0.0.1:1433:1433\gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.20.0\--address0.0.0.0\--credentials-file/path/to/service-account-key.json\INSTANCE_CONNECTION_NAME

dockerrun-d\-v/PATH_TO_HOST_TARGET:/PATH_TO_GUEST_TARGET\-vPATH_TO_KEY_FILE:/path/to/service-account-key.json\gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.20.0--unix-socket/cloudsql\--credentials-file/path/to/service-account-key.json/PATH_TO_KEY_FILE\INSTANCE_CONNECTION_NAME

v/mnt/stateful_partition/cloudsql:/cloudsql

For production workloads, the Cloud SQL Auth Proxy doesn't currently provide built-insupport for running as a Windows service, but third-party service managers canbe used to run it as a service. For example, you can useNSSMto configure the Cloud SQL Auth Proxy as a Windows service, and NSSM monitors theCloud SQL Auth Proxy and restarts it automatically if it stops responding. See theNSSM documentation for more information.

Enable the use of the Cloud SQL Auth Proxy in Cloud SQL usingConnectorEnforcement.

If you're using aPrivate Service Connect-enabled instance, then there's a limitation. If the instance has connector enforcement enabled, then you can't create read replicas for the instance. Similarly, if the instance has read replicas, then you can't enable connector enforcement for the instance.

gcloudsqlinstancespatchINSTANCE_NAME\--connector-enforcementREQUIRED

PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

{  "settings": {                         "connectorEnforcement": "REQUIRED"      }                                             }

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id" | Select-Object -Expand Content

{  "kind": "sql#operation",  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-16T02:32:12.281Z",  "operationType": "UPDATE",  "name": "operation-id",  "targetId": "instance-id",  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",  "targetProject": "project-id"}

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

{  "settings": {    "connectorEnforcement": "REQUIRED"  }}

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id" | Select-Object -Expand Content

{  "kind": "sql#operation",  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-16T02:32:12.281Z",  "operationType": "UPDATE",  "name": "operation-id",  "targetId": "instance-id",  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",  "targetProject": "project-id"}

Tips for working with Cloud SQL Auth Proxy

Use the Cloud SQL Auth Proxy to connect to multiple instances

You can use one local Cloud SQL Auth Proxy client to connect to multiple Cloud SQLinstances. The way you do this depends on whether you are using Unix socketsor TCP.

# Start the Cloud SQL Auth Proxy to connect to two different Cloud SQL instances.# Give the Cloud SQL Auth Proxy a unique port on your machine to use for each Cloud SQL instance../cloud-sql-proxy"myProject:us-central1:myInstance?port=1433"\"myProject:us-central1:myInstance2?port=1234"# Connect to "myInstance" using port 1433 on your machine:sqlcmd-UmyUser-S"127.0.0.1,1433"# Connect to "myInstance2" using port 1234 on your machine:sqlcmd-UmyUser-S"127.0.0.1,1234"

Troubleshoot Cloud SQL Auth Proxy connections

The Cloud SQL Auth Proxy Docker image is based on a specific version of the Cloud SQL Auth Proxy.When a new version of the Cloud SQL Auth Proxy becomes available, pull the newversion of the Cloud SQL Auth Proxy Docker image to keep your environment up to date. Youcan see the current version of the Cloud SQL Auth Proxy by checking theCloud SQL Auth Proxy GitHub releases page.

If you are having trouble connecting to your Cloud SQL instance usingthe Cloud SQL Auth Proxy, here are a few things to try to find what's causing theproblem.

• Check the Cloud SQL Auth Proxy output.

  Often, the Cloud SQL Auth Proxy output can help you determine the source of the problemand how to solve it. Pipe the output to a file, or watch the Cloud Shell terminal whereyou started the Cloud SQL Auth Proxy.

• If you are getting a403 notAuthorized error, and you are using a serviceaccount to authenticate the Cloud SQL Auth Proxy, make sure the service account has thecorrectpermissions.

  You can check the service account by searching for its ID on theIAM page. It must havethecloudsql.instances.connect permission. TheCloud SQL Admin,Client andEditor predefined roles have this permission.

• If you are connecting from App Engine and are getting a403 notAuthorized error, check theapp.yaml valuecloud_sql_instances for a misspelled or incorrect instance connection name.Instance connection names are always in the formatPROJECT:REGION:INSTANCE.

  Also, check that the App Engine service account(for example, $PROJECT_ID@appspot.gserviceaccount.com) hasthe Cloud SQL Client IAM role.

  If the App Engine service lives in one project (project A) and the databaselives in another (project B), this error means the App Engine serviceaccount has not been given the Cloud SQL Client IAM rolein the project with the database (project B).

• Make sure to enable the Cloud SQL Admin API.

  If it is not, you see output likeError 403: Access NotConfigured in your Cloud SQL Auth Proxy logs.

• If you are including multiple instances in your instances list, make sureyou are using a comma as a delimiter, with no spaces. If you are using TCP,make sure you are specifying different ports for each instance.

• If you are connecting using UNIX sockets, confirm that the sockets werecreated by listing the directory you provided when you started the Cloud SQL Auth Proxy.

• If you have an outbound firewall policy, make sure it allows connectionsto port 3307 on the target Cloud SQL instance.

  Note: The Cloud SQL Auth Proxy uses 3307 to connect to the Cloud SQL Auth Proxy server.Port1433 is the default port for the SQL Server protocolover a direct TCP connection (not using the Cloud SQL Auth Proxy).

• You can confirm that the Cloud SQL Auth Proxy started correctly by looking in the logsunder theOperations > Logging > Logs explorer section of theGoogle Cloud console. A successful operation looks like the following:

  2021/06/1415:47:56Listeningon/cloudsql/$PROJECT_ID:$REGION:$INSTANCE_NAME/1433for$PROJECT_ID:$REGION:$INSTANCE_NAME2021/06/1415:47:56Readyfornewconnections

• Quota issues: When the Cloud SQL Admin API quota is breached, theCloud SQL Auth Proxy starts up with the following error message:

  Therewasaproblemwhenparsingainstanceconfigurationbutignoringduetotheconfiguration.Error:googleapi:Error429:Quotaexceededforquotametric'Queries'andlimit'Queries per minute per user'ofservice'sqladmin.googleapis.com'forconsumer'project_number:$PROJECT_ID.,rateLimitExceeded

  Once an application connects to the proxy, the proxy reports the followingerror:

  failedtorefreshtheephemeralcertificatefor$INSTANCE_CONNECTION_NAME:googleapi:Error429:Quotaexceededforquotametric'Queries'andlimit'Queries per minute per user'ofservice'sqladmin.googleapis.com'forconsumer'project_number:$PROJECT_ID.,rateLimitExceeded

  Solution: Either identify the source of the quota problem, for example, anapplication is misusing the connector and unnecessarily creating newconnections, or contact support to request an increase to the Cloud SQLAdmin API quota. If the quota error appears on startup, you must re-deploy theapplication to restart the proxy. If the quota error appears after startup, are-deploy is unnecessary.

What's next

• Learn more about theCloud SQL Auth Proxy.
• Learn more aboutIdentity and Access Management (IAM).
• Learn more aboutService Accounts.
• Learn about thetwo levels of access control for Cloud SQL instances.
• Createusers anddatabases.
• Learn about connecting to your instance from your application.
• Learn aboutoptions for support.