{"id":13418738,"url":"https://github.com/GoogleCloudPlatform/cloud-sql-proxy","last_synced_at":"2025-03-15T04:30:26.927Z","repository":{"id":37587586,"uuid":"43526067","full_name":"GoogleCloudPlatform/cloud-sql-proxy","owner":"GoogleCloudPlatform","description":"A utility for connecting securely to your Cloud SQL instances","archived":false,"fork":false,"pushed_at":"2024-12-12T19:03:09.000Z","size":3586,"stargazers_count":1287,"open_issues_count":33,"forks_count":350,"subscribers_count":64,"default_branch":"main","last_synced_at":"2024-12-18T08:40:01.975Z","etag":null,"topics":["cloud-sql","cloud-sql-proxy","gcp","google-cloud","google-cloud-platform","libraries"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GoogleCloudPlatform.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-10-01T23:13:02.000Z","updated_at":"2024-12-12T19:03:12.000Z","dependencies_parsed_at":"2023-12-24T15:27:54.398Z","dependency_job_id":"157646c4-8ac3-4611-8a99-f078713a7f00","html_url":"https://github.com/GoogleCloudPlatform/cloud-sql-proxy","commit_stats":{"total_commits":1409,"total_committers":118,"mean_commits":"11.940677966101696","dds":0.5486160397444997,"last_synced_commit":"7c630930c3dfbc92a0cbdc094147ca264c6ccfca"},"previous_names":["googlecloudplatform/cloudsql-proxy"],"tags_count":120,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Fcloud-sql-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Fcloud-sql-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Fcloud-sql-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Fcloud-sql-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GoogleCloudPlatform","download_url":"https://codeload.github.com/GoogleCloudPlatform/cloud-sql-proxy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243104061,"owners_count":20236944,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloud-sql","cloud-sql-proxy","gcp","google-cloud","google-cloud-platform","libraries"],"created_at":"2024-07-30T22:01:06.346Z","updated_at":"2025-03-15T04:30:26.921Z","avatar_url":"https://github.com/GoogleCloudPlatform.png","language":"Go","readme":"# Cloud SQL Auth Proxy\n\n[![CI][ci-badge]][ci-build]\n\n\u003e [!IMPORTANT]\n\u003e\n\u003e The Cloud SQL Auth Proxy does not currently support Unix domain socket\n\u003e connections to MySQL 8.4 instances. This is due to a [known issue](https://github.com/GoogleCloudPlatform/cloud-sql-proxy/issues/2317)\n\u003e involving the new default `caching_sha2_password` authentication plugin.\n\nThe Cloud SQL Auth Proxy is a utility for ensuring secure connections to your\nCloud SQL instances. It provides IAM authorization, allowing you to control who\ncan connect to your instance through IAM permissions, and TLS 1.3 encryption,\nwithout having to manage certificates.\n\nSee the [Connecting Overview][connection-overview] page for more information on\nconnecting to a Cloud SQL instance, or the [About the Proxy][about-proxy] page\nfor details on how the Cloud SQL Proxy works.\n\nThe Cloud SQL Auth Proxy has support for:\n\n- [Automatic IAM Authentication][iam-auth] (Postgres and MySQL only)\n- Metrics ([Cloud Monitoring][], [Cloud Trace][], and [Prometheus][])\n- [HTTP Healthchecks][health-check-example]\n- Service account impersonation\n- Separate Dialer functionality released as the [Cloud SQL Go Connector][go connector]\n- Configuration with [environment variables](#config-environment-variables)\n- Fully POSIX-compliant flags\n\nIf you're using Go, Java, Python, or Node.js, consider using the corresponding Cloud SQL\nconnector which does everything the Proxy does, but in process:\n\n- [Cloud SQL Go connector][go connector]\n- [Cloud SQL Java connector][java connector]\n- [Cloud SQL Python connector][python connector]\n- [Cloud SQL Node.js connector][node connector]\n\nFor users migrating from v1, see the [Migration Guide](migration-guide.md).\nThe [v1 README][v1 readme] is still available.\n\n\u003e [!IMPORTANT]\n\u003e \n\u003e The Proxy does not configure the network between the VM it's running on\n\u003e and the Cloud SQL instance. You MUST ensure the Proxy can reach your Cloud SQL\n\u003e instance, either by deploying it in a VPC that has access to your Private IP\n\u003e instance, or by configuring Public IP.\n\n[cloud monitoring]: https://cloud.google.com/monitoring\n[cloud trace]: https://cloud.google.com/trace\n[prometheus]: https://prometheus.io/\n[go connector]: https://github.com/GoogleCloudPlatform/cloud-sql-go-connector\n[java connector]: https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory\n[python connector]: https://github.com/GoogleCloudPlatform/cloud-sql-python-connector\n[node connector]: https://github.com/GoogleCloudPlatform/cloud-sql-nodejs-connector\n[v1 readme]: https://github.com/GoogleCloudPlatform/cloudsql-proxy/blob/5f5b09b62eb6dfcaa58ce399d0131c1544bf813f/README.md\n\n## Installation\n\nCheck for the latest version on the [releases page][releases] and use the\nfollowing instructions for your OS and CPU architecture.\n\n\u003c!-- {x-release-please-start-version} --\u003e\n\u003cdetails open\u003e\n\u003csummary\u003eLinux amd64\u003c/summary\u003e\n\n```sh\n# see Releases for other versions\nURL=\"https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.15.1\"\n\ncurl \"$URL/cloud-sql-proxy.linux.amd64\" -o cloud-sql-proxy\n\nchmod +x cloud-sql-proxy\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eLinux 386\u003c/summary\u003e\n\n```sh\n# see Releases for other versions\nURL=\"https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.15.1\"\n\ncurl \"$URL/cloud-sql-proxy.linux.386\" -o cloud-sql-proxy\n\nchmod +x cloud-sql-proxy\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eLinux arm64\u003c/summary\u003e\n\n```sh\n# see Releases for other versions\nURL=\"https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.15.1\"\n\ncurl \"$URL/cloud-sql-proxy.linux.arm64\" -o cloud-sql-proxy\n\nchmod +x cloud-sql-proxy\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eLinux arm\u003c/summary\u003e\n\n```sh\n# see Releases for other versions\nURL=\"https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.15.1\"\n\ncurl \"$URL/cloud-sql-proxy.linux.arm\" -o cloud-sql-proxy\n\nchmod +x cloud-sql-proxy\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eMac (Intel)\u003c/summary\u003e\n\n```sh\n# see Releases for other versions\nURL=\"https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.15.1\"\n\ncurl \"$URL/cloud-sql-proxy.darwin.amd64\" -o cloud-sql-proxy\n\nchmod +x cloud-sql-proxy\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eMac (Apple Silicon)\u003c/summary\u003e\n\n```sh\n# see Releases for other versions\nURL=\"https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.15.1\"\n\ncurl \"$URL/cloud-sql-proxy.darwin.arm64\" -o cloud-sql-proxy\n\nchmod +x cloud-sql-proxy\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eWindows x64\u003c/summary\u003e\n\n```sh\n# see Releases for other versions\ncurl https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.15.1/cloud-sql-proxy.x64.exe -o cloud-sql-proxy.exe\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eWindows x86\u003c/summary\u003e\n\n```sh\n# see Releases for other versions\ncurl https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.15.1/cloud-sql-proxy.x86.exe -o cloud-sql-proxy.exe\n```\n\n\u003c/details\u003e\n\u003c!-- {x-release-please-end} --\u003e\n\n### Install from Source\n\nTo install from source, ensure you have the latest version of [Go installed](https://go.dev/doc/install).\n\nThen, simply run:\n\n```shell\ngo install github.com/GoogleCloudPlatform/cloud-sql-proxy/v2@latest\n```\n\nThe `cloud-sql-proxy` will be placed in `$GOPATH/bin` or `$HOME/go/bin`.\n\n## Usage\n\nThe following examples all reference an `INSTANCE_CONNECTION_NAME`, which takes\nthe form: `myproject:myregion:myinstance`.\n\nTo find your Cloud SQL instance's `INSTANCE_CONNECTION_NAME`, visit the detail\npage of your Cloud SQL instance in the console, or use `gcloud` with:\n\n```shell\ngcloud sql instances describe \u003cINSTANCE_NAME\u003e --format='value(connectionName)'\n```\n\n### Credentials\n\nThe Cloud SQL Proxy uses a Cloud IAM principal to authorize connections against\na Cloud SQL instance. The Proxy sources the credentials using\n[Application Default Credentials](https://cloud.google.com/docs/authentication/production).\n\n\u003e [!NOTE]\n\u003e\n\u003e Any IAM principal connecting to a Cloud SQL database will need one of the\n\u003e following IAM roles:\n\u003e\n\u003e - Cloud SQL Client (preferred)\n\u003e - Cloud SQL Editor\n\u003e - Cloud SQL Admin\n\u003e\n\u003e Or one may manually assign the following IAM permissions:\n\u003e \n\u003e - `cloudsql.instances.connect`\n\u003e - `cloudsql.instances.get`\n\u003e\n\u003e See [Roles and Permissions in Cloud SQL][roles-and-permissions] for details.\n\nWhen the Proxy authenticates under the Compute Engine VM's default service\naccount, the VM must have at least the `sqlservice.admin` API scope (i.e.,\n\"https://www.googleapis.com/auth/sqlservice.admin\") and the associated project\nmust have the SQL Admin API enabled. The default service account must also have\nat least writer or editor privileges to any projects of target SQL instances.\n\nThe Proxy also supports two flags related to credentials:\n\n- `--token` to use an OAuth2 token\n- `--credentials-file` to use a service account key file\n\n### Basic Usage\n\nTo start the Proxy, use:\n\n```shell\n# starts the Proxy listening on localhost with the default database engine port\n# For example:\n#   MySQL      localhost:3306\n#   Postgres   localhost:5432\n#   SQL Server localhost:1433\n./cloud-sql-proxy \u003cINSTANCE_CONNECTION_NAME\u003e\n```\n\nThe Proxy will automatically detect the default database engine's port and start\na corresponding listener. Production deployments should use the `--port` flag to\nreduce startup time.\n\nThe Proxy supports multiple instances:\n\n```shell\n./cloud-sql-proxy \u003cINSTANCE_CONNECTION_NAME_1\u003e \u003cINSTANCE_CONNECTION_NAME_2\u003e\n```\n\n### Configuring Port\n\nTo override the port, use the `--port` flag:\n\n```shell\n# Starts a listener on localhost:6000\n./cloud-sql-proxy --port 6000 \u003cINSTANCE_CONNECTION_NAME\u003e\n```\n\nWhen specifying multiple instances, the port will increment from the flag value:\n\n```shell\n# Starts a listener on localhost:6000 for INSTANCE_CONNECTION_1\n# and localhost:6001 for INSTANCE_CONNECTION_NAME_2.\n./cloud-sql-proxy --port 6000 \u003cINSTANCE_CONNECTION_NAME_1\u003e \u003cINSTANCE_CONNECTION_NAME_2\u003e\n```\n\nTo configure ports on a per instance basis, use the `port` query param:\n\n```shell\n# Starts a listener on localhost:5000 for the instance called \"postgres\"\n# and starts a listener on localhost:6000 for the instance called \"mysql\"\n./cloud-sql-proxy \\\n    'myproject:my-region:postgres?port=5000' \\\n    'myproject:my-region:mysql?port=6000'\n```\n\n### Configuring Listening Address\n\nTo override the choice of `localhost`, use the `--address` flag:\n\n```shell\n# Starts a listener on all interfaces at port 5432\n./cloud-sql-proxy --address 0.0.0.0 \u003cINSTANCE_CONNECTION_NAME\u003e\n```\n\nTo override address on a per-instance basis, use the `address` query param:\n\n```shell\n# Starts a listener on 0.0.0.0 for \"postgres\" at port 5432\n# and a listener on 10.0.0.1:3306 for \"mysql\"\n./cloud-sql-proxy \\\n    'myproject:my-region:postgres?address=0.0.0.0' \\\n    'myproject:my-region:mysql?address=10.0.0.1\"\n```\n\n### Configuring Private IP\n\nBy default, the Proxy attempts to connect to an instance's public IP. To enable\nprivate IP, use:\n\n```shell\n# Starts a listener connected to the private IP of the Cloud SQL instance.\n# Note: there must be a network path present for this to work.\n./cloud-sql-proxy --private-ip \u003cINSTANCE_CONNECTION_NAME\u003e\n```\n\n\u003e [!IMPORTANT]\n\u003e \n\u003e The Proxy does not configure the network. You MUST ensure the Proxy can\n\u003e reach your Cloud SQL instance, either by deploying it in a VPC that has access\n\u003e to your Private IP instance, or by configuring Public IP.\n\n### Configuring Unix domain sockets\n\nThe Proxy also supports [Unix domain sockets](https://en.wikipedia.org/wiki/Unix_domain_socket).\nTo start the Proxy with Unix sockets, run:\n\n```shell\n# Uses the directory \"/mycooldir\" to create a Unix socket\n# For example, the following directory would be created:\n#   /mycooldir/myproject:myregion:myinstance\n./cloud-sql-proxy --unix-socket /mycooldir \u003cINSTANCE_CONNECTION_NAME\u003e\n```\n\nTo configure a Unix domain socket on a per-instance basis, use the `unix-socket`\nquery param:\n\n```shell\n# Starts a TCP listener on localhost:5432 for \"postgres\"\n# and creates a Unix domain socket for \"mysql\":\n#     /cloudsql/myproject:my-region:mysql\n./cloud-sql-proxy \\\n    myproject:my-region:postgres \\\n    'myproject:my-region:mysql?unix-socket=/cloudsql'\n```\n\n\u003e [!NOTE]\n\u003e\n\u003e The Proxy supports Unix domain sockets on recent versions of Windows, but\n\u003e replaces colons with periods:\n\u003e \n\u003e ```shell\n\u003e # Starts a Unix domain socket at the path:\n\u003e #    C:\\cloudsql\\myproject.my-region.mysql\n\u003e ./cloud-sql-proxy --unix-socket C:\\cloudsql myproject:my-region:mysql\n\u003e ```\n\n### Configuring IAM Database Authentication\n\nThe Proxy supports [Automatic IAM Database Authentication][iam-auth] for MySQL\nand Postgres instances, allowing IAM principal's to authenticate and connect\nas database users.\n\nMake sure to configure your [Cloud SQL instance to allow IAM authentication][iam-auth-config]\nand to [add your IAM principal as a database user][iam-auth-user].\n\n```shell\n./cloud-sql-proxy --auto-iam-authn \u003cINSTANCE_CONNECTION_NAME\u003e\n```\n\n\u003e [!IMPORTANT]\n\u003e \n\u003e Make sure to run the Proxy as the same IAM principal as the database user\n\u003e you want to log in as. Only the IAM principal that is attached to the\n\u003e [sourced credentials](#credentials) will be able to successfully log in\n\u003e via automatic IAM database authentication.\n\u003e\n\u003e When logging in using an IAM database user, Cloud SQL truncates usernames\n\u003e based on the engine type in order to not exceed character limits.\n\u003e PostgreSQL's username character limit is 63, while MySQL's is 32.\n\u003e\n\u003e Cloud SQL IAM database usernames are formatted in the following way:\n\u003e \n\u003e **Postgres**:\n\u003e * For an IAM user account, this is the user's email address.\n\u003e * For a service account, it is the service account's email without the\n\u003e `.gserviceaccount.com` domain suffix.\n\u003e\n\u003e **MySQL**:\n\u003e * For an IAM user account, this is the user's email address,\n\u003e without the `@` or domain name. For example, for `test-user@gmail.com`,\n\u003e the database user would be `test-user`.\n\u003e * For a service account, this is the service account's email address without\n\u003e the `@project-id.iam.gserviceaccount.com` suffix.\n\n### Configuring DNS domain names to identify instances\n\nThe Proxy can be configured to use DNS to look up an instance. This would\nallow you to configure your application to connect to a database instance, and\ncentrally configure which instance in your DNS zone.\n\n#### Configuring DNS Records\n\nAdd a DNS TXT record for the Cloud SQL instance to a **private** DNS server\nor a private Google Cloud DNS Zone used by your application.\n\n**Note:** You are strongly discouraged from adding DNS records for your\nCloud SQL instances to a public DNS server. This would allow anyone on the\ninternet to discover the Cloud SQL instance name.\n\nFor example: suppose you wanted to use the domain name\n`prod-db.mycompany.example.com` to connect to your database instance\n`my-project:region:my-instance`. You would create the following DNS record:\n\n- Record type: `TXT`\n- Name: `prod-db.mycompany.example.com` – This is the domain name used by the application\n- Value: `my-project:region:my-instance` – This is the instance name\n\n#### Configuring the Proxy\n\nConfigure the Proxy with your DNS domain name instead of an instance connection\nname:\n\n```sh\n./cloud-sql-proxy prod-db.mycompany.example.com\n```\n\n### Automatic fail-over using DNS domain names\n\nWhen the Proxy is configured using a domain name, it will\nperiodically check if the DNS record for an instance changes. When the Proxy\ndetects that the domain name refers to a different instance, it will\nclose all open connections to the old instance. Subsequent connection attempts\nwill be directed to the new instance.\n\nFor example: suppose application is configured to connect using the\ndomain name `prod-db.mycompany.example.com`. Initially the corporate DNS\nzone has a TXT record with the value `my-project:region:my-instance`. The\napplication establishes connections to the `my-project:region:my-instance`\nCloud SQL instance.\n\nThen, to reconfigure the application to use a different database\ninstance, change the value of the `prod-db.mycompany.example.com` DNS record\nfrom `my-project:region:my-instance` to `my-project:other-region:my-instance-2`\n\nThe Proxy detects the change to this DNS record.\nNow, when the application connects to its database using the\ndomain name `prod-db.mycompany.example.com`, it will connect to the\n`my-project:other-region:my-instance-2` Cloud SQL instance.\n\nThe Proxy will automatically close all existing connections to\n`my-project:region:my-instance`. This will force the connection pools to\nestablish new connections. Also, it may cause database queries in progress\nto fail.\n\nThe Proxy will poll for changes to the DNS name every 30 seconds by default.\n\n### Testing Connectivity\n\nThe Proxy includes support for a connection test on startup. This test helps\nensure the Proxy can reach the associated instance and is a quick debugging\ntool. The test will attempt to connect to the specified instance(s) and fail\nif the instance is unreachable. If the test fails, the Proxy will exit with\na non-zero exit code.\n\n```shell\n./cloud-sql-proxy --run-connection-test \u003cINSTANCE_CONNECTION_NAME\u003e\n```\n\n### Config file\n\nThe Proxy supports a configuration file. Supported file types are TOML, JSON,\nand YAML. Load the file with the `--config-file` flag:\n\n```shell\n./cloud-sql-proxy --config-file /path/to/config.[toml|json|yaml]\n```\n\nThe configuration file format supports all flags. The key names should match\nthe flag names. For example:\n\n``` toml\n# use instance-connection-name-0, instance-connection-name-1, etc.\n# for multiple instances\ninstance-connection-name = \"proj:region:inst\"\nauto-iam-authn = true\ndebug = true\ndebug-logs = true\n```\n\nRun `./cloud-sql-proxy --help` for more details. See the full documentation\nin [docs/cmd](docs/cmd).\n\n### Config environment variables\n\nThe proxy supports configuration through environment variables. \nEach environment variable uses \"CSQL_PROXY\" as a prefix and is \nthe uppercase version of the flag using underscores as word delimiters. \n\nFor example, the `--auto-iam-authn` flag may be set with the environment variable \n`CSQL_PROXY_AUTO_IAM_AUTHN`.\n\nAn invocation of the Proxy using environment variables would look like the following: \n\n```shell\nCSQL_PROXY_AUTO_IAM_AUTHN=true \\ \n    ./cloud-sql-proxy \u003cINSTANCE_CONNECTION_NAME\u003e\n```\n\nRun `./cloud-sql-proxy --help` for more details.\n\n### Configuring a Lazy Refresh\n\nThe `--lazy-refresh` flag configures the Proxy to retrieve connection info\nlazily and as-needed. Otherwise, no background refresh cycle runs. This setting\nis useful in environments where the CPU may be throttled outside of a request\ncontext, e.g., Cloud Run, Cloud Functions, etc.\n\n### Additional flags\n\nTo see a full list of flags, use:\n\n```shell\n./cloud-sql-proxy --help\n```\n\n\n## Container Images\n\nThere are containerized versions of the Proxy available from the following\n[Artifact Registry](https://cloud.google.com/artifact-registry) repositories:\n\n- `gcr.io/cloud-sql-connectors/cloud-sql-proxy`\n- `us.gcr.io/cloud-sql-connectors/cloud-sql-proxy`\n- `eu.gcr.io/cloud-sql-connectors/cloud-sql-proxy`\n- `asia.gcr.io/cloud-sql-connectors/cloud-sql-proxy`\n\n\u003e [!NOTE]\n\u003e\n\u003e The above container images were migrated from Google Container Registry (deprecated)\n\u003e to Artifact Registry which is why they begin with the old naming pattern (`gcr.io`)\n\nEach image is tagged with the associated Proxy version. The following tags are\ncurrently supported:\n\n- `$VERSION` (default)\n- `$VERSION-alpine`\n- `$VERSION-bullseye`\n- `$VERSION-bookworm`\n\n\u003c!-- {x-release-please-start-version} --\u003e\nThe `$VERSION` is the Proxy version without the leading \"v\" (e.g.,\n`2.15.1`).\n\nFor example, to pull a particular version, use a command like:\n\n``` shell\n# $VERSION is 2.15.1\ndocker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.15.1\n```\n\n\u003c!-- {x-release-please-end} --\u003e\nWe recommend pinning to a specific version tag and using automation with a CI pipeline\nto update regularly.\n\nThe default container image uses [distroless][] with a non-root user. If you\nneed a shell or related tools, use the Alpine or Debian-based container images\n(bullseye or bookworm) listed above.\n\n[distroless]: https://github.com/GoogleContainerTools/distroless\n\n### Working with Docker and the Proxy\n\nThe containers have the proxy as an `ENTRYPOINT` so, to use the proxy from a\ncontainer, all you need to do is specify options using the command, and expose\nthe proxy's internal port to the host. For example, you can use:\n\n```shell\ndocker run --publish \u003chost-port\u003e:\u003cproxy-port\u003e \\\n    gcr.io/cloud-sql-connectors/cloud-sql-proxy:latest \\\n    --address \"0.0.0.0\" --port \u003cproxy-port\u003e \u003cinstance-connection-name\u003e\n```\n\nYou'll need the `--address \"0.0.0.0\"` so that the proxy doesn't only listen for\nconnections originating from *within* the container.\n\nYou will need to authenticate using one of the methods outlined in the\n[credentials](#credentials) section. If using a credentials file you must mount\nthe file and ensure that the non-root user that runs the proxy has *read access*\nto the file. These alternatives might help:\n\n1. Change the group of your local file and add read permissions to the group\nwith `chgrp 65532 key.json \u0026\u0026 chmod g+r key.json`.\n1. If you can't control your file's group, you can directly change the public\npermissions of your file by doing `chmod o+r key.json`.\n\n\u003e [!WARNING]\n\u003e \n\u003e This can be insecure because it allows any user in the host system to read\n\u003e the credential file which they can use to authenticate to services in GCP.\n\nFor example, a full command using a JSON credentials file might look like\n\n```shell\ndocker run \\\n    --publish \u003chost-port\u003e:\u003cproxy-port\u003e \\\n    --mount type=bind,source=\"$(pwd)\"/sa.json,target=/config/sa.json \\\n    gcr.io/cloud-sql-connectors/cloud-sql-proxy:latest \\\n    --address 0.0.0.0 \\\n    --port \u003cproxy-port\u003e \\\n    --credentials-file /config/sa.json \u003cinstance-connection-name\u003e\n```\n\n## Running as a Kubernetes Sidecar\n\nSee the [example here][sidecar-example] as well as [Connecting from Google\nKubernetes Engine][connect-to-k8s].\n\n## Running behind a Socks5 proxy\n\nThe Cloud SQL Auth Proxy includes support for sending requests through a SOCKS5\nproxy. If a SOCKS5 proxy is running on `localhost:8000`, the command to start\nthe Cloud SQL Auth Proxy would look like:\n\n```\nALL_PROXY=socks5://localhost:8000 \\\nHTTPS_PROXY=socks5://localhost:8000 \\\n    cloud-sql-proxy \u003cINSTANCE_CONNECTION_NAME\u003e\n```\n\nThe `ALL_PROXY` environment variable specifies the proxy for all TCP\ntraffic to and from a Cloud SQL instance. The `ALL_PROXY` environment variable\nsupports `socks5` and `socks5h` protocols. To route DNS lookups through a proxy,\nuse the `socks5h` protocol.\n\nThe `HTTPS_PROXY` (or `HTTP_PROXY`) specifies the proxy for all HTTP(S) traffic\nto the SQL Admin API. Specifying `HTTPS_PROXY` or `HTTP_PROXY` is only necessary\nwhen you want to proxy this traffic. Otherwise, it is optional. See\n[`http.ProxyFromEnvironment`](https://pkg.go.dev/net/http@go1.17.3#ProxyFromEnvironment)\nfor possible values.\n\n## Support for Metrics and Tracing\n\nThe Proxy supports [Cloud Monitoring][], [Cloud Trace][], and [Prometheus][].\n\nSupported metrics include:\n\n- `cloudsqlconn/dial_latency`: The distribution of dialer latencies (ms)\n- `cloudsqlconn/open_connections`: The current number of open Cloud SQL\n  connections\n- `cloudsqlconn/dial_failure_count`: The number of failed dial attempts\n- `cloudsqlconn/refresh_success_count`: The number of successful certificate\n  refresh operations\n- `cloudsqlconn/refresh_failure_count`: The number of failed refresh\n  operations.\n\nSupported traces include:\n\n- `cloud.google.com/go/cloudsqlconn.Dial`: The dial operation including\n  refreshing an ephemeral certificate and connecting the instance\n- `cloud.google.com/go/cloudsqlconn/internal.InstanceInfo`: The call to retrieve\n  instance metadata (e.g., database engine type, IP address, etc)\n- `cloud.google.com/go/cloudsqlconn/internal.Connect`: The connection attempt\n  using the ephemeral certificate\n- SQL Admin API client operations\n\nTo enable Cloud Monitoring and Cloud Trace, use the `--telemetry-project` flag\nwith the project where you want to view metrics and traces. To configure the\nmetrics prefix used by Cloud Monitoring, use the `--telemetry-prefix` flag. When\nenabling telemetry, both Cloud Monitoring and Cloud Trace are enabled. To\ndisable Cloud Monitoring, use `--disable-metrics`. To disable Cloud Trace, use\n`--disable-traces`.\n\nTo enable Prometheus, use the `--prometheus` flag. This will start an HTTP\nserver on localhost with a `/metrics` endpoint. The Prometheus namespace may\noptionally be set with `--prometheus-namespace`.\n\n## Debug logging\n\nTo enable debug logging to report on internal certificate refresh operations,\nuse the `--debug-logs` flag. Typical use of the Proxy should not require debug\nlogs, but if you are surprised by the Proxy's behavior, debug logging should\nprovide insight into internal operations and can help when reporting issues.\n\n## Localhost Admin Server\n\nThe Proxy includes support for an admin server on localhost. By default, the\nthe admin server is not enabled. To enable the server, pass the --debug or\n--quitquitquit flag. This will start the server on localhost at port 9091.\nTo change the port, use the --admin-port flag.\n\nWhen --debug is set, the admin server enables Go's profiler available at\n/debug/pprof/.\n\nSee the [documentation on pprof][pprof] for details on how to use the\nprofiler.\n\nWhen --quitquitquit is set, the admin server adds an endpoint at\n/quitquitquit. The admin server exits gracefully when it receives a GET or POST\nrequest at /quitquitquit.\n\n[pprof]: https://pkg.go.dev/net/http/pprof.\n\n## Frequently Asked Questions\n\n### Why would I use the Proxy?\n\nThe Proxy is a convenient way to control access to your database using IAM\npermissions while ensuring a secure connection to your Cloud SQL instance. When\nusing the Proxy, you do not have to manage database client certificates,\nconfigured Authorized Networks, or ensure clients connect securely. The Proxy\nhandles all of this for you.\n\n### How should I use the Proxy?\n\nThe Proxy is a gateway to your Cloud SQL instance. Clients connect to the Proxy\nover an unencrypted connection and are authorized using the environment's IAM\nprincipal. The Proxy then encrypts the connection to your Cloud SQL instance.\n\nBecause client connections are not encrypted and authorized using the\nenvironment's IAM principal, we recommend running the Proxy on the same VM or\nKubernetes pod as your application and using the Proxy's default behavior of\nallowing connections from only the local network interface. This is the most\nsecure configuration: unencrypted traffic does not leave the VM, and only\nconnections from applications on the VM are allowed.\n\nHere are some common examples of how to run the Proxy in different environments:\n\n- [Connect to Cloud SQL for MySQL from your local computer][local-quickstart]\n- [Connect to Cloud SQL for MySQL from Google Kubernetes Engine][gke-quickstart]\n\n[local-quickstart]: https://cloud.google.com/sql/docs/mysql/connect-instance-local-computer\n[gke-quickstart]: https://cloud.google.com/sql/docs/mysql/connect-instance-kubernetes\n\n### Why can't the Proxy connect to my private IP instance?\n\nThe Proxy does not configure the network between the VM it's running on and the\nCloud SQL instance. You MUST ensure the Proxy can reach your Cloud SQL\ninstance, either by deploying it in a VPC that has access to your Private IP\ninstance, or by configuring Public IP.\n\n### Should I use the Proxy for large deployments?\n\nWe recommend deploying the Proxy on the host machines that are running the\napplication. However, large deployments may exceed the request quota for the SQL\nAdmin API . If your Proxy reports request quota errors, we recommend deploying\nthe Proxy with a connection pooler like [pgbouncer][] or [ProxySQL][]. For\ndetails, see [Running the Cloud SQL Proxy as a Service][service-example].\n\n### Can I share the Proxy across multiple applications?\n\nInstead of using a single Proxy across multiple applications, we recommend using\none Proxy instance for every application process. The Proxy uses the context's\nIAM principal and so have a 1-to-1 mapping between application and IAM principal\nis best. If multiple applications use the same Proxy instance, then it becomes\nunclear from an IAM perspective which principal is doing what.\n\n### How do I verify the shasum of a downloaded Proxy binary?\n\nAfter downloading a binary from the releases page, copy the sha256sum value\nthat corresponds with the binary you chose.\n\nThen run this command (make sure to add the asterisk before the file name):\n\n``` shell\necho '\u003cRELEASE_PAGE_SHA_HERE\u003e *\u003cNAME_OF_FILE_HERE\u003e' | shasum -c\n```\n\nFor example, after downloading the v2.1.0 release of the Linux AMD64 Proxy, you\nwould run:\n\n``` shell\n$ echo \"547b24faf0dfe5e3d16bbc9f751dfa6b34dfd5e83f618f43a2988283de5208f2 *cloud-sql-proxy\" | shasum -c\ncloud-sql-proxy: OK\n```\n\nIf you see `OK`, the binary is a verified match.\n\n\n[pgbouncer]: https://www.pgbouncer.org/\n[proxysql]: https://www.proxysql.com/\n\n## Reference Documentation\n\n- [Cloud SQL][cloud-sql]\n- [Cloud SQL Auth Proxy Documentation][proxy-page]\n- [Cloud SQL Auth Proxy Quickstarts][quickstarts]\n- [Cloud SQL Code Samples][code-samples]\n- [Cloud SQL Auth Proxy Package Documentation][pkg-docs]\n\n## Support policy\n\n### Major version lifecycle\n\nThis project uses [semantic versioning](https://semver.org/), and uses the\nfollowing lifecycle regarding support for a major version:\n\n- **Active** - Active versions get all new features and security fixes (that\nwouldn’t otherwise introduce a breaking change). New major versions are\nguaranteed to be \"active\" for a minimum of 1 year.\n\n- **Maintenance** - Maintenance versions continue to receive security and critical\nbug fixes, but do not receive new features.\n\n### Release cadence\n\nThe Cloud SQL Auth Proxy aims for a minimum monthly release cadence. If no new\nfeatures or fixes have been added, a new PATCH version with the latest\ndependencies is released.\n\nWe support releases for 1 year from the release date.\n\n## Contributing\n\nContributions are welcome. Please, see the [CONTRIBUTING][contributing] document\nfor details.\n\nPlease note that this project is released with a Contributor Code of Conduct.\nBy participating in this project you agree to abide by its terms. See\n[Contributor Code of Conduct][code-of-conduct] for more information.\n\n[about-proxy]: https://cloud.google.com/sql/docs/mysql/sql-proxy\n[ci-badge]: https://github.com/GoogleCloudPlatform/cloudsql-proxy/actions/workflows/tests.yaml/badge.svg?event=push\n[ci-build]: https://github.com/GoogleCloudPlatform/cloudsql-proxy/actions/workflows/tests.yaml?query=event%3Apush+branch%3Amain\n[cloud-sql]: https://cloud.google.com/sql\n[code-samples]: https://cloud.google.com/sql/docs/mysql/samples\n[code-of-conduct]: CODE_OF_CONDUCT.md\n[connect-to-k8s]: https://cloud.google.com/sql/docs/mysql/connect-kubernetes-engine\n[connection-overview]: https://cloud.google.com/sql/docs/mysql/connect-overview\n[contributing]: CONTRIBUTING.md\n[health-check-example]: https://github.com/GoogleCloudPlatform/cloudsql-proxy/tree/main/examples/k8s-health-check#cloud-sql-proxy-health-checks\n[iam-auth]: https://cloud.google.com/sql/docs/postgres/iam-authentication#auto-iam-auth\n[iam-auth-config]: https://cloud.google.com/sql/docs/postgres/create-edit-iam-instances#configure-iam-db-instance\n[iam-auth-user]: https://cloud.google.com/sql/docs/postgres/add-manage-iam-users#creating-a-database-user\n[pkg-badge]: https://pkg.go.dev/badge/github.com/GoogleCloudPlatform/cloudsql-proxy.svg\n[pkg-docs]: https://pkg.go.dev/github.com/GoogleCloudPlatform/cloudsql-proxy\n[private-ip]: https://cloud.google.com/sql/docs/mysql/private-ip#requirements_for_private_ip\n[proxy-page]: https://cloud.google.com/sql/docs/mysql/sql-proxy\n[quickstarts]: https://cloud.google.com/sql/docs/mysql/quickstarts\n[releases]: https://github.com/GoogleCloudPlatform/cloudsql-proxy/releases\n[roles-and-permissions]: https://cloud.google.com/sql/docs/mysql/roles-and-permissions\n[service-account]: https://cloud.google.com/iam/docs/service-accounts\n[sidecar-example]: https://github.com/GoogleCloudPlatform/cloudsql-proxy/tree/master/examples/k8s-sidecar#run-the-cloud-sql-proxy-as-a-sidecar\n[service-example]: https://github.com/GoogleCloudPlatform/cloudsql-proxy/tree/main/examples/k8s-service\n","funding_links":[],"categories":["Go"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGoogleCloudPlatform%2Fcloud-sql-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGoogleCloudPlatform%2Fcloud-sql-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGoogleCloudPlatform%2Fcloud-sql-proxy/lists"}