This page describes how to connect a sqlcmd client to your Cloud SQL instance, from a client machine running Linux or a Compute Engine Linux instance, using the Cloud SQL Auth Proxy Docker image. ## Before you begin You must have: - Installed the [gcloud CLI](https://docs.cloud.google.com/sdk/gcloud.md.txt). [Learn more](https://docs.cloud.google.com/sdk/downloads). - Authorized the gcloud CLI. [Learn more](https://docs.cloud.google.com/sdk/docs/authenticate.md.txt). - Set the default project for the gcloud CLI. [Learn more](https://docs.cloud.google.com/sdk/docs/managing-properties#setting_properties). - Configured a database user on your Cloud SQL instance. [Learn more](https://docs.cloud.google.com/sql/docs/sqlserver/users.md.txt). ### Required roles To get the permissions that you need to connect to a Cloud SQL instance using the Cloud SQL Auth Proxy Docker image, ask your administrator to grant you the following IAM roles on your project: - To connect using the Cloud SQL Auth Proxy: [Cloud SQL Client](https://docs.cloud.google.com/iam/docs/roles-permissions/cloudsql.md.txt#cloudsql.client) (`roles/cloudsql.client`) - If you use IAM database authentication: [Cloud SQL Instance User](https://docs.cloud.google.com/iam/docs/roles-permissions/cloudsql.md.txt#cloudsql.instanceUser) (`roles/cloudsql.instanceUser`) For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt). You might also be able to get the required permissions through [custom roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined). ## Connect a sqlcmd client using the Cloud SQL Auth Proxy Docker image **To connect using the Cloud SQL Auth Proxy Docker image:** 1. Enable the Cloud SQL Admin API, if it is not already enabled. **Roles required to enable APIs** To enable APIs, you need the `serviceusage.services.enable` permission. If you created the project, then you likely already have this permission through the Owner role (`roles/owner`). Otherwise, you can get this permission through the Service Usage Admin role (`roles/serviceusage.serviceUsageAdmin`). [Learn how to grant roles](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt). [Enable the API](https://console.cloud.google.com/apis/enableflow?apiid=sqladmin&redirect=https://console.cloud.google.com) 2. If you are using a Compute Engine instance, prepare the instance: 1. Display the Compute Engine instance properties: ```bash gcloud compute instances describe [GCE_INSTANCE_NAME] ``` 2. Verify the [service account](https://docs.cloud.google.com/compute/docs/access/service-accounts.md.txt) and access scopes configured on the instance: - Ensure that the service account attached to the VM has the **Cloud SQL Client** (`roles/cloudsql.client`) predefined Identity and Access Management (IAM) role to connect using the Cloud SQL Auth Proxy or the Cloud SQL Admin API. If you use IAM database authentication, also grant the **Cloud SQL Instance User** (`roles/cloudsql.instanceUser`) role. For more information about predefined roles, see [Required roles](https://docs.cloud.google.com/sql/docs/sqlserver/connect-docker.md.txt#required-roles). - Ensure that the VM access scope is set to `cloud-platform` (`https://www.googleapis.com/auth/cloud-platform`, or **Allow full access to all Cloud APIs** in the Google Cloud console). Access scopes are a legacy method for specifying authorization for a VM and only set the maximum OAuth authorization scope for requests. Manage access control through predefined IAM roles instead of access scopes. If your Compute Engine instance doesn't have the required service account roles or access scope, you can update the instance. For more information about changing the service account and access scopes on a VM, see [Change the attached service account](https://docs.cloud.google.com/compute/docs/instances/change-service-account.md.txt#changeserviceaccountandscopes) in the Compute Engine documentation. 3. Open a terminal connection to the instance, using the instructions at [Connecting to Linux instances](https://docs.cloud.google.com/compute/docs/instances/connecting-to-instance). 3. Install the sqlcmd client on the Compute Engine instance or client machine, if it is not already installed. ### Debian/Ubuntu For Debian/Ubuntu, [install the applicable SQL Server command-line tools](https://docs.microsoft.com/en-us/sql/linux/sql-server-linux-setup-tools?view=sql-server-2017#ubuntu). ### CentOS/RHEL For CentOS/RHEL, [install the applicable SQL Server command-line tools](https://docs.microsoft.com/en-us/sql/linux/sql-server-linux-setup-tools?view=sql-server-2017#install-tools-on-rhel-7). ### openSUSE For openSUSE, [install the applicable SQL Server command-line tools](https://docs.microsoft.com/en-us/sql/linux/quickstart-install-connect-suse?view=sql-server-2017#tools). ### Other platforms See the [landing page](https://docs.microsoft.com/en-us/sql/database-engine/install-windows/install-sql-server-database-engine?view=sql-server-2017) for installing SQL Server, as well as the [SQL Server downloads page](https://www.microsoft.com/en-us/sql-server/sql-server-downloads). 4. If needed, install the Docker client: ```bash curl https://get.docker.com | sh sudo usermod -aG docker $USER ``` If you are using a [container-optimized](https://docs.cloud.google.com/compute/docs/containers/vm-image) Compute Engine instance, it already has the Docker client installed. 5. Install the Cloud SQL Auth Proxy Docker image from the [Google Container Registry](https://docs.cloud.google.com/container-registry). ```bash docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.28.0 ``` 6. If you are running the Cloud SQL Auth Proxy Docker image on a local machine (not a Compute Engine instance), or if the service account attached to your Compute Engine instance doesn't have the required IAM roles and access scope, create a Google Cloud service account. > [!NOTE] > **Note:** If you are connecting from a Compute Engine VM, we recommend that you use the [service account attached to the VM](https://docs.cloud.google.com/compute/docs/access/service-accounts.md.txt) instead of a service account key file: > - Grant the attached service account the **Cloud SQL Client** (`roles/cloudsql.client`) predefined IAM role to connect using the Cloud SQL Auth Proxy or the Cloud SQL Admin API, and the **Cloud SQL Instance User** (`roles/cloudsql.instanceUser`) role if you use IAM database authentication. For more information about predefined roles, see [Cloud SQL IAM roles](https://docs.cloud.google.com/sql/docs/sqlserver/iam-roles.md.txt). > - Set the VM access scope to `cloud-platform` (`https://www.googleapis.com/auth/cloud-platform`, or **Allow full access to all Cloud APIs** in the Google Cloud console) and use IAM roles to control permissions. Access scopes are a legacy method for specifying authorization for a VM and only set the maximum OAuth authorization scope. To update an existing VM, see [Change the attached service account](https://docs.cloud.google.com/compute/docs/instances/change-service-account.md.txt#changeserviceaccountandscopes). 1. In the Google Cloud console, go to the **Service accounts** page. [Go to Service accounts](https://console.cloud.google.com/iam-admin/serviceaccounts/) 2. Select the project that contains your Cloud SQL instance. 3. Click **Create service account**. 4. In the **Service account name** field, enter a descriptive name for the service account. 5. Change the **Service account ID** to a unique, recognizable value and then click **Create and continue**. 6. Click the **Select 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] > **Note:** To create a service account with the required permissions, you must have the `resourcemanager.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. Click **Done** to finish creating the service account. 8. Click the action menu for your new service account and then select **Manage keys**. 9. Click the **Add key** drop-down menu and then click **Create new key**. 10. Confirm that the key type is JSON and then click **Create** . The private key file is downloaded to your machine. You can move it to another location. Keep the key file secure. You provide the path to the key file as "PATH_TO_KEY_FILE" when you start the Cloud SQL Auth Proxy.

7. Go to the Cloud SQL Instances page in the Google Cloud console. [Go to Cloud SQL Instances](https://console.cloud.google.com/sql/instances) 8. Select the instance to open its **Instance details** page and copy the **Instance connection name**. For example: `myproject:us-central1:myinstance`. 9. Start the Cloud SQL Auth Proxy.

### TCP sockets ```bash docker run -d -v PATH_TO_KEY_FILE:/path/to/service-account-key.json -p 127.0.0.1:1433:1433 gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.28.0 --address 0.0.0.0 --port 1433 --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME ``` If you're using the credentials provided by your Compute Engine instance, don't include the `--credentials-file` parameter and the `-v PATH_TO_KEY_FILE:/path/to/service-account-key.json` line. Always specify the `127.0.0.1` prefix in `-p` so that the Cloud SQL Auth Proxy isn't exposed outside the local host. The `--address 0.0.0.0` flag is required to make the port accessible from outside of the Docker container. 10. Start the client:
The connection string you use depends on whether you started the Cloud SQL Auth Proxy using a TCP socket or Docker. ### TCP sockets 1. Start the sqlcmd client: ```bash sqlcmd -S tcp:127.0.0.1,1433 -U USERNAME -P PASSWORD ``` When you connect using TCP sockets, the Cloud SQL Auth Proxy is accessed through `127.0.0.1`.
2. If prompted, enter the password. 3. The sqlcmd prompt appears. Need help? For help troubleshooting the proxy, see [Troubleshooting Cloud SQL Auth Proxy connections](https://docs.cloud.google.com/sql/docs/sqlserver/connect-auth-proxy.md.txt#troubleshooting), or see our [Cloud SQL Support](https://docs.cloud.google.com/sql/docs/sqlserver/getting-support.md.txt) page.
## Keep the Cloud SQL Auth Proxy Docker image up to date 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 new version of the Cloud SQL Auth Proxy Docker image to keep your environment up to date. You can see the current version of the Cloud SQL Auth Proxy by checking the [Cloud SQL Auth Proxy GitHub releases page](https://github.com/GoogleCloudPlatform/cloudsql-proxy/releases). ## What's next
- Learn more about the [Cloud SQL Auth Proxy](https://docs.cloud.google.com/sql/docs/sqlserver/sql-proxy.md.txt). - Get help [troubleshooting connection issues](https://docs.cloud.google.com/sql/docs/sqlserver/connect-admin-proxy#troubleshooting) for the Cloud SQL Auth Proxy. - Create [users](https://docs.cloud.google.com/sql/docs/sqlserver/create-manage-users.md.txt) and [databases](https://docs.cloud.google.com/sql/docs/sqlserver/create-manage-databases.md.txt). - Learn about [options for connecting to your instance from your application](https://docs.cloud.google.com/sql/docs/sqlserver/external-connection-methods). - Learn about [Docker](https://www.docker.com/). - Learn about the [Google Container Registry](https://docs.cloud.google.com/container-registry). - Learn about [options for support](https://docs.cloud.google.com/sql/docs/support).