{"id":15221900,"url":"https://github.com/googlecloudplatform/alloydb-go-connector","last_synced_at":"2025-10-20T01:43:46.304Z","repository":{"id":38186062,"uuid":"465808435","full_name":"GoogleCloudPlatform/alloydb-go-connector","owner":"GoogleCloudPlatform","description":"A Go library for connecting securely to your AlloyDB instances","archived":false,"fork":false,"pushed_at":"2025-03-11T15:34:51.000Z","size":1538,"stargazers_count":60,"open_issues_count":8,"forks_count":16,"subscribers_count":19,"default_branch":"main","last_synced_at":"2025-03-30T15:42:16.622Z","etag":null,"topics":["alloydb","go","golang","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":"2022-03-03T16:56:41.000Z","updated_at":"2025-03-11T15:34:46.000Z","dependencies_parsed_at":"2023-10-14T16:34:37.606Z","dependency_job_id":"1b862064-128a-4930-bc53-87f06032dfba","html_url":"https://github.com/GoogleCloudPlatform/alloydb-go-connector","commit_stats":{"total_commits":478,"total_committers":15,"mean_commits":"31.866666666666667","dds":0.4560669456066946,"last_synced_commit":"28839d91f57bce74c3e5cd14816b2f27f91c9fad"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Falloydb-go-connector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Falloydb-go-connector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Falloydb-go-connector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Falloydb-go-connector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GoogleCloudPlatform","download_url":"https://codeload.github.com/GoogleCloudPlatform/alloydb-go-connector/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247640465,"owners_count":20971557,"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":["alloydb","go","golang","libraries"],"created_at":"2024-09-28T15:08:45.564Z","updated_at":"2025-10-20T01:43:41.255Z","avatar_url":"https://github.com/GoogleCloudPlatform.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://cloud.google.com/alloydb/docs/connect-language-connectors#go-pgx\"\u003e\n        \u003cimg src=\"docs/images/alloydb-go-connector.png\" alt=\"alloydb-go-connector image\"\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n# AlloyDB Go Connector\n\n[![CI][ci-badge]][ci-build]\n[![Go Reference][pkg-badge]][pkg-docs]\n\n[ci-badge]: https://github.com/GoogleCloudPlatform/alloydb-go-connector/actions/workflows/tests.yaml/badge.svg?event=push\n[ci-build]: https://github.com/GoogleCloudPlatform/alloydb-go-connector/actions/workflows/tests.yaml?query=event%3Apush+branch%3Amain\n[pkg-badge]: https://pkg.go.dev/badge/cloud.google.com/go/alloydbconn.svg\n[pkg-docs]: https://pkg.go.dev/cloud.google.com/go/alloydbconn\n\nThe _AlloyDB Go Connector_ is an AlloyDB connector designed for use with the Go\nlanguage. Using an AlloyDB connector provides the following benefits:\n\n* **IAM Authorization:** uses IAM permissions to control who/what can connect to\n  your AlloyDB instances\n\n* **Improved Security:** uses TLS 1.3 encryption and identity verification\n  between the client connector and the server-side proxy, independent of the\n  database protocol.\n\n* **Convenience:** removes the requirement to use and distribute SSL\n  certificates, as well as manage firewalls or source/destination IP addresses.\n\n* (optionally) **IAM DB Authentication:** provides support for\n  [AlloyDB’s automatic IAM DB AuthN][iam-db-authn] feature.\n\n[iam-db-authn]: https://cloud.google.com/alloydb/docs/manage-iam-authn\n\n## Installation\n\nYou can install this repo with `go get`:\n\n```sh\ngo get cloud.google.com/go/alloydbconn\n```\n\n## Usage\n\nThis package provides several functions for authorizing and encrypting\nconnections. These functions can be used with your database driver to connect to\nyour AlloyDB instance.\n\nAlloyDB supports network connectivity through public IP addresses and private,\ninternal IP addresses. By default this package will attempt to connect over a\nprivate IP connection. When doing so, this package must be run in an\nenvironment that is connected to the [VPC Network][vpc] that hosts your\nAlloyDB private IP address.\n\nPlease see [Configuring AlloyDB Connectivity][alloydb-connectivity] for more details.\n\n[vpc]: https://cloud.google.com/vpc/docs/vpc\n[alloydb-connectivity]: https://cloud.google.com/alloydb/docs/configure-connectivity\n\n### APIs and Services\n\nThis package requires the following to connect successfully:\n\n* IAM principal (user, service account, etc.) with the [AlloyDB\n  Client and Service Usage Consumer][client-role] roles or equivalent\n  permissions. [Credentials](#credentials) for the IAM principal are\n  used to authorize connections to an AlloyDB instance.\n\n* The [AlloyDB API][admin-api] to be enabled within your Google Cloud\n  Project. By default, the API will be called in the project associated with the\n  IAM principal.\n\n[admin-api]:   https://console.cloud.google.com/apis/api/alloydb.googleapis.com\n[client-role]: https://cloud.google.com/alloydb/docs/auth-proxy/overview#how-authorized\n\n### Credentials\n\nThis repo uses the [Application Default Credentials (ADC)][adc] strategy for\nresolving credentials. Please see [these instructions for how to set your ADC][set-adc]\n(Google Cloud Application vs Local Development, IAM user vs service account credentials),\nor consult the [golang.org/x/oauth2/google][google-auth] documentation.\n\nTo explicitly set a specific source for the Credentials, see [Using\nOptions](#using-options) below.\n\n[adc]: https://cloud.google.com/docs/authentication#adc\n[set-adc]: https://cloud.google.com/docs/authentication/provide-credentials-adc\n[google-auth]: https://pkg.go.dev/golang.org/x/oauth2/google#hdr-Credentials\n\n### Connecting with pgx\n\nTo use the dialer with [pgx](https://github.com/jackc/pgx), use\n[pgxpool](https://pkg.go.dev/github.com/jackc/pgx/v4/pgxpool) by configuring a\n[Config.DialFunc][dial-func] like so:\n\n``` go\n// Configure the driver to connect to the database\ndsn := fmt.Sprintf(\"user=%s password=%s dbname=%s sslmode=disable\", pgUser, pgPass, pgDB)\nconfig, err := pgxpool.ParseConfig(dsn)\nif err != nil {\n    log.Fatalf(\"failed to parse pgx config: %v\", err)\n}\n\n// Create a new dialer with any options\nd, err := alloydbconn.NewDialer(ctx)\nif err != nil {\n    log.Fatalf(\"failed to initialize dialer: %v\", err)\n}\n// Don't close the dialer until you're done with the database connection\n// e.g. at the end of your main function\ndefer d.Close()\n\n// Tell the driver to use the AlloyDB Go Connector to create connections\nconfig.ConnConfig.DialFunc = func(ctx context.Context, _ string, instance string) (net.Conn, error) {\n    return d.Dial(ctx, \"projects/\u003cPROJECT\u003e/locations/\u003cREGION\u003e/clusters/\u003cCLUSTER\u003e/instances/\u003cINSTANCE\u003e\")\n}\n\n// Interact with the driver directly as you normally would\nconn, err := pgxpool.ConnectConfig(context.Background(), config)\nif err != nil {\n    log.Fatalf(\"failed to connect: %v\", connErr)\n}\ndefer conn.Close()\n```\n\n[dial-func]: https://pkg.go.dev/github.com/jackc/pgconn#Config\n\n### Using Options\n\nIf you need to customize something about the `Dialer`, you can initialize\ndirectly with `NewDialer`:\n\n```go\nctx := context.Background()\nd, err := alloydbconn.NewDialer(\n    ctx,\n    alloydbconn.WithCredentialsFile(\"key.json\"),\n)\nif err != nil {\n    log.Fatalf(\"unable to initialize dialer: %s\", err)\n}\n\nconn, err := d.Dial(ctx, \"projects/\u003cPROJECT\u003e/locations/\u003cREGION\u003e/clusters/\u003cCLUSTER\u003e/instances/\u003cINSTANCE\u003e\")\n```\n\nFor a full list of customizable behavior, see alloydbconn.Option.\n\n### Using DialOptions\n\nIf you want to customize how the connection is created, use a DialOption.\n\nFor example, to connect over public IP, use:\n\n```go\nconn, err := d.Dial(\n    ctx,\n    \"projects/\u003cPROJECT\u003e/locations/\u003cREGION\u003e/clusters/\u003cCLUSTER\u003e/instances/\u003cINSTANCE\u003e\",\n    alloydbconn.WithPublicIP(),\n)\n```\n\nOr to use PSC, use:\n\n``` go\nconn, err := d.Dial(\n    ctx,\n    \"projects/\u003cPROJECT\u003e/locations/\u003cREGION\u003e/clusters/\u003cCLUSTER\u003e/instances/\u003cINSTANCE\u003e\",\n    alloydbconn.WithPSC(),\n)\n```\n\nYou can also use the `WithDefaultDialOptions` Option to specify DialOptions to\nbe used by default:\n\n```go\nd, err := alloydbconn.NewDialer(\n    ctx,\n    alloydbconn.WithDefaultDialOptions(\n        alloydbconn.WithPublicIP(),\n    ),\n)\n```\n\n### Using the dialer with database/sql\n\nUsing the dialer directly will expose more configuration options. However, it is\npossible to use the dialer with the `database/sql` package.\n\nTo use `database/sql`, use `pgxv5.RegisterDriver` with any necessary Dialer\nconfiguration. Note: the connection string must use the keyword/value format\nwith host set to the instance connection name.\n\n``` go\npackage foo\n\nimport (\n    \"database/sql\"\n\n    \"cloud.google.com/go/alloydbconn\"\n    \"cloud.google.com/go/alloydbconn/driver/pgxv5\"\n)\n\nfunc Connect() {\n    cleanup, err := pgxv5.RegisterDriver(\"alloydb\", alloydbconn.WithPublicIP())\n    if err != nil {\n        // ... handle error\n    }\n    defer cleanup()\n\n    db, err := sql.Open(\n        \"alloydb\",\n        \"host=projects/\u003cPROJECT\u003e/locations/\u003cREGION\u003e/clusters/\u003cCLUSTER\u003e/instances/\u003cINSTANCE\u003e user=myuser password=mypass dbname=mydb sslmode=disable\",\n\t)\n    // ... etc\n}\n```\n\n### Automatic IAM Database Authentication\n\nThe Go Connector supports [Automatic IAM database authentication][].\n\nMake sure to [configure your AlloyDB Instance to allow IAM authentication][configure-iam-authn]\nand [add an IAM database user][add-iam-user].\n\nA `Dialer` can be configured to connect to an AlloyDB instance using\nautomatic IAM database authentication with the `WithIAMAuthN` Option.\n\n```go\nd, err := alloydbconn.NewDialer(ctx, alloydbconn.WithIAMAuthN())\n```\n\nWhen configuring the DSN for IAM authentication, the `password` field can be\nomitted and the `user` field should be formatted as follows:\n\n- For an IAM user account, this is the user's email address.\n- For a service account, it is the service account's email without the\n`.gserviceaccount.com` domain suffix.\n\nFor example, to connect using the `test-sa@test-project.iam.gserviceaccount.com`\nservice account, the DSN would look like:\n\n```go\ndsn := \"user=test-sa@test-project.iam dbname=mydb sslmode=disable\"\n```\n\n[Automatic IAM database authentication]: https://cloud.google.com/alloydb/docs/manage-iam-authn\n[configure-iam-authn]: https://cloud.google.com/alloydb/docs/manage-iam-authn#enable\n[add-iam-user]: https://cloud.google.com/alloydb/docs/manage-iam-authn#create-user\n\n### Enabling Metrics and Tracing\n\nThis library includes support for metrics and tracing using [OpenCensus][]. To\nenable metrics or tracing, you need to configure an [exporter][]. OpenCensus\nsupports many backends for exporters.\n\nSupported metrics include:\n\n- `alloydbconn/dial_latency`: The distribution of dialer latencies (ms)\n- `alloydbconn/open_connections`: The current number of open AlloyDB\n  connections\n- `alloydbconn/dial_failure_count`: The number of failed dial attempts\n- `alloydbconn/refresh_success_count`: The number of successful certificate\n  refresh operations\n- `alloydbconn/refresh_failure_count`: The number of failed refresh\n  operations.\n- `alloydbconn/bytes_sent`: The number of bytes sent to an AlloyDB instance.\n- `alloydbconn/bytes_received`: The number of bytes received from an AlloyDB\n  instance.\n\nSupported traces include:\n\n- `cloud.google.com/go/alloydbconn.Dial`: The dial operation including\n  refreshing an ephemeral certificate and connecting to the instance\n- `cloud.google.com/go/alloydbconn/internal.InstanceInfo`: The call to retrieve\n  instance metadata (e.g., IP address, etc)\n- `cloud.google.com/go/alloydbconn/internal.Connect`: The connection attempt\n  using the ephemeral certificate\n- AlloyDB API client operations\n\nFor example, to use [Cloud Monitoring][] and [Cloud Trace][], you would\nconfigure an exporter like so:\n\n```golang\npackage main\n\nimport (\n    \"contrib.go.opencensus.io/exporter/stackdriver\"\n    \"go.opencensus.io/trace\"\n)\n\nfunc main() {\n    sd, err := stackdriver.NewExporter(stackdriver.Options{\n        ProjectID: \"mycoolproject\",\n    })\n    if err != nil {\n        // handle error\n    }\n    defer sd.Flush()\n    trace.RegisterExporter(sd)\n\n    sd.StartMetricsExporter()\n    defer sd.StopMetricsExporter()\n\n    // Use alloydbconn as usual.\n    // ...\n}\n```\n\n[OpenCensus]: https://opencensus.io/\n[exporter]: https://opencensus.io/exporters/\n[Cloud Monitoring]: https://cloud.google.com/monitoring\n[Cloud Trace]: https://cloud.google.com/trace\n\n### Debug Logging\n\nThe Go Connector supports optional debug logging to help diagnose problems with\nthe background certificate refresh. To enable it, provide a logger that\nimplements the `debug.ContextLogger` interface when initializing the Dialer.\n\nFor example:\n\n``` go\nimport (\n    \"context\"\n    \"net\"\n\n    \"cloud.google.com/go/alloydbconn\"\n)\n\ntype myLogger struct{}\n\nfunc (l *myLogger) Debugf(ctx context.Context, format string, args ...interface{}) {\n    // Log as you like here\n}\n\nfunc connect() {\n    l := \u0026myLogger{}\n\n    d, err := NewDialer(\n        context.Background(),\n        alloydbconn.WithContextDebugLogger(l),\n    )\n    // use dialer as usual...\n}\n```\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**Deprecated** - Deprecated versions continue to receive security and critical\nbug fixes, but do not receive new features. Deprecated versions will be\nsupported for 1 year.\n\n**Unsupported** - Any major version that has been deprecated for \u003e=1 year is\nconsidered unsupported.\n\n## Supported Go Versions\n\nWe follow the [Go Version Support Policy][go-policy] used by Google Cloud\nLibraries for Go.\n\n[go-policy]: https://github.com/googleapis/google-cloud-go#go-versions-supported\n\n### Release cadence\n\nThis project aims for a release on at least a monthly basis. If no new features\nor fixes have been added, a new PATCH version with the latest dependencies is\nreleased.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgooglecloudplatform%2Falloydb-go-connector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgooglecloudplatform%2Falloydb-go-connector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgooglecloudplatform%2Falloydb-go-connector/lists"}