Help us improve
Share bugs, ideas, or general feedback.
From flow
Guides provisioning Google AlloyDB clusters, read pools, columnar engine, Private Service Access, PostgreSQL tuning on GCP, and Cloud SQL migrations.
npx claudepluginhub cofin/flow --plugin flowHow this skill is triggered — by the user, by Claude, or both
Slash command
/flow:alloydbThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
AlloyDB is a fully managed, PostgreSQL-compatible database service on Google Cloud. It combines the familiarity of PostgreSQL with Google's storage and compute innovations for high performance and availability.
Guides provisioning, managing, and connecting to Google Cloud SQL instances for PostgreSQL, MySQL, SQL Server, covering auth proxy, backups, replicas, PITR, private IP, and migrations.
Provisions AlloyDB PostgreSQL clusters and instances on GCP, monitors creation status via operations, and retrieves database configuration and health data like version, uptime, and connections.
Administers modern cloud databases (AWS RDS/Aurora/DynamoDB, Azure SQL/Cosmos, GCP Cloud SQL/Spanner), NoSQL/relational systems; handles IaC (Terraform/CloudFormation), HA/DR, migrations, optimization.
Share bugs, ideas, or general feedback.
AlloyDB is a fully managed, PostgreSQL-compatible database service on Google Cloud. It combines the familiarity of PostgreSQL with Google's storage and compute innovations for high performance and availability.
Use this skill in three distinct layers:
Keep those layers separate when giving guidance. Provisioning is not the same thing as agent connectivity.
| Feature | AlloyDB | Cloud SQL for PostgreSQL |
|---|---|---|
| Storage | Disaggregated, log-based | Attached disk |
| Columnar engine | Built-in adaptive columnar cache | Not available |
| ML embeddings | Native Vertex AI integration | Manual setup |
| Read scaling | Read pool (auto-managed replicas) | Manual read replicas |
| Availability | 99.99% SLA (regional) | 99.95% SLA |
| Networking | Private IP only (PSA required) | Public or private IP |
| Action | Command |
|---|---|
| Create cluster | gcloud alloydb clusters create NAME --region=REGION --network=NETWORK --password=PASS |
| Create primary | gcloud alloydb instances create NAME --cluster=CLUSTER --region=REGION --instance-type=PRIMARY --cpu-count=N |
| Create read pool | gcloud alloydb instances create NAME --cluster=CLUSTER --region=REGION --instance-type=READ_POOL --read-pool-node-count=N |
| Connect via proxy | ./alloydb-auth-proxy "projects/P/locations/R/clusters/C/instances/I" --port=5432 |
| Enable columnar engine | SELECT google_columnar_engine_add('table_name'); |
# From GCE VM in same VPC (private IP)
psql "host=ALLOYDB_IP dbname=postgres user=postgres sslmode=require"
# Via AlloyDB Auth Proxy (recommended for external access)
./alloydb-auth-proxy \
"projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE" \
--port=5432
psql "host=127.0.0.1 port=5432 dbname=postgres user=postgres"
AlloyDB requires Private Service Access (PSA) before any cluster can be created. Allocate an IP range and create the VPC peering connection.
Create the cluster with gcloud alloydb clusters create, then add a primary instance. Choose CPU count based on workload (start with 4 vCPUs for small workloads).
For read-heavy workloads, add a read pool with --instance-type=READ_POOL. AlloyDB automatically manages the read replicas within the pool.
For analytical query patterns, enable the columnar engine on tables with SELECT google_columnar_engine_add('table'). Check g_columnar_recommended_columns for automatic recommendations.
Use the AlloyDB Auth Proxy for connections from outside the VPC. For applications within GCE/GKE on the same VPC, connect directly via private IP.
Use the lowest-admin supported path for the current host, and degrade cleanly:
alloydb and alloydb-observability extensions.gcloud, Auth Proxy, psql, and SQL guidance from this skill's references.Do not make the skill Gemini-only. The Gemini extension path is preferred when available, but the operational guidance in this skill must still work for Claude, Codex, OpenCode, Antigravity, and plain terminal workflows.
--password at cluster creation — there is no way to recover the initial password; store it in Secret Managersslmode=require in connection strings for securityroles/monitoring.viewer and set alerts on CPU, connections, and replication lag before going to productionEXPLAIN (ANALYZE, BUFFERS) on a representative dataset before production deploymentBefore delivering configurations, verify:
default network in productionColumnar engine setup for an analytics workload:
-- Enable columnar engine on the orders table
SELECT google_columnar_engine_add('orders');
-- Check which columns AlloyDB recommends for columnar caching
SELECT table_name, column_name, estimated_benefit
FROM g_columnar_recommended_columns
ORDER BY estimated_benefit DESC;
-- Verify a query uses the columnar engine
EXPLAIN (ANALYZE) SELECT region, SUM(amount)
FROM orders
WHERE order_date >= '2025-01-01'
GROUP BY region;
-- Look for "Columnar Scan" in the plan output
Connection string for a Python application using the Auth Proxy:
DATABASE_URL = "postgresql+asyncpg://postgres:password@127.0.0.1:5432/mydb"
# Auth Proxy runs locally, forwarding to AlloyDB private IP
AlloyDB metrics are available under alloydb.googleapis.com/database/postgresql/* in Cloud Monitoring. Enable Cloud Monitoring before production launch.
Key metrics to watch:
max_connections (200 on pg18)PromQL patterns (Cloud Monitoring / Google Managed Prometheus):
# CPU utilization
avg_over_time(alloydb_googleapis_com:database_postgresql_cpu_utilization[5m])
# Active connections vs capacity
alloydb_googleapis_com:database_postgresql_network_connections
# Replication lag
max by (instance_id)(alloydb_googleapis_com:database_postgresql_replication_replica_lag_seconds)
Required role: roles/monitoring.viewer. See Observability Reference for full PromQL patterns, alert policy examples, and dashboard recommendations.
Before promoting any query to production, validate with EXPLAIN (ANALYZE, BUFFERS). Monitor live workload via pg_stat_activity.
Quick patterns:
-- Active queries with duration
SELECT pid, now() - query_start AS duration, state, query
FROM pg_stat_activity
WHERE state != 'idle'
ORDER BY duration DESC;
-- Tables with bloat
SELECT relname, n_dead_tup, n_live_tup, last_autovacuum
FROM pg_stat_user_tables
WHERE n_dead_tup > 10000
ORDER BY n_dead_tup DESC;
See Operations Reference for EXPLAIN ANALYZE interpretation, bloat detection, autovacuum tuning, invalid index detection, and security hardening.
Run alloydb-auth-proxy as a sidecar container alongside the application pod. The sidecar uses the pod's workload identity (requires roles/alloydb.client) and refreshes IAM tokens automatically. The application connects to 127.0.0.1:5432 with no credential management in the app layer.
Store the database password in Secret Manager. On rotation: add a new secret version, update the AlloyDB user password via gcloud alloydb users set-password, perform a rolling restart with exponential backoff, then disable the old secret version.
Set max_connections=200 for PostgreSQL 18 instances as the production baseline. For workloads exceeding 200 concurrent connections, add PgBouncer in transaction mode rather than raising the limit further.
See Operations Reference for the full Kubernetes sidecar spec, rotation runbook, and connection pooling guidance.
AlloyDB continuous backup enables PITR to any second within the retention window (default 14 days). Restoration creates a new cluster — the original cluster is unaffected.
gcloud alloydb clusters restore RESTORED_CLUSTER_ID \
--region=REGION \
--network=NETWORK \
--source-cluster=projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID \
--point-in-time="2025-06-15T14:30:00Z"
When the primary region is unavailable, promote the secondary cluster with:
gcloud alloydb clusters promote SECONDARY_CLUSTER_ID --region=SECONDARY_REGION
After promotion, update connection strings (via Secret Manager or environment config) to the promoted cluster endpoint. See Operations Reference for the full failover runbook and checklist.
This section is for the connection layer, not for provisioning the AlloyDB cluster itself.
Prefer the dedicated Gemini CLI extensions for managed AlloyDB. They embed the underlying MCP Toolbox flow directly, so Gemini users do not need to configure a separate MCP server first.
Install the core AlloyDB extension:
gemini extensions install https://github.com/gemini-cli-extensions/alloydb --auto-update
Install the observability extension when the user wants metrics, dashboards, alerts, or query-performance monitoring:
gemini extensions install https://github.com/gemini-cli-extensions/alloydb-observability --auto-update
Prefer workspace-scoped configuration:
gemini extensions config alloydb --scope workspace
Guide the user through configuration before starting Gemini:
export ALLOYDB_POSTGRES_PROJECT="<your-gcp-project-id>"
export ALLOYDB_POSTGRES_REGION="<your-alloydb-region>"
export ALLOYDB_POSTGRES_CLUSTER="<your-alloydb-cluster-id>"
export ALLOYDB_POSTGRES_INSTANCE="<your-alloydb-instance-id>"
export ALLOYDB_POSTGRES_DATABASE="<your-database-name>"
export ALLOYDB_POSTGRES_USER="<your-database-user>" # optional
export ALLOYDB_POSTGRES_PASSWORD="<your-database-password>" # optional
export ALLOYDB_POSTGRES_IP_TYPE="PRIVATE" # PRIVATE / PUBLIC / PSC
Important configuration guidance:
v0.6.0 or newer.roles/alloydb.viewer.roles/alloydb.client.roles/alloydb.admin plus roles/serviceusage.serviceUsageConsumer.roles/monitoring.viewer.For non-Gemini agents, or when the user explicitly wants a shared MCP server, guide them through MCP Toolbox with the AlloyDB prebuilt config instead of inventing a custom server:
{
"mcpServers": {
"alloydb": {
"command": "./toolbox",
"args": ["--prebuilt", "alloydb-postgres", "--stdio"],
"env": {
"ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
"ALLOYDB_POSTGRES_REGION": "REGION",
"ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
"ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
"ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
"ALLOYDB_POSTGRES_USER": "USERNAME",
"ALLOYDB_POSTGRES_PASSWORD": "PASSWORD",
"ALLOYDB_POSTGRES_IP_TYPE": "PRIVATE"
}
}
}
}
For reusable project workflows, prefer generated workspace skills over one-off prompts:
toolbox --prebuilt alloydb-postgres skills-generate \
--name alloydb-monitor \
--toolset monitor \
--description "AlloyDB monitoring skill" \
--output-dir .agents/skills
If neither Gemini extensions nor MCP Toolbox are available, fall back to the manual gcloud, Auth Proxy, and SQL workflows already documented in this skill's reference files.
For detailed guides and code examples, refer to the following documents in references/: