For information about connecting a sqlcmd client to a Cloud SQL instance using public IP, see Connecting sqlcmd Client Using IP Addresses.
For more information about how the proxy works, see About the Cloud SQL Proxy.
Before you begin
Before you can connect a sqlcmd to a Cloud SQL instance, you must have:
Enabled the Cloud SQL Admin API
- Created a Cloud SQL instance, including configuring the default user.
For more information about creating instances, see Creating Instances.
For more information about configuring the default user, see Configuring the default user account.
- Installed the sqlcmd client.
- Installed and initialized the Cloud SDK.
- If needed, installed the Docker client.
Install the Cloud SQL Proxy
Linux 64-bit
- Download the proxy:
wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
- Make the proxy executable:
chmod +x cloud_sql_proxy
Linux 32-bit
- Download the proxy:
wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
- Make the proxy executable:
chmod +x cloud_sql_proxy
macOS 64-bit
- Download the proxy:
curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64
- Make the proxy executable:
chmod +x cloud_sql_proxy
macOS 32-bit
- Download the proxy:
curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
- Make the proxy executable:
chmod +x cloud_sql_proxy
Windows 64-bit
Right-click https://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe and select Save Link As to download the proxy. Rename the file tocloud_sql_proxy.exe
.
Windows 32-bit
Right-click https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe and select Save Link As to download the proxy. Rename the file tocloud_sql_proxy.exe
.
Docker proxy image
For convenience, the Cloud SQL team maintains several container images that contain the Cloud SQL Proxy for use by our customers. For more information about these images, see the Cloud SQL Proxy repo on GitHub. You can pull the latest image to your local machine using Docker with the following command:docker pull gcr.io/cloudsql-docker/gce-proxy:1.19.1
Other OS
For other operating systems not included here, you can compile the proxy from source.Create a Service Account
- Go to the Service accounts page of the Google Cloud Console.
- Select the project that contains your Cloud SQL instance.
- Click Create service account.
- In the Create service account dialog, provide a descriptive name for the service account.
-
For Role, select one of the following roles:
- Cloud SQL > Cloud SQL Client
- Cloud SQL > Cloud SQL Editor
- Cloud SQL > Cloud SQL Admin
- Change the Service account ID to a unique, recognizable value.
-
Click Furnish a new private key and confirm that the key type is
JSON
. -
Click Create.
The private key file is downloaded to your machine. You can move it to another location. Keep the key file secure.
Start the Cloud SQL Proxy
You can start the proxy using TCP sockets or the Docker proxy image.
TCP sockets
Copy your instance connection name from the Instance details page.
For example:
myproject:myregion:myinstance
.- If the instance has both public and private IP configured, and you want the
proxy to use the private IP address, you must provide the following option
when you start the proxy:
-ip_address_types=PRIVATE
- If you are using a service account to authenticate the proxy, note the location on your client machine of the private key file that was created when you created the service account.
- Start the proxy.
Some possible proxy invocation strings:
- Using Cloud SDK authentication:
./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:1433
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 -instances=<INSTANCE_CONNECTION_NAME>=tcp:1433 \ -credential_file=<PATH_TO_KEY_FILE> &
For more information about proxy options, see Options for authenticating the proxy and Options for specifying instances.
- Using Cloud SDK authentication:
Docker proxy image
To run the Cloud SQL Proxy in a Docker container, use the Proxy Docker image available from the Google Container Registry.
You can start the proxy using either TCP sockets or Unix sockets, with the commands shown below.
Depending on your language and environment, you can start the 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
docker run -d \\ -v PATH_TO_KEY_FILE:/config \\ -p 127.0.0.1:1433:1433 \\ gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy \\ -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:1433 -credential_file=/config
If you are using the credentials provided by your Compute Engine instance,
do not include the credential_file
parameter and the
-v PATH_TO_KEY_FILE:/config
line.
Always specify 127.0.0.1
prefix in -p so that the 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
docker run -d -v /cloudsql:/cloudsql \\ -v PATH_TO_KEY_FILE:/config \\ gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy -dir=/cloudsql \\ -instances=INSTANCE_CONNECTION_NAME -credential_file=/config
If you are using the credentials provided by your Compute Engine instance,
do not include the credential_file
parameter and the
-v PATH_TO_KEY_FILE:/config
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 use Compute Engine metadata to dynamically determine the instances to connect to. Learn more about the proxy parameters.
Connect to the Cloud SQL Proxy
The connection string you use depends on whether you started the proxy using a TCP socket or or Docker.
TCP sockets
- Start the sqlcmd client:
sqlcmd -S tcp:127.0.0.1,1433 -U <USER_NAME> -P <PASSWORD>
When you connect using TCP sockets, the proxy is accessed through
127.0.0.1
. - If prompted, enter the password.
- The sqlcmd prompt appears.
Need help? For help troubleshooting the proxy, see Troubleshooting Cloud SQL Proxy connections. Or, see our Cloud SQL Support page.
Language-specific information and examples
You can connect to the proxy from any language that enables you to connect to a TCP socket. Below are a few sample proxy invocation and connection statements to help you understand how they work together in your application.
Connecting with TCP
Proxy invocation statement:
./cloud_sql_proxy -instances=[INSTANCE_CONNECTION_NAME]=tcp:1433 &
Python
To see this snippet in the context of a web application, view the README on GitHub.
Java
To see this snippet in the context of a web application, view the README on GitHub.
Node.js
To see this snippet in the context of a web application, view the README on GitHub.
Go
To see this snippet in the context of a web application, view the README on GitHub.
C#
To see this snippet in the context of a web application, view the README on GitHub.
Ruby
To see this snippet in the context of a web application, view the README on GitHub.
PHP
To see this snippet in the context of a web application, view the README on GitHub.
What's next
- Learn more about the proxy.
- Get help troubleshooting connection issues for the Cloud SQL Proxy.
- Learn about using the proxy with private IP.
- Learn about the two levels of access control for Cloud SQL instances.
- Create users and databases.
- Learn about connecting to your instance from your application.
- Learn about options for support.