cloud_sql_proxy(1)

cloud_sql_proxy(1) — the Debian GNU/Linux manual page, but make it make sense 💖

okay bestie, gather round, because this is the manual page for cloud_sql_proxy from the Debian GNU/Linux manual and it's genuinely iconic. it's giving "your tunnel to the cloud, but cute."

---

✨ NAME ✨

cloud_sql_proxy — connect securely to a 2nd generation cloud sql database 🦋

---

✨ SYNOPSIS ✨

cloud_sql_proxy

yeah that's it. no flags needed to start, the flags are where the fun is. keep reading. 💅

---

✨ DESCRIPTION ✨

The Cloud SQL Proxy is your little secure bestie for talking to Google Cloud SQL. simple, secure connectivity, no cap. It's a long-running process that opens up local sockets — either TCP or Unix sockets — based on whatever parameters you handed it. Then your local app just connects to the Cloud SQL instance by using the matching socket. that's the whole vibe. 🎀

Authorization

By default, the proxy authenticates under the default service account of the Compute Engine VM it's running on. so like, that VM needs at least the sqlservice.admin API scope, and the associated project needs the SQL Admin API enabled. also the default service account must have at least WRITER/EDITOR privileges to any projects of the target SQL instances. no privileges, no tunnel, periodt.

• On Google Compute Engine, the default service account is used. The Cloud SQL API must be enabled for the VM.
• When the gcloud command-line tool is installed on the local machine, the active account is used for authentication. Run gcloud auth list to see which accounts are installed on your local machine, and gcloud config list account to view the active account.
• To configure the proxy using a service account, pass the -credential_file parameter or set the GOOGLE_APPLICATION_CREDENTIALS environment variable. This will override gcloud or GCE (Google Compute Engine) credentials, if they exist.

---

✨ OPTIONS ✨

General

• -quiet — Disable log messages (like when new connections are established). > ⚠️ WARNING: this option disables ALL logging output (including connection errors), which will likely make debugging difficult. fr fr, you will be sad. Also: the -quiet flag takes precedence over the -verbose flag.
• -verbose — When explicitly set to false, disable log messages that are not errors nor first-time startup messages (e.g. when new connections are established or closed without errors).
• -version — Print the version of the proxy and exit. short king behavior, love that. 👑

Connection

• -credential_file — If provided, this json file will be used to retrieve Service Account credentials. You may set the GOOGLE_APPLICATION_CREDENTIALS environment variable for the same effect.
• -token — When set, the proxy uses this Bearer token for authorization.
• -max_connections — If provided, the maximum number of connections to establish before refusing new connections. Defaults to 0 (no limit).
• -instances — To connect to a specific list of instances, set the instances parameter to a comma-separated list of fully qualified instance connection strings (project:region:name). For example:

-instances=my-project:my-region:my-instance

For connectivity over TCP, you must specify a tcp port as part of the instance string. For example, the following opens a loopback TCP socket on port 3306, which will be proxied to connect to the instance my-instance in project my-project:

-instances=my-project:my-region:my-instance=tcp:3306

When connecting over TCP, the -instances parameter is required. Supplying the INSTANCES environment variable achieves the same effect. One can use that to keep k8s manifest files constant across multiple environments. If the name has the suffix =tcp:port, a TCP server is opened on the specified port to proxy to that instance. Otherwise, one socket file per instance is opened in dir. You may use the INSTANCES environment variable for the same effect. Using both will use the value from the flag. Not compatible with -fuse.

• -instances_metadata — When running on GCE (Google Compute Engine) you can avoid the need to specify the list of instances on the command line by using the Metadata server. This parameter specifies a path to a metadata value which is then polled for a comma-separated list of fully qualified instances (project:region:name) to connect to in exactly the same way as the -instances parameter. Updates to the metadata value will be observed and acted on by the Proxy. For example, to use the instance metadata value named cloud-sql-instances you would provide instance/attributes/cloud-sql-instances.
• -check_region — If specified, the region portion of the connection string is required for Unix socket-based connections.
• -projects — To direct the proxy to open connections for each Cloud SQL Instance in the comma-separated list of projects specified, set the projects parameter:

-projects=my-project

• -refresh_config_throttle — If set, this flag specifies the amount of forced sleep between successive API calls in order to protect client API quota. Minimum allowed value is 1s.
• -dir — When using Unix sockets (the default for systems which support them), the Proxy places the sockets representing database instances in the directory specified by the -dir parameter.
• -fuse — If your local environment has FUSE installed, you can specify the -fuse flag to avoid the requirement to specify instances in advance. Mount a directory at dir using FUSE for accessing instances. > 💀 Note that the directory at dir must be empty before this program is started. With FUSE, any attempts to open a Unix socket in the directory specified by -dir automatically creates that socket and connects to the corresponding instance. literally magic, we love her. ✨
• -fuse_tmp — Used as a temporary directory if -fuse is set. Note that files in this directory can be removed automatically by this program.

Automatic instance discovery

If the Google Cloud SQL is installed on the local machine and no instance connection flags are specified, the proxy connects to all instances in the gcloud tool's active project. Run gcloud config list project to display the active project. no setup, just vibes. 🌈

---

✨ FILES ✨

• Credentials — By default user account credentials are acquired by gcloud auth login and stored locally on the system. gcloud auth activate-service-account authorizes access using a service account. As with gcloud init and gcloud auth login, this command saves the service account credentials to the local system on successful completion and sets the specified account as the active account in your Cloud SDK configuration. To configure the proxy using a service account, pass the -credential_file parameter or set the GOOGLE_APPLICATION_CREDENTIALS environment variable. This will override gcloud or GCE (Google Compute Engine) credentials, if they exist.
• sockets directory — When using Unix sockets (the default for systems which support them), the Proxy places the sockets representing database instances in the directory specified by the -dir parameter. With FUSE one can also interact with the proxy using this directory to specify instances of cloud SQL databases to connect to on the fly.
• /dev/fuse — Optional functionality can be enabled (--fuse) with access to /dev/fuse as well as the fusermount binary.

---

✨ SEE ALSO ✨

fusermount(1), mount(8), mount.fuse(8), ulockmgr_server(1), mysql(1), postgres(1). go read those too bestie, iykyk 🫶

---

✨ BUGS ✨

The upstream issue reporting system is at github. 😭

---

✨ AUTHOR ✨

Manoj Srivastava <srivasta@google.com> — ty for your service, icon. 👑

---

okay that's the whole page, we ate and left no crumbs. this Debian GNU/Linux manual page is from the Debian source, version dated 2018-05-10, and it's titled cloud_sql_proxy(1). now go proxy something securely, mwah 💖🌸🦋