Connect to Cloud SQL for PostgreSQL from your local computer

MySQL  |  PostgreSQL  |  SQL Server

Learn how to deploy a sample app on your Linux, macOS, or Windows-based local computerconnected to a PostgreSQL instance by using the Google Cloud console and a clientapplication.

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

Before you begin

Note:The name you use for your project must be between 4 and 30 characters. When youtype the name, the form suggests a project ID, which you can edit. Theproject ID must be between 6 and 30 characters, with a lowercase letteras the first character. You can use a dash, lowercase letter, or digit for theremaining characters, but the last character cannot be a dash.
  1. Enable the Cloud APIs necessary to run a Cloud SQL sample app on your local computer.

    Console

    Click theEnable 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 thegcloud CLI which provides command-line access to your Google Cloud resources. Thegcloud CLI is used to run thegcloud 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 followinggcloud command:

    gcloudservicesenablesqladmin.googleapis.comiam.googleapis.com

    This command enables the following APIs:

    • Cloud SQL Admin API
    • IAM API

Set up Cloud SQL

Create a Cloud SQL instance

Console

Create an instance with a public IP address

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

    Go to Cloud SQL Instances

  2. ClickCreate Instance.
  3. Click Choose PostgreSQL.
  4. Enterquickstart-instance forInstance ID.
  5. Enter a password for the postgres user. Save this password for future use.
  6. Click theSingle zone option forChoose region and zonal availability.
  7. Click and expand theShow Configuration Options section.
  8. In theMachine Type drop-down menu, selectLightweight.

  9. ClickCreate Instance and wait until the instance initializes and starts.

gcloud

Create an instance with a public IP address

Before running thegcloud sql instances create command as follows, replaceDB_ROOT_PASSWORD with the password of your database user.

Optionally, modify the values for the following parameters:

  • --database_version: The database engine type and version. If left unspecified, the API default is used. See thegcloud database versions documentation to see the currently available versions.
  • --cpu: The number of cores to set in the machine.
  • --memory: Whole number value indicating how much memory to set in the machine. A size unit should be provided (for example, 3072MB or 9GB). If no units are specified, GB is assumed.
  • --region: Regional location of the instance (for example asia-east1, us-east1). If left unspecified, the defaultus-central is used. See the full list ofregions.

Run thegcloud sql instances create command to create a Cloud SQL instance.

gcloudsqlinstancescreatequickstart-instance--database-version=POSTGRES_13--cpu=1--memory=4GB--region=us-central--root-password=DB_ROOT_PASSWORD

Create a database

Console

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

    Go to Cloud SQL Instances

  2. Selectquickstart-instance.
  3. Open theDatabases tab.
  4. ClickCreate database.
    1. In theNew database dialog box, enterquickstart_db as the name of the database.
    2. ClickCreate.

gcloud

Run thegcloud sql databases create command to create a database.

gcloudsqldatabasescreatequickstart_db--instance=quickstart-instance

Create a user

Console

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

    Go to Cloud SQL Instances

  2. To open theOverview page of an instance, click the instance name.
  3. SelectUsers from theSQL navigation menu.
  4. ClickAdd user account.
  5. On theAdd a user account to instanceinstance_name page, add the following information:
    • In theUsername field, enterquickstart-user
    • In thePassword field, specify a password for your database user. Make a note of this for use in a later step of this quickstart.
  6. ClickAdd.

gcloud

Replace the following:

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

Run thegcloud sql users create command to create the user.

gcloudsqluserscreatequickstart-user--instance=quickstart-instance--password=PASSWORD

User name length limits are the same for Cloud SQL as foron-premises PostgreSQL.

Set up a service account

Create and configure a Google Cloud service account that has theCloud SQL Client role 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

  1. In the Google Cloud console, go to theCreate service account page.

    2. Go to Create service account

  2. Select a Google Cloud project.
  3. Enter aquickstart-service-account as the service account name.
  4. Optional: Enter a description of the service account.
  5. ClickCreate and continue and continue to the next step.
  6. Choose the Cloud SQL Client role to grant to the service account on the project.
  7. ClickContinue.
  8. ClickDone to finish creating the service account.

Create and download the service account key file

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

    2. Go to Service accounts

  2. Select a project.
  3. Click the email address of thequickstart-service-account service account that you want to create a key for.
  4. Click theKeys tab.
  5. Click theAdd key drop-down menu, then selectCreate new key.
  6. SelectJSON as theKey type and clickCreate.

ClickingCreate downloads 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

  1. To create the service account, run thegcloud iam service-accounts create command:
    2. gcloudiamservice-accountscreatequickstart-service-account--description="DESCRIPTION"--display-name="quickstart-service-account"

    Replace the following value:

    • DESCRIPTION: An optional description of the service account
  2. To grant your service account the Cloud SQL Client role on your project, run thegcloud projects add-iam-policy-binding command. ReplacePROJECT_ID with your Google Cloud project ID:
    gcloudprojectsadd-iam-policy-bindingPROJECT_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 thegcloud iam service-accounts keys create command:

gcloudiamservice-accountskeyscreateKEY_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.

  1. Go to thesetup guide for a Go development environment.
  2. Complete the instructions in theInstall Go section.

Java

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

  1. Go to thesetup guide for a Java development environment.
  2. Complete the instructions in theInstall a JDK (Java Development Kit) section.
  3. Complete the instructions in theInstall a build automation tool to set up Apache Maven.

Node.js

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

  1. Go tosetup guide for a Node.js development environment.
  2. Complete the instructions in theInstalling Node.js and npm section.

Python

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

  1. Go tosetup guide for a Python development environment.
  2. Complete the instructions in theInstalling Python section.

Install Git

InstallGit, an open source version control system.

Linux

Follow the officialGit installation documentation for Linux.

macOS

Follow the officialGit installation documentation for macOS.

Windows

Follow the officialGit installation documentation for Windows.

Clone a sample app

Clone a sample app to your local computer using thegit 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.

  1. Clone the sample app.
    gitclonehttps://github.com/GoogleCloudPlatform/golang-samples
  2. Change directory to the directory containing the sample app.
    cdgolang-samples/cloudsql/postgres/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.

  1. Clone the sample app.
    gitclonehttps://github.com/GoogleCloudPlatform/java-docs-samples
  2. Change directory to the directory containing the sample app.
    cdjava-docs-samples/cloud-sql/postgres/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.

  1. Clone the sample app.
    gitclonehttps://github.com/GoogleCloudPlatform/nodejs-docs-samples
  2. Change directory to the directory containing the sample app.
    cdnodejs-docs-samples/cloud-sql/postgres/knex

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.

  1. Clone the sample app.
    gitclonehttps://github.com/GoogleCloudPlatform/python-docs-samples
  2. Change directory to the directory containing the sample app.
    cdpython-docs-samples/cloud-sql/postgres/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'sConnection name that appears on the Cloud SQL instanceOverview page.
  • YOUR_DB_PASSWORD with the password of thequickstart-user that you created in the previousCreate a user quickstart step.
exportGOOGLE_APPLICATION_CREDENTIALS=CREDENTIALS_JSON_FILEexportINSTANCE_CONNECTION_NAME='INSTANCE_CONNECTION_NAME'exportDB_PORT='5432'exportDB_NAME='quickstart_db'exportDB_USER='quickstart-user'exportDB_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.

  1. Get the dependencies required to run the sample app.
    goget./...
  2. Run the sample app.
    goruncmd/app/main.go
  3. View the running sample app. Open a browser window and go tohttp://127.0.0.1:8080.

    View deployed sample app

  4. To stop the sample app, pressControl+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'sConnection name that appears on the Cloud SQL instanceOverview page.
  • YOUR_DB_PASSWORD with the password of thequickstart-user that you created in the previousCreate a user quickstart step.
exportGOOGLE_APPLICATION_CREDENTIALS=CREDENTIALS_JSON_FILEexportINSTANCE_CONNECTION_NAME='INSTANCE_CONNECTION_NAME'exportDB_PORT='5432'exportDB_NAME='quickstart_db'exportDB_USER='quickstart-user'exportDB_PASS='YOUR_DB_PASSWORD'

  1. Run the following command to get the Java sample app's dependencies on your local computer and run the sample app.

    mvnjetty:run
  2. View the running sample app. Open a browser window and go tohttp://127.0.0.1:8080.

    View deployed sample app

  3. To stop the sample app, pressControl+C in the terminal window where you started the sample app.

Node.js

  1. 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 thequickstart-user that you created in the previousCreate a user quickstart step.
    exportGOOGLE_APPLICATION_CREDENTIALS=CREDENTIALS_JSON_FILEexportINSTANCE_HOST='127.0.0.1'exportDB_PORT='5432'exportDB_NAME='quickstart_db'exportDB_USER='quickstart-user'exportDB_PASS='YOUR_DB_PASSWORD'
  2. Download the Cloud SQL Auth Proxy.
    curl-ocloud-sql-proxy\https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.0.0/cloud-sql-proxy.linux.amd64
  3. Run the Cloud SQL Auth Proxy as a background process. ReplaceINSTANCE_CONNECTION_NAME with your instance'sConnection name that appears on the Cloud SQL instanceOverview page.
    ./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 thefg 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 pressControl+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.

  1. Install the Node.js packages necessary to run the app locally.
    npminstall
  2. Run the sample app.
    npmstart
  3. View the running sample app. Open a browser window and go tohttp://127.0.0.1:8080.

    View deployed sample app

  4. To stop the sample app, pressControl+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:

exportGOOGLE_APPLICATION_CREDENTIALS=CREDENTIALS_JSON_FILEexportINSTANCE_CONNECTION_NAME='INSTANCE_CONNECTION_NAME'exportDB_PORT='5432'exportDB_NAME='quickstart_db'exportDB_USER='quickstart-user'exportDB_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.

  1. Initialize a virtual environment and install the requirements to run the sample app.
    python3-mvenvenvsourceenv/bin/activatepipinstall-rrequirements.txt
  2. Run the sample app.
    pythonapp.py
  3. View the running sample app. Open a browser window and go tohttp://127.0.0.1:8080.

    View deployed sample app

  4. To stop the sample app, pressControl+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:

$env:GOOGLE_APPLICATION_CREDENTIALS="CREDENTIALS_JSON_FILE"$env:INSTANCE_CONNECTION_NAME="INSTANCE_CONNECTION_NAME"$env:DB_PORT="5432"$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.

  1. Get the dependencies required to run the sample app.
    goget./...
  2. Run the sample app.
    goruncmd\app\main.go
  3. View the running sample app. Open a browser window and go tohttp://127.0.0.1:8080.

    View deployed sample app

  4. To stop the sample app, pressControl+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:

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

  1. Run the following command to get the Java sample app's dependencies on your local computer and run the sample app.

    mvnjetty:run
  2. View the running sample app. Open a browser window and go tohttp://127.0.0.1:8080.

    View deployed sample app

  3. To stop the sample app, pressControl+C in the Powershell window where you started the sample app.

Node.js

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

    $env:GOOGLE_APPLICATION_CREDENTIALS="CREDENTIALS_JSON_FILE"$env:INSTANCE_HOST="127.0.0.1"$env:DB_PORT="5432"$env:DB_NAME="quickstart_db"$env:DB_USER="quickstart-user"$env:DB_PASS="YOUR_DB_PASSWORD"
  2. Download the Cloud SQL Auth Proxy.
    wgethttps://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.0.0/cloud-sql-proxy.x64.exe-Ocloud-sql-proxy.exe
  3. Run the Cloud SQL Auth Proxy as a background process. ReplaceINSTANCE_CONNECTION_NAME with your instance'sConnection name that appears on the Cloud SQL instanceOverview page.
    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 thecmd.exe window that was spawned by theStart-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.

  1. Install the Node.js packages necessary to run the app locally.
    npminstall
  2. Run the sample app.
    npmstart
  3. View the running sample app. Open a browser window and go tohttp://127.0.0.1:8080.

    View deployed sample app

  4. To stop the sample app, pressControl+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:

$env:GOOGLE_APPLICATION_CREDENTIALS="CREDENTIALS_JSON_FILE"$env:INSTANCE_CONNECTION_NAME="INSTANCE_CONNECTION_NAME"$env:DB_PORT="5432"$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.

  1. Initialize a virtual environment and install the requirements to run the sample app.
    virtualenv--pythonpython3env.\env\Scripts\activatepipinstall-rrequirements.txt
  2. Run the sample app.
    pythonapp.py
  3. View the running sample app. Open a browser window and go tohttp://127.0.0.1:8080.

    View deployed sample app

  4. To stop the sample app, pressControl+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.

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

    Go to Cloud SQL Instances

  2. Select thequickstart-instance instance to open theInstance detailspage.
  3. In the icon bar at the top of the page, clickDelete.
  4. In theDelete instance dialog box, typequickstart-instance, and thenclickDelete to delete the instance.

Optional cleanup steps

If you're not using theCloud SQL client role that you assigned to thequickstart-service-account service account, you can remove it.

  1. In the Google Cloud console, go to theIAM page.

    Go to IAM

  2. Click the edit icon (which looks like a pencil) for the IAM account namedquickstart-service-account.
  3. Delete theCloud SQL client role.
  4. ClickSave.

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

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

  1. In the Google Cloud console, go to theAPIs page.

    Go to APIs

  2. Select any API that you would like to disable and then click theDisable API button.

What's next

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

You also can learn about creatingPostgreSQL users anddatabases for your Cloud SQL instance.

For more information about pricing, seeCloud SQL for PostgreSQL pricing.

Learn more about:

  • Configuring your Cloud SQL instance with apublic IP address.
  • Configuring your Cloud SQL instance with aprivate IP address.

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

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-07-14 UTC.