This page shows you how to connect to Cloud SQL from a local test environment using the Cloud SQL Proxy. Connecting through the proxy enables you to test an App Engine application in your local environment, or establish a secure connection for database administration.
Do not use these instructions to set up the proxy for a production environment. For more connection options, see Connection Options for External Applications.
Before you begin
Before performing the steps in this quickstart, you should complete the following tasks:
- Create a GCP project and a PostgreSQL instance.
- If you are using a pre-existing project, make sure your GCP
user is an owner of your project, or has the
Cloud SQL Clientrole. Otherwise, you should set up the proxy using the instructions outlined in Connecting using the Cloud SQL Proxy. -
Optionally, install the
psqlclient.The client enables you to test your connection to your instance. The
psqlclient is installed with the server package, or it can be installed on its own. Learn more.
Enable the Cloud SQL API
Enable the Cloud SQL Admin API.Install and authenticate the gcloud command-line tool
-
If you haven't already, install the
gcloudcommand-line tool.For more information, see Cloud SDK Documentation.
You do not need any additional components, but be sure to run
gcloud initto initialize thegcloudtool. -
Authenticate the
gcloudcommand-line tool:gcloud auth login
Install the Cloud SQL Proxy client on your local machine
The proxy binary you download depends on your operating system, and whether
it uses a 32-bit or 64-bit kernel.
Most newer hardware uses a 64-bit kernel. If you are unsure whether your
machine is running a 64-bit kernel, use the
uname -a command for Linux or macOS, or click Computer > Properties in
the Start Menu for Windows.
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, renaming it 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, renaming it tocloud_sql_proxy.exe.
Get the instance connection name
-
Go to the Cloud SQL Instances page in the Google Cloud Platform Console.
-
Click the instance name to open its Instance details page.
-
Under Connect to this instance, note the Instance connection name.
You will use this value in the next step.
Start the proxy
Start the proxy in its own terminal so you can monitor its output. Replace
<INSTANCE_CONNECTION_NAME> with the instance connection name you copied
in the previous step.
./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:5432
You should see a message similar to:
Listening on 127.0.0.1:5432 for myproject:us-central1:myinstance". Ready for new connections
Connect to your database using the psql client
This step is optional, but recommended so you can test your connection.
Run the following command, replacing<USERNAME> with your PostgreSQL username,
and <DB_NAME> with the name of the database you want to connect to.
psql "host=127.0.0.1 sslmode=disable dbname=<DB_NAME> user=<USER_NAME>"
You should see the psql prompt, and a message similar to the following example should appear in the proxy terminal:
New connection for "myproject:us-central1:myinstance"
