Connect to Cloud SQL for MySQL from your local computer

MySQL | PostgreSQL | SQL Server

Learn how to deploy a sample app on your Linux, macOS, or Windows-based local computer connected to a MySQL instance by using the Google Cloud console and a client application.

Assuming that you complete all the steps in a timely manner, the resources created in this quickstart typically cost less than one dollar (USD).

Before you begin

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project : Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project : To create a project, you need the Project Creator role ( roles/resourcemanager.projectCreator ), which contains the resourcemanager.projects.create permission. Learn how to grant roles .

Go to project selector

Verify that billing is enabled for your Google Cloud project .

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project : Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project : To create a project, you need the Project Creator role ( roles/resourcemanager.projectCreator ), which contains the resourcemanager.projects.create permission. Learn how to grant roles .

Go to project selector

Verify that billing is enabled for your Google Cloud project .

Verify that you have the permissions required to complete this quickstart .
Enable the Cloud APIs necessary to run a Cloud SQL sample app on your local computer.
Console

Click the Enable APIs button to enable the APIs required for this quickstart.

Enable APIs

This enables the following APIs:
- Cloud SQL Admin API
- IAM API
gcloud

Install the gcloud CLI which provides command-line access to your Google Cloud resources. The gcloud CLI is used to run the gcloud CLI commands presented throughout this quickstart. All the commands are formatted to be run in a Linux/macOS terminal or in Windows Powershell.

Open the terminal and run the following gcloud command:
```
gcloud  
services  
 enable 
  
sqladmin.googleapis.com  
iam.googleapis.com
```
This command enables the following APIs:
- Cloud SQL Admin API
- IAM API

Required roles

To get the permissions that you need to set up Cloud SQL from your local computer, ask your administrator to grant you the following IAM roles on the project that you want to create and connect to:

Create or delete an instance, database, and user: Cloud SQL administrator role ( roles/cloudsql.admin ).
Create or delete an IAM service account: IAM Service Account administrator role ( roles/iam.serviceAccountAdmin ).
Add or remove an IAM policy binding: Project IAM administrator role ( roles/resourcemanager.projectIamAdmin ).
Create, manage and rotate service account keys: Service Account Key Admin (roles/iam.serviceAccountKeyAdmin).

For more information about granting roles, see Manage access to projects, folders, and organizations .

You might also be able to get the required permissions through custom roles or other predefined roles .

Set up Cloud SQL

To create an Cloud SQL instance, do the following:

In the Google Cloud console, go to the Cloud SQL Instances page.

Go to Cloud SQL Instances
Select the MySQL tab and click Create Sandbox instance in the Sandbox box. Alternatively, you can click Create Instance and complete the following steps:

Click Choose MySQL .
Select the Enterprise edition.
Choose the Sandbox preset.

If you're prompted to enable the Compute API , click the Enable API button.
In the Instance info section, enter quickstart-instance as the Instance ID .
Enter a password for the root user. Take note of the password you create, because you'll need it later.
In the Choose region and zonal availability section, select the Single zone option.
Click Create instance .

Create a database

Console

In the Google Cloud console, go to the Cloud SQL Instances page.

Go to Cloud SQL Instances
Select quickstart-instance .
Open the Databases tab.
Click Create database .

In the Create a database dialog box, enter quickstart_db as the name of the database, and optionally the character set and collation.
Click Create .

gcloud

Run the gcloud sql databases create command to create a database.

gcloud  
sql  
databases  
create  
 quickstart_db 
  
--instance = 
 quickstart-instance

Create a user

Console

In the Google Cloud console, go to the Cloud SQL Instances page.

Go to Cloud SQL Instances
To open the Overview page of an instance, click the instance name.
Select Users from the SQL navigation menu.
Click Add user account .

In the Add a user account to instance instance_name page, add the following information:
- Username : Set to quickstart-user
- Password : Specify a password for your database user. Make a note of this for use in a later step of this quickstart.
- In the Host name section, the default is Allow any host , which means that the user can connect from any IP address.
  Optionally, select Restrict host by IP address or address range and enter an IP address or address range in the Host section. The user can then connect only from the IP address or addresses specified.

Click Add .

gcloud

Replace the following:

PASSWORD with a password for your database user. Make a note of this for use in a later step of this quickstart.

Run the gcloud sql users create command to create the user.

gcloud  
sql  
users  
create  
 quickstart-user 
  
--instance = 
 quickstart-instance 
  
--password = 
 PASSWORD

Username length limits are the same for Cloud SQL as for on-premises MySQL; 32 characters for MySQL 8.0 and later, 16 characters for earlier versions.

Set up a service account

Create and configure a Google Cloud service account that has the Cloud SQL Clientrole with permissions to connect to Cloud SQL. After you create a service account, you might need to wait for 60 seconds or more before you use the service account.

Console

Create a service account

In the Google Cloud console, go to the Create service accountpage.

Go to Create service account

Select a Google Cloud project.
Enter a quickstart-service-account as the service account name.
Optional: Enter a description of the service account.
Click Create and continueand continue to the next step.
Choose the Cloud SQL Client role to grant to the service account on the project.
Click Continue.
Click Doneto finish creating the service account.

Create and download the service account key file

In the Google Cloud console, go to the Service accountspage.

Go to Service accounts

Select a project.
Click the email address of the quickstart-service-account service account that you want to create a key for.
Click the Keystab.
Click the Add keydrop-down menu, then select Create new key.
Select JSONas the Key typeand click Create.

Clicking Createdownloads a service account key file. After you download the key file, you cannot download it again.

Make sure to store the key file securely, because it can be used to authenticate as your service account. You can move and rename this file however you would like.

gcloud

Create a service account

To create the service account, run the gcloud iam service-accounts create command:

gcloud  
iam  
service-accounts  
create  
quickstart-service-account  
--description = 
 " DESCRIPTION 
" 
  
--display-name = 
 " quickstart-service-account 
"

Replace the following value:

DESCRIPTION : An optional description of the service account

To grant your service account the Cloud SQL Client role on your project, run the gcloud projects add-iam-policy-binding command. Replace PROJECT_ID with your Google Cloud project ID:

gcloud  
projects  
add-iam-policy-binding  
 PROJECT_ID 
  
--member = 
 "serviceAccount:quickstart-service-account@ PROJECT_ID 
.iam.gserviceaccount.com" 
  
--role = 
 "roles/cloudsql.client"

Create and download the service account key file

To use the service account you just created from your local computer you need a service account key file to authenticate the sample application as the service account. To create and download the service account key file, run the gcloud iam service-accounts keys create command:

gcloud  
iam  
service-accounts  
keys  
create  
 KEY_FILE 
  
--iam-account = 
quickstart-service-account@ PROJECT_ID 
.iam.gserviceaccount.com

Replace the following values:

KEY_FILE : The path to a new output file for the private key — for example, ~/sa-private-key.json .
PROJECT_ID : Your Google Cloud project ID.

The service account key file is now downloaded to your local computer. After you download the key file, you cannot download it again.

Make sure to store the key file securely, because anyone can use it to authenticate as your service account. You can move and rename this file however you would like.

Setup development environment for programming language

Set up your local computer's development environment for your preferred programming language.

Go

Complete the following steps to set up your development environment to run the Go sample app.

Go to the setup guide for a Go development environment .
Complete the instructions in the Install Gosection.

Java

Complete the following steps to set up your development environment to run the Java sample app.

Go to the setup guide for a Java development environment .
Complete the instructions in the Install a JDK (Java Development Kit)section.
Complete the instructions in the Install a build automation toolto set up Apache Maven.

Node.js

Complete the following steps to set up your development environment to run the Node.js sample app.

Go to setup guide for a Node.js development environment .
Complete the instructions in the Installing Node.js and npmsection.

Python

Complete the following steps to set up your development environment to run the Python sample app.

Go to setup guide for a Python development environment .
Complete the instructions in the Installing Pythonsection.

Install Git

Install Git , an open source version control system.

Clone a sample app

Clone a sample app to your local computer using the git clone command.

Go

Run the following commands to clone the Go sample app to your local computer and change directory to the directory containing the sample app.

Clone the sample app.

git  
clone  
https://github.com/GoogleCloudPlatform/golang-samples

Change directory to the directory containing the sample app.
```
 cd 
  
golang-samples/cloudsql/mysql/database-sql
```

Java

Run the following commands to clone the Java sample app to your local computer and change directory to the directory containing the sample app.

Clone the sample app.

git  
clone  
https://github.com/GoogleCloudPlatform/java-docs-samples

Change directory to the directory containing the sample app.
```
 cd 
  
java-docs-samples/cloud-sql/mysql/servlet
```

Node.js

Run the following commands to clone the Node.js sample app to your local computer and change directory to the directory containing the sample app.

Clone the sample app.

git  
clone  
https://github.com/GoogleCloudPlatform/nodejs-docs-samples

Change directory to the directory containing the sample app.
```
 cd 
  
nodejs-docs-samples/cloud-sql/mysql/mysql
```

Python

Run the following commands to clone the Python sample app to your local computer and change directory to the directory containing the sample app.

Clone the sample app.

git  
clone  
https://github.com/GoogleCloudPlatform/python-docs-samples

Change directory to the directory containing the sample app.

 cd 
  
python-docs-samples/cloud-sql/mysql/sqlalchemy

Configure and run sample app

Configure and run the sample app.

Linux/macOS

Go

Open the terminal and run the following commands to initialize environment variables required to run the sample app. Before running the commands, make the following replacements:

CREDENTIALS_JSON_FILE with the file path of your service account's JSON credentials key file using a format like /path/to/service/account/key.json .
INSTANCE_CONNECTION_NAME with your instance's Connection namethat appears on the Cloud SQL instance Overviewpage.
YOUR_DB_PASSWORD with the password of the quickstart-user that you created in the previous Create a userquickstart step.

 export 
  
 GOOGLE_APPLICATION_CREDENTIALS 
 = 
 CREDENTIALS_JSON_FILE 
 export 
  
 INSTANCE_CONNECTION_NAME 
 = 
 ' INSTANCE_CONNECTION_NAME 
' 
 export 
  
 DB_PORT 
 = 
 '3306' 
 export 
  
 DB_NAME 
 = 
 ' quickstart_db 
' 
 export 
  
 DB_USER 
 = 
 ' quickstart-user 
' 
 export 
  
 DB_PASS 
 = 
 ' YOUR_DB_PASSWORD 
'

Run the following commands to get the Go sample app's dependencies on your local computer and run the sample app.

Get the dependencies required to run the sample app.
```
go  
get  
./...
```
Run the sample app.
```
go  
run  
cmd/app/main.go
```
View the running sample app. Open a browser window and go to http://127.0.0.1:8080 .
To stop the sample app, press Control+C in the terminal window where you started the sample app.

Java

Run the following commands to initialize environment variables required to run the sample app. Before running the commands, make the following replacements:

CREDENTIALS_JSON_FILE with the file path of your service account's JSON credentials key file using a format like /path/to/service/account/key.json .
INSTANCE_CONNECTION_NAME with your instance's Connection namethat appears on the Cloud SQL instance Overviewpage.
YOUR_DB_PASSWORD with the password of the quickstart-user that you created in the previous Create a userquickstart step.

 export 
  
 GOOGLE_APPLICATION_CREDENTIALS 
 = 
 CREDENTIALS_JSON_FILE 
 export 
  
 INSTANCE_CONNECTION_NAME 
 = 
 ' INSTANCE_CONNECTION_NAME 
' 
 export 
  
 DB_PORT 
 = 
 '3306' 
 export 
  
 DB_NAME 
 = 
 ' quickstart_db 
' 
 export 
  
 DB_USER 
 = 
 ' quickstart-user 
' 
 export 
  
 DB_PASS 
 = 
 ' YOUR_DB_PASSWORD 
'

Run the following command to get the Java sample app's dependencies on your local computer and run the sample app.
```
mvn  
jetty:run
```
View the running sample app. Open a browser window and go to http://127.0.0.1:8080 .
To stop the sample app, press Control+C in the terminal window where you started the sample app.

Node.js

Run the following commands to initialize environment variables required to run the sample app. Before running the commands, make the following replacements:
- CREDENTIALS_JSON_FILE with the file path of your service account's JSON credentials key file using a format like /path/to/service/account/key.json .
- YOUR_DB_PASSWORD with the password of the quickstart-user that you created in the previous Create a userquickstart step.
```
 export 
  
 GOOGLE_APPLICATION_CREDENTIALS 
 = 
 CREDENTIALS_JSON_FILE 
 export 
  
 INSTANCE_HOST 
 = 
 '127.0.0.1' 
 export 
  
 DB_PORT 
 = 
 '3306' 
 export 
  
 DB_NAME 
 = 
 ' quickstart_db 
' 
 export 
  
 DB_USER 
 = 
 ' quickstart-user 
' 
 export 
  
 DB_PASS 
 = 
 ' YOUR_DB_PASSWORD 
' 
```

Download the Cloud SQL Auth Proxy.

curl  
-o  
cloud-sql-proxy  
 \ 
https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.0.0/cloud-sql-proxy.linux.amd64

Run the Cloud SQL Auth Proxy as a background process. Replace INSTANCE_CONNECTION_NAME with your instance's Connection namethat appears on the Cloud SQL instance Overviewpage.
```
./cloud-sql-proxy  
 \ 
--credentials-file  
 $GOOGLE_APPLICATION_CREDENTIALS 
  
 \ 
 INSTANCE_CONNECTION_NAME 
  
 & 
```

Note: The process running the Cloud SQL Auth Proxy in the background can be stopped using the fg command in your Terminal window where you started the sample app. This should bring the running Cloud SQL Auth Proxy job to the terminal foreground. Then press Control+C to stop the proxy job.

Run the following commands to get the required Node.js packages on to your local computer and run the sample app.

Install the Node.js packages necessary to run the app locally.
```
npm  
install
```
Run the sample app.
```
npm  
start
```
View the running sample app. Open a browser window and go to http://127.0.0.1:8080 .
To stop the sample app, press Control+C in the terminal window where you started the sample app.

Python

Run the following commands to initialize environment variables required to run the sample app. Before running the commands, make the following replacements:

CREDENTIALS_JSON_FILE with the file path of your service account's JSON credentials key file using a format like /path/to/service/account/key.json .
INSTANCE_CONNECTION_NAME with your instance's Connection namethat appears on the Cloud SQL instance Overviewpage.
YOUR_DB_PASSWORD with the password of the quickstart-user that you created in the previous Create a userquickstart step.

 export 
  
 GOOGLE_APPLICATION_CREDENTIALS 
 = 
 CREDENTIALS_JSON_FILE 
 export 
  
 INSTANCE_CONNECTION_NAME 
 = 
 ' INSTANCE_CONNECTION_NAME 
' 
 export 
  
 DB_PORT 
 = 
 '3306' 
 export 
  
 DB_NAME 
 = 
 ' quickstart_db 
' 
 export 
  
 DB_USER 
 = 
 ' quickstart-user 
' 
 export 
  
 DB_PASS 
 = 
 ' YOUR_DB_PASSWORD 
'

Run the following commands to get the Python sample app's requirements on to your local computer and run the sample app.

Initialize a virtual environment and install the requirements to run the sample app.

python3  
-m  
venv  
env source 
  
env/bin/activate
pip  
install  
-r  
requirements.txt

Run the sample app.
```
python  
app.py
```
View the running sample app. Open a browser window and go to http://127.0.0.1:8080 .
To stop the sample app, press Control+C in the terminal window where you started the sample app.

Windows

Go

Run the following commands to initialize environment variables required to run the sample app. Before running the commands, make the following replacements:

CREDENTIALS_JSON_FILE with the file path of your service account's JSON credentials key file using a format like C:\Users\Your-Username\Downloads\key.json .
INSTANCE_CONNECTION_NAME with your instance's Connection namethat appears on the Cloud SQL instance Overviewpage.
YOUR_DB_PASSWORD with the password of the quickstart-user that you created in the previous Create a userquickstart step.

 $env 
:GOOGLE_APPLICATION_CREDENTIALS = 
 " CREDENTIALS_JSON_FILE 
" 
 $env 
:INSTANCE_CONNECTION_NAME = 
 " INSTANCE_CONNECTION_NAME 
" 
 $env 
:DB_PORT = 
 "3306" 
 $env 
:DB_NAME = 
 " quickstart_db 
" 
 $env 
:DB_USER = 
 " quickstart-user 
" 
 $env 
:DB_PASS = 
 " YOUR_DB_PASSWORD 
"

Run the following commands to get the Go sample app's dependencies on your local computer and run the sample app.

Get the dependencies required to run the sample app.
```
go  
get  
./...
```
Run the sample app.
```
go  
run  
cmd \a 
pp \m 
ain.go
```
View the running sample app. Open a browser window and go to http://127.0.0.1:8080 .
To stop the sample app, press Control+C in the Powershell window where you started the sample app.

Java

Run the following commands to initialize environment variables required to run the sample app. Before running the commands, make the following replacements:

CREDENTIALS_JSON_FILE with the file path of your service account's JSON credentials key file using a format like C:\Users\Your-Username\Downloads\key.json .
INSTANCE_CONNECTION_NAME with your instance's Connection namethat appears on the Cloud SQL instance Overviewpage.
YOUR_DB_PASSWORD with the password of the quickstart-user that you created in the previous Create a userquickstart step.

 $env 
:GOOGLE_APPLICATION_CREDENTIALS = 
 " CREDENTIALS_JSON_FILE 
" 
 $env 
:INSTANCE_CONNECTION_NAME = 
 " INSTANCE_CONNECTION_NAME 
" 
 $env 
:DB_PORT = 
 "3306" 
 $env 
:DB_NAME = 
 " quickstart_db 
" 
 $env 
:DB_USER = 
 " quickstart-user 
" 
 $env 
:DB_PASS = 
 " YOUR_DB_PASSWORD 
"

Run the following command to get the Java sample app's dependencies on your local computer and run the sample app.
```
mvn  
jetty:run
```
View the running sample app. Open a browser window and go to http://127.0.0.1:8080 .
To stop the sample app, press Control+C in the Powershell window where you started the sample app.

Node.js

Run the following commands to initialize environment variables required to run the sample app. Before running the commands, make the following replacements:
- CREDENTIALS_JSON_FILE with the file path of your service account's JSON credentials key file using a format like C:\Users\Your-Username\Downloads\key.json .
- YOUR_DB_PASSWORD with the password of the quickstart-user that you created in the previous Create a userquickstart step.
```
 $env 
:GOOGLE_APPLICATION_CREDENTIALS = 
 " CREDENTIALS_JSON_FILE 
" 
 $env 
:INSTANCE_HOST = 
 "127.0.0.1" 
 $env 
:DB_PORT = 
 "3306" 
 $env 
:DB_NAME = 
 " quickstart_db 
" 
 $env 
:DB_USER = 
 " quickstart-user 
" 
 $env 
:DB_PASS = 
 " YOUR_DB_PASSWORD 
" 
```

Download the Cloud SQL Auth Proxy.

wget  
https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.0.0/cloud-sql-proxy.x64.exe  
-O  
cloud-sql-proxy.exe

Run the Cloud SQL Auth Proxy as a background process. Replace INSTANCE_CONNECTION_NAME with your instance's Connection namethat appears on the Cloud SQL instance Overviewpage.

Start-Process  
-filepath  
 ".\cloud-sql-proxy.exe" 
  
-ArgumentList  
 ` 
 "--credentials-file 
 $env 
 :GOOGLE_APPLICATION_CREDENTIALS" 
  
 INSTANCE_CONNECTION_NAME

Note: The process running the Cloud SQL Auth Proxy in the background can be stopped by selecting the cmd.exewindow that was spawned by the Start-Process command. Close the window to stop the proxy job.

Run the following commands to get the required Node.js packages on your local computer and run the sample app.

Install the Node.js packages necessary to run the app locally.
```
npm  
install
```
Run the sample app.
```
npm  
start
```
View the running sample app. Open a browser window and go to http://127.0.0.1:8080 .
To stop the sample app, press Control+C in the Powershell window where you started the sample app.

Python

Run the following commands to initialize environment variables required to run the sample app. Before running the commands, make the following replacements:

CREDENTIALS_JSON_FILE with the file path of your service account's JSON credentials key file using a format like C:\Users\Your-Username\Downloads\key.json .
INSTANCE_CONNECTION_NAME with your instance's Connection namethat appears on the Cloud SQL instance Overviewpage.
YOUR_DB_PASSWORD with the password of the quickstart-user that you created in the previous Create a userquickstart step.

 $env 
:GOOGLE_APPLICATION_CREDENTIALS = 
 " CREDENTIALS_JSON_FILE 
" 
 $env 
:INSTANCE_CONNECTION_NAME = 
 " INSTANCE_CONNECTION_NAME 
" 
 $env 
:DB_PORT = 
 "3306" 
 $env 
:DB_NAME = 
 " quickstart_db 
" 
 $env 
:DB_USER = 
 " quickstart-user 
" 
 $env 
:DB_PASS = 
 " YOUR_DB_PASSWORD 
"

Run the following commands to get the Python sample app's requirements on your local computer and run the sample app.

Initialize a virtual environment and install the requirements to run the sample app.

virtualenv  
--python  
python3  
env
. \e 
nv \S 
cripts \a 
ctivate
pip  
install  
-r  
requirements.txt

Run the sample app.
```
python  
app.py
```
View the running sample app. Open a browser window and go to http://127.0.0.1:8080 .
To stop the sample app, press Control+C in the Powershell window where you started the sample app.

Clean up

To avoid incurring charges to your Google Cloud account for the resources used on this page, follow these steps.

In the Google Cloud console, go to the Cloud SQL Instances page.

Go to Cloud SQL Instances
Select the quickstart-instance instance to open the Instance detailspage.
In the icon bar at the top of the page, click Delete.
In the Delete instancedialog box, type quickstart-instance , and then click Deleteto delete the instance.

Optional cleanup steps

If you're not using the Cloud SQL clientrole that you assigned to the quickstart-service-account service account, you can remove it.

In the Google Cloud console, go to the Service accounts page.

Go to IAM
Click the edit icon (which looks like a pencil) for the IAM account named quickstart-service-account.
Delete the Cloud SQL clientrole.
Click Save.

If you're not using the APIs that were enabled as part of this quickstart, you can disable them.

APIs that were enabled within this quickstart:
- Cloud SQL Admin API
- Identity and Access Management API

In the Google Cloud console, go to the APIs page.

Go to APIs
Select any API that you would like to disable and then click the Disable APIbutton.

What's next

Based on your needs, you can learn more about creating Cloud SQL instances .

You also can learn about creating MySQL users and databases for your Cloud SQL instance.

For more information about pricing, see Cloud SQL for MySQL pricing .

Learn more about:

Configuring your Cloud SQL instance with a public IP address.
Configuring your Cloud SQL instance with a private IP address.

Additionally, you can learn about connecting to a Cloud SQL instance from other Google Cloud applications: