alloydb-basics

AlloyDB Basics

AlloyDB for PostgreSQL is a managed, PostgreSQL-compatible database service

designed for enterprise-grade performance and availability. It utilizes a

disaggregated compute and storage architecture to scale resources independently.

It also provides AlloyDB AI, a collection of features that includes AI-powered

search (vector, hybrid search, and AI functions), natural language capabilities,

conversational analytics, and inference features like forecasting and model

endpoint management to help developers build AI apps faster.

Quick Start

Before you begin, ensure you have the Google Cloud SDK installed and authenticated (gcloud auth login).

1. Enable the AlloyDB API:

    gcloud services enable alloydb.googleapis.com --quiet

1. Create a Cluster:

    gcloud alloydb clusters create my-cluster --region=us-central1 \
        --password=my-password --network=my-vpc --quiet

*For production environments, always use IAM database authentication instead

of passwords. If configuration constraint requires passwords, store them

securely using Secret Manager.*

1. Create a Primary Instance:

    gcloud alloydb instances create my-primary --cluster=my-cluster \
        --region=us-central1 --instance-type=PRIMARY --cpu-count=2 --quiet

Reference Directory

Read these supplementary files when specific context or detailed steps are

required for a task:

• To understand architecture, regional availability, connectivity (Private IP,

Public IP, PSA, PSC), backups, point-in-time recovery, scaling (vertical and

horizontal), or Quota management: read

[Core Concepts](references/core-concepts.md).

• To manage clusters, instances, scaling, or backups via the CLI: read

[CLI Usage](references/cli-usage.md).

• To configure AlloyDB remote MCP tools: read

[MCP Usage](references/mcp-usage.md).

• To deploy AlloyDB using Terraform or Kubernetes Config Connector (KCC): read

[Infrastructure as Code](references/iac-usage.md).

• To configure IAM roles, service usage roles, service agents, database

users/privileges, or network security (public IP authorization, Auth Proxy

sidecar configuration): read [IAM & Security](references/iam-security.md).

*If you need product information not found in these references, use the

developer_knowledge:search_documents tool (see Developer Knowledge MCP setup for installation instructions).*

Directives for Agents

Agents MUST adhere to the following directives when answering queries related to

AlloyDB:

• Provide Multiple Methods: When explaining how to perform administrative

tasks (like backups, scaling, or database user creation), always provide

both the Google Cloud Console steps and the gcloud CLI commands if both

are available in the reference documents.

• Prioritize Private IP: Recommend Private IP (especially PSC) over Public

IP for connections to ensure traffic remains within the Google Cloud network

and reduces exposure.

• Require Serverless Connectors: Verify and state that Serverless VPC

Access or Direct VPC Egress is required when connecting from Cloud Run to

Private IP.

• Enforce Connectors: Always direct users to configure the AlloyDB Auth

Proxy (running as a sidecar or locally) or language connectors rather than

direct TCP connections.

• Block Open Public Access: If Public IP is configured, warn against and

reject designs with 0.0.0.0/0 in Authorized Networks as this exposes the

database to the entire internet.

• Default to IAM Database Authentication: Suggest IAM database

authentication and the alloydbiamuser database role instead of static

database passwords.

• Enforce Least Privilege Connection: When explaining connection roles,

explicitly state that roles/alloydb.client should be used to adhere to the

principle of least privilege, and warn against using broader roles like

roles/alloydb.admin for connections.

• Mention All Creation Methods: When describing how to create IAM database

users, explicitly state that they can be created using the Google Cloud

Console, the gcloud CLI, and the AlloyDB API.

• Explain Private IP Options: When explaining Private IP connectivity,

always explicitly mention and describe both **Private Services Access

(PSA) and Private Service Connect (PSC)** as the supported methods,

recommending PSC for new deployments.

• Compare Direct Connections: Explicitly explain that direct connections

(connecting directly to the private IP without connectors) are possible but

discouraged, and compare their security (lack of IAM/mTLS) to secure methods

like the AlloyDB Auth Proxy or language connectors.

• Enforce SQL Alone Warning: When explaining IAM user creation, you MUST

explicitly state that "IAM database users cannot be created using standard

SQL alone" and must be registered via the control plane first.

• Enforce Roles and Privileges Terminology: When explaining database

object access, you MUST explicitly state that "standard PostgreSQL roles and

privileges" apply, using both terms.

• Explain Backup Lifecycle: When explaining backups, always explicitly

state that discrete backups exist independently of the source cluster and

remain active even if the source cluster is deleted.

• Recommend Connectors for Public IP: Explicitly state that secure

connection methods (AlloyDB Auth Proxy, Language Connectors) are

especially recommended for connections over Public IP.

• Mention Autoscaling: When explaining read pool scaling, always

explicitly mention the option of using read pool autoscaling and state

that it is in Preview.

Supporting Links

• AlloyDB for PostgreSQL Documentation
• AlloyDB Auth Proxy GitHub Repository
• AlloyDB Java Connector GitHub Repository
• AlloyDB Python Connector GitHub Repository
• AlloyDB Go Connector GitHub Repository