Connection overview

This page summarizes how to connect to databases served by AlloyDB for PostgreSQL:

  • Networking: AlloyDB instances use private IPs on a Virtual Private Cloud (VPC). Various techniques allow secure connections from applications running outside the VPC.

  • Authorization: The AlloyDB Auth Proxy lets you use Identity and Access Management (IAM) to control who has access to your data. Your VPC's firewall lets you further tune access to AlloyDB resources.

  • Authentication: Use standard PostgreSQL user-authentication techniques to log in to your instances.


While an AlloyDB instance contains many nodes, your applications connect to an instance through a single, static IP address. This address is private to the VPC that you specify when first setting up an instance's cluster.

This private-IP restriction impacts application connections in two ways:

  • Applications running elsewhere within your project's VPC can connect to the instance—or to a proxy representing the instance—without additional steps or resources.

    As an example, Connect a psql client to an instance shows how to connect to your AlloyDB instance by running the psql command-line program on a Compute Engine VM within your VPC.

  • Applications running outside the VPC require an intermediary service to connect to the AlloyDB instance. Solutions include running proxy services on a VM within the instance's VPC, or using other Google Cloud products to establish a permanent connection between your application and your VPC.

    For more information, see Connect to a cluster from outside its VPC.

Note that, of the two options, connections over private IP typically provide lower latency and limited attack vectors because they don't require traversing the internet.


You can control access to an AlloyDB cluster by using AlloyDB Language Connectors or the AlloyDB Auth Proxy, as well as with VPC firewall rules.

AlloyDB Language Connectors

AlloyDB Language Connectors are client libraries that provide automated mTLS using TLS 1.3 and IAM authorization when connecting to a AlloyDB cluster.

You can use these libraries directly from their supported programming language. They provide the same functionality as the AlloyDB Proxy without requiring an external process. This provides improved security and reduced configuration requirements to connect to AlloyDB.

For more information, see AlloyDB Language Connectors overview.

Control access with IAM and the AlloyDB Auth Proxy

Although you can connect directly to an instance through its IP address, we recommend using the AlloyDB Auth Proxy in production environments. It provides IAM-based access control and end-to-end encryption between the proxy and your cluster.

For more information, see About the AlloyDB Auth Proxy.

Limit VPC access with firewall rules

As with any cloud-based project, you should tune your VPC's firewall rules to restrict network access only to the IP ranges or subnetworks that your applications connect from. This is especially important with external applications, as detailed in Connect to a cluster from outside its VPC.

For more information about configuring your VPC's firewall, see VPC firewall rules.


AlloyDB supports two kinds of database users, each of which has its own way of authenticating with your databases:

  • Standard PostgreSQL user roles authenticate using a username and password. You manage these accounts using ordinary PostgreSQL user-management techniques. For more information, see Manage AlloyDB user roles.

  • IAM user and service accounts authenticate as database users using OAuth 2.0 tokens. You manage these accounts using the Google Cloud IAM system. For more information, see Manage IAM authentication.

Once authenticated with an AlloyDB instance, an application can treat the instance like an ordinary PostgreSQL server. After establishing networking and authorization routes to an instance, you can use standard PostgreSQL techniques to log in to an instance and access your data. This holds true whether manually logging in with a tool like psql, or connecting to your database programmatically using a PostgreSQL code library.

Typically, your first authentication with a new AlloyDB cluster involves logging in to its primary instance as its postgres user, using the password that you specify when creating the cluster. From there, you should create database users without administrative privileges for your application's use.

What's next