alloydb-basics

---
name: alloydb-basics
description: >-
license: Apache-2.0
---

# 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](https://cloud.google.com/sdk/docs/install) and authenticated (`gcloud auth login`).

1.  **Enable the AlloyDB API:**

    ```bash
    gcloud services enable alloydb.googleapis.com --quiet
    ```

2.  **Create a Cluster:**

    ```bash
    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.*

3.  **Create a Primary Instance:**

    ```bash
    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](https://developers.google.com/knowledge/mcp) 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](https://docs.cloud.google.com/alloydb/docs/overview.md.txt)
-   [AlloyDB Auth Proxy GitHub Repository](https://github.com/GoogleCloudPlatform/alloydb-auth-proxy)
-   [AlloyDB Java Connector GitHub Repository](https://github.com/GoogleCloudPlatform/alloydb-java-connector)
-   [AlloyDB Python Connector GitHub Repository](https://github.com/GoogleCloudPlatform/alloydb-python-connector)
-   [AlloyDB Go Connector GitHub Repository](https://github.com/GoogleCloudPlatform/alloydb-go-connector)