Connect from Compute Engine

MySQL  |  PostgreSQL  |  SQL Server

This page describes how to use the sqlcmd client, installed on aCompute Engine instance, to connect to Cloud SQL.

You can use private IP, public IP, the Cloud SQL Auth Proxy, or the Cloud SQL Auth Proxy Docker image.

For step-by-step instructions on running a Compute Engine sample webapplication connected to Cloud SQL, see thequickstart for connectingfrom Compute Engine.

Before you begin

This task does not include instructions for setting up yourCompute Engine instance. If you need help with creating andconfiguring a Compute Engine instance, see theCompute Engine documentation.

Ensure your Compute Engine VM has the properscope toconnect using the Cloud SQL Admin API.

Configure the service accountto have either of the following access scopes:

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

Private IP

To connect to Cloud SQL from a Compute Engine instance usingprivate IP, private services access must be set up for your environment and yourCloud SQL instance must be configured to use private IP. YourCompute Engine instance must be in the same region as yourCloud SQL instance, and on the network configured for a private connection.Learn more.

1. Configure your instance to use private IP

Use the instructions inConfiguring Private IP Connectivity.

2. Open a Cloud Shell terminal connection to your Compute Engine instance.

Use the appropriate instructions, depending on the instance's operating system:

If your Compute Engine instance is running either an RHEL or a CentOS public image, SELinux might block the proxy connection. If this happens, you must configure the SELinux feature to allow the connection.

For more information about SELinux for RHEL, see the RHEL documentation. For more information about SELinux for CentOS, seethe CentOS documentation.

3. Install the sqlcmd client on the Compute Engine instance, if it is not already installed.

Debian/Ubuntu

For Debian/Ubuntu, install the applicable SQL Server command-line tools.

CentOS/RHEL

For CentOS/RHEL, install the applicable SQL Server command-line tools.

openSUSE

For openSUSE, install the applicable SQL Server command-line tools.

Other platforms

See the landing page for installing SQL Server, as well as the SQL Server downloads page.

4. Connect with the sqlcmd client.

sqlcmd-SCLOUD_SQL_PRIVATE_IP_ADDRESS-UUSERNAME

You can find the private IP address on theCloud SQL instances page or by running the followinggcloud command:

gcloudsqlinstanceslist

Public IP

To connect using public IP:

1. Add a static IPv4 IP address to the Compute Engine instance, if it does not already have one.

You cannot connect to Compute Engine using IPv6. For information about adding a static IP address, see Reserving a new static external IP address in the Compute Engine documentation.

2. Authorize the static IP address of the Compute Engine instance as a network that can connect to your Cloud SQL instance.

For more information, seeConfiguring access for public IP connections.

Note: Grant authorization only forstatic IP addresses. Ephemeral IP addresses are temporary; granting them access to your instance creates a security risk because they could be reassigned to a different Compute Engine user later.

3. Open a Cloud Shell terminal connection to your Compute Engine instance.

Use the appropriate instructions, depending on the instance's operating system:

If your Compute Engine instance is running either an RHEL or a CentOS public image, SELinux might block the proxy connection. If this happens, you must configure the SELinux feature to allow the connection.

For more information about SELinux for RHEL, see the RHEL documentation. For more information about SELinux for CentOS, seethe CentOS documentation.

4. Install the sqlcmd client on the Compute Engine instance, if it is not already installed.

Debian/Ubuntu

For Debian/Ubuntu, install the applicable SQL Server command-line tools.

CentOS/RHEL

For CentOS/RHEL, install the applicable SQL Server command-line tools.

openSUSE

For openSUSE, install the applicable SQL Server command-line tools.

Other platforms

See the landing page for installing SQL Server, as well as the SQL Server downloads page.

5. Connect with the sqlcmd client.

sqlcmd-SCLOUD_SQL_PUBLIC_IP_ADDR-UUSERNAME

You can find the public IP address on theCloud SQL instances page or by running the followinggcloud command:

gcloudsqlinstanceslist

For an example of how to connect using SSL, seeConnecting with SSL.

6. The sqlcmd prompt appears.

Cloud SQL Auth Proxy

To connect using the Cloud SQL Auth Proxy from Compute Engine:

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

2. Create a service account.

Note:If your Compute Engine instance has either theFull API access orCloud SQL Admin API scope, you can skip this step; you do not need to provide a certificate file when you start the Cloud SQL Auth Proxy.If you are connecting from Compute Engine, make sureyour VM has the properscope to connect using the Cloud SQL Admin API.

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

If the Compute Engine instance is in a different project than the Cloud SQL instance, ensure that its service account has the proper permissions in the project that contains the Cloud SQL instance:

  1. Go to the Compute Engine instances listing in the Google Cloud console.

    Go to the Compute Engine instances listing

  2. If needed, select the project associated with the Compute Engine instance.
  3. Select the Compute Engine instance to display its properties.
  4. In the Compute Engine instance properties, copy the name of the service account.
  5. Go to theIAM & Admin Projects page in the Google Cloud console.

    Go to the IAM & Admin Projects page

  6. Select the project that contains the Cloud SQL instance.
  7. Search for the service account name.

  8. If the service account is already there, and it has a role that includes thecloudsql.instances.connect permission, you can proceed tostep 4.

    TheCloud SQL Client,Cloud SQL Editor andCloud SQL Admin roles all provide the necessary permission, as do the legacyEditor andOwner project roles.

  9. Otherwise, add the service account by clickingAdd.

  10. In theAdd principals dialog, provide the name of the service account and select a role that include thecloudsql.instances.connect permission (any Cloud SQL predefined role other than Viewer will work).

    Alternatively, you can use the basic Editor role by selectingProject > Editor, but theEditor role includes permissions across Google Cloud.

    If you do not see these roles, your Google Cloud user might not have theresourcemanager.projects.setIamPolicy permission. You can check your permissions by going to theIAM page in the Google Cloud console and searching for your user id.

  11. ClickAdd.

    You now see the service account listed with the specified role.

3. Open a terminal connection to your Compute Engine instance.

Use the appropriate instructions, depending on the instance's operating system:

If your Compute Engine instance is running either an RHEL or a CentOS public image, SELinux might block the proxy connection. If this happens, you must configure the SELinux feature to allow the connection.

For more information about SELinux for RHEL, see the RHEL documentation. For more information about SELinux for CentOS, seethe CentOS documentation.

4. Install the sqlcmd client on the Compute Engine instance, if it is not already installed.

Debian/Ubuntu

For Debian/Ubuntu, install the applicable SQL Server command-line tools.

CentOS/RHEL

For CentOS/RHEL, install the applicable SQL Server command-line tools.

openSUSE

For openSUSE, install the applicable SQL Server command-line tools.

Other platforms

See the landing page for installing SQL Server, as well as the SQL Server downloads page.

5. Install the Cloud SQL Auth Proxy on the Compute Engine instance.

Linux 64-bit

  1. Download the Cloud SQL Auth Proxy:
    curl-ocloud-sql-proxyhttps://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.20.0/cloud-sql-proxy.linux.amd64
  2. Make the Cloud SQL Auth Proxy executable:
    chmod+xcloud-sql-proxy

Linux 32-bit

  1. Download the Cloud SQL Auth Proxy:
    curl-ocloud-sql-proxyhttps://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.20.0/cloud-sql-proxy.linux.386
  2. If thecurl command is not found, runsudo apt install curl and repeat the download command.
  3. Make the Cloud SQL Auth Proxy executable:
    chmod+xcloud-sql-proxy

Windows 64-bit

Right-clickhttps://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.20.0/cloud-sql-proxy.x64.exe and selectSave Link As to download the Cloud SQL Auth Proxy. Rename the file tocloud-sql-proxy.exe.

Windows 32-bit

Right-clickhttps://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.20.0/cloud-sql-proxy.x86.exe and selectSave Link As to download the Cloud SQL Auth Proxy. Rename the file tocloud-sql-proxy.exe.

Cloud SQL Auth Proxy Docker image

The Cloud SQL Auth Proxy has different container images, such asdistroless,alpine,andbuster. The default Cloud SQL Auth Proxy container image usesdistroless, whichcontains no shell. If you need a shell or related tools, then download an image based onalpine orbuster.For more information, seeCloud SQL Auth Proxy Container Images.

You can pull the latest image to your local machine using Docker by using the following command:

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

Note: The Cloud SQL Auth Proxy uses a repository that supports thegcr.io domain but serves images from Artifact Registry. For more information, seeTransition from Container Registry.

Other OS

For other operating systems not included here, you cancompile the Cloud SQL Auth Proxy from source.

6. Start the Cloud SQL Auth Proxy.

Note:If your Compute Engine instance has either theFull API access orCloud SQL Admin API scope, you do not need to provide a certificate file when you 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.

Warning: Be careful when binding the Cloud SQL Auth Proxy to an external interface.Anyone with access to that interface/port will be authorized to connect to your instance.

TCP sockets

For TCP connections, the Cloud SQL Auth Proxy listens onlocalhost(127.0.0.1) by default.So, when you specify--port PORT_NUMBER for an instance, the local connectionis at127.0.0.1:PORT_NUMBER.

Alternatively, you can specify a different address for the local connection.For example, here's how to make the Cloud SQL Auth Proxy listen at0.0.0.0:1234 for thelocal connection:

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

  1. Copy yourINSTANCE_CONNECTION_NAME. This can be found on theOverview page for your instance in theGoogle Cloud console or by running the following command:

    gcloudsqlinstancesdescribeINSTANCE_NAME--format='value(connectionName)'

    For example:myproject:myregion:myinstance.

  2. If the instance has both public and private IP configured, and you want the Cloud SQL Auth Proxy to use theprivate IP address, you must provide the following option when you start the Cloud SQL Auth Proxy:
    --private-ip
  3. If you are using a service account to authenticate the Cloud SQL Auth Proxy, note the location on your client machine of the private key file that was created when you createdthe service account.
  4. Start the Cloud SQL Auth Proxy.

    Some possible Cloud SQL Auth Proxy invocation strings:

    • Using Cloud SDK authentication:
      ./cloud-sql-proxy--port1433INSTANCE_CONNECTION_NAME
      The specified port must not already be in use, for example, by a local database server.
    • Using a service account and explicitly including the name of the instance connection (recommended for production environments):
      ./cloud-sql-proxy\--credentials-filePATH_TO_KEY_FILEINSTANCE_CONNECTION_NAME&

    For more information about Cloud SQL Auth Proxy options, seeOptions for authenticating the Cloud SQL Auth Proxy.

Docker

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 start the Cloud SQL Auth Proxy using either TCP sockets or Unix sockets, with thecommands shown below. The 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:

gcloudsqlinstancesdescribeINSTANCE_NAME
.

For example:myproject:myregion:myinstance.

Note: The Cloud SQL Auth Proxy doesn't support listening on Unix domain sockets on Windows.

Depending on your language and environment, you can start the Cloud SQL Auth Proxy using either TCP sockets or Unix sockets. Unix sockets are not supported for applications written in the Java programming language or for the Windows environment.

Using TCP sockets

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

If you're using the credentials provided by your Compute Engine instance, don't include the--credentials-file parameter and the-vPATH_TO_KEY_FILE:/path/to/service-account-key.json line.

Always specify127.0.0.1 prefix in -p so that the Cloud SQL Auth Proxy is not exposed outside the local host. The "0.0.0.0" in the instances parameter is required to make the port accessible from outside of the Docker container.

Using Unix sockets

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

If you're using the credentials provided by your Compute Engine instance, don't include the--credentials-file parameter and the-vPATH_TO_KEY_FILE:/path/to/service-account-key.json line.

If you are using a container optimized image, use a writeable directory in place of/cloudsql, for example:

-v /mnt/stateful_partition/cloudsql:/cloudsql

You can specify more than one instance, separated by commas. You can also useCompute Engine metadata to dynamically determine the instances to connect to.Learn more about the Cloud SQL Auth Proxy parameters.

7. Start the sqlcmd session.

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

TCP sockets

  1. Start the sqlcmd client:
    sqlcmd-Stcp:127.0.0.1,1433-UUSERNAME-PPASSWORD

    When you connect using TCP sockets, the Cloud SQL Auth Proxy is accessed through127.0.0.1.

  2. If prompted, enter the password.
  3. The sqlcmd prompt appears.

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

What's next

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-12-15 UTC.