Skip to main content
Agent skill

Alloydb Basics

Manages clusters, instances, and backups for AlloyDB for PostgreSQL, and integrates with AlloyDB Model Context Protocol (MCP) tools for automated database operations. Use when creating, configuring, or administering AlloyDB databases. Do NOT use for general PostgreSQL instances (e.g. Cloud SQL) or other GCP databases.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Alloydb Basics when an AI agent needs a reusable SKILL.md workflow for this job: Manages clusters, instances, and backups for AlloyDB for PostgreSQL, and integrates with AlloyDB Model Context Protocol (MCP) tools for automated database operations. Use when creating, configuring, or administering AlloyDB databases. Do NOT use for general PostgreSQL instances (e.g. Cloud SQL) or other GCP databases.

When not to use it

Skip Alloydb Basics when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/alloydb-basics
# Save SKILL.md to ~/.claude/skills/alloydb-basics/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/alloydb-basics/SKILL.md. For a shared project, commit the folder at .claude/skills/alloydb-basics/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Alloydb Basics skill for this task: Use Alloydb Basics when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# 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.

## Attribution

**MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you MUST read [Usage Attribution](references/attribution.md). For commands executed directly in the terminal (never in generated scripts, Terraform, or user code), prefix `gcloud` with `CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:alloydb-basics)"` and append `agent-skills/1.0 (skill:alloydb-basics)` to `User-Agent` headers.

## 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)

Intended uses

  • Use Alloydb Basics when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.