Help us improve
Share bugs, ideas, or general feedback.
From flow
Guides deploying and operating AlloyDB Omni on Docker, Podman, Kubernetes, or RPM for local dev, on-premises, or non-GCP environments. Covers connections, tuning, persistence, and columnar engine testing.
npx claudepluginhub cofin/flow --plugin flowHow this skill is triggered — by the user, by Claude, or both
Slash command
/flow:alloydb-omniThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
AlloyDB Omni is the downloadable edition of AlloyDB that runs anywhere: local machines, on-premises data centers, or other cloud providers. It is distributed as a container image and includes the same query processing and columnar engine as the managed AlloyDB service.
Guides provisioning Google AlloyDB clusters, read pools, columnar engine, Private Service Access, PostgreSQL tuning on GCP, and Cloud SQL migrations.
Discovers available and installed PostgreSQL extensions, lists memory configurations and pg_settings, queries server state and connections, and retrieves AlloyDB cluster details for tuning.
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 Omni is the downloadable edition of AlloyDB that runs anywhere: local machines, on-premises data centers, or other cloud providers. It is distributed as a container image and includes the same query processing and columnar engine as the managed AlloyDB service.
Use this skill in three distinct layers:
Keep those layers separate when giving guidance. Deployment is not the same thing as agent connectivity.
| Method | Image | Use Case |
|---|---|---|
| Docker | google/alloydbomni:latest | Local development, CI |
| Podman | google/alloydbomni:latest | Rootless containers, RHEL |
| Kubernetes | AlloyDB Omni Operator | Production on-prem/multi-cloud |
| RPM | alloydbomni package | Bare metal / VM (RHEL/CentOS) |
| Variable | Purpose | Example |
|---|---|---|
POSTGRES_PASSWORD | Initial superuser password (required) | mysecretpassword |
POSTGRES_DB | Database to create on first start | myapp |
POSTGRES_USER | Superuser name (default: postgres) | postgres |
docker compose up -dpsql -h localhost -U postgresdocker compose down (data persists in named volume)Use Docker/Podman for local development and CI. Use the Kubernetes operator for production non-GCP deployments. Use RPM for bare-metal servers.
Set --memory, --cpus, and --shm-size based on workload. For development, 2 CPUs / 4GB RAM / 256MB shared memory is a reasonable starting point.
Always use a named volume for /var/lib/postgresql/data. Without a volume, data is lost when the container stops. Optionally mount ./init-scripts to /docker-entrypoint-initdb.d for first-run SQL.
For non-trivial workloads, configure shared_buffers (25% of container memory), effective_cache_size (75%), and work_mem via ALTER SYSTEM SET or a mounted config file.
Connect via localhost:5432. AlloyDB Omni supports all AlloyDB features including the columnar engine, so you can test analytical queries locally.
Use the lowest-admin supported path for the current host, and degrade cleanly:
alloydb-omni extension.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 deployment and operational guidance in this skill must still work across other agents and plain terminal workflows.
--memory and --cpus, the container can consume all host resources and destabilize the machineshm_size to at least 256MB — the default 64MB is too small for PostgreSQL and causes "could not resize shared memory segment" errorsPOSTGRES_PASSWORD in production — use secrets management (Docker secrets, Kubernetes secrets, or Vault)pg_dump or volume snapshots; there is no managed backup like GCP AlloyDBgoogle/alloydbomni:latest can change between runs; use a specific version tag for reproducibilityBefore delivering configurations, verify:
shm_size is set to at least 256MBPOSTGRES_PASSWORD is set (container will not start without it)Docker Compose for local AlloyDB Omni development:
# docker-compose.yml
services:
alloydb:
image: google/alloydbomni:latest
container_name: alloydb-omni
environment:
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-devsecret}
POSTGRES_DB: myapp
POSTGRES_USER: postgres
ports:
- "5432:5432"
volumes:
- alloydb-data:/var/lib/postgresql/data
- ./init-scripts:/docker-entrypoint-initdb.d
restart: unless-stopped
shm_size: "256m"
deploy:
resources:
limits:
cpus: "2"
memory: 4G
volumes:
alloydb-data:
Initialization script to enable the columnar engine:
-- init-scripts/01-extensions.sql
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS google_ml_integration;
The AlloyDB Omni Kubernetes Operator manages DBCluster custom resources (CRD: dbclusters.alloydbomni.dbadmin.goog/v1). Key lifecycle operations:
availabilityOptions.standby: Enabled in primarySpec; the operator promotes the standby automatically on primary failurekubectl patch dbcluster <name> --type=merge -p '{"spec":{"readPoolSpec":{"replicas":<N>}}}'primarySpec.parameters triggers a controlled rolling restart with no data lossalloydbomni.dbadmin.goog/backup=true to trigger an immediate backupdatabaseVersion or the image tag; the operator orchestrates a rolling restartSee references/kubernetes-operator.md for the full CRD spec, HA configuration YAML, scaling examples, health monitoring, and upgrade procedures.
RPM-based AlloyDB Omni installs are a first-class deployment path for RHEL-family hosts, VMs, and bare-metal systems where containers are not the right fit.
Key lifecycle operations:
yum install alloydbomnialloydb-omni init --data-dir=... before first startsystemctl enable --now alloydb-omni, status, restart, and journalctlALTER SYSTEM SET ... and restart the serviceSee references/rpm.md for the full install, service-management, configuration, validation, and upgrade workflow.
Key diagnostics for AlloyDB Omni production workloads:
EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT) to identify sequential scans, high-cost nodes, and buffer hit ratiospg_class JOIN pg_index where indisvalid = false to find indexes that need rebuilding with REINDEX CONCURRENTLYpg_stat_user_tables for n_dead_tup and n_live_tup ratios; tables with dead-tuple ratio above 20% are candidates for VACUUM ANALYZEpg_stat_activity filtered on state = 'active' and wait_event_type to identify lock waits and long-running queriesSee references/performance.md for ready-to-run diagnostic queries, autovacuum tuning, and connection lifecycle management.
The columnar engine accelerates analytical queries by caching selected columns in a compressed in-memory format.
google_columnar_engine.memory_limit (e.g., ALTER SYSTEM SET google_columnar_engine.memory_limit = '4GB') — allocate 10–25% of total container/node memorySELECT google_columnar_engine_add('<table>') or individual column-level populationEXPLAIN output before and after adding a table — look for Custom Scan (columnar scan) nodes replacing Seq ScanSELECT * FROM g_columnar_memory_usage shows per-relation memory consumption and hit ratesThis section is for the connection layer, not for deploying AlloyDB Omni itself.
For AlloyDB Omni, prefer the dedicated Gemini CLI extension when Gemini is the active host. Use the generic PostgreSQL route only as a fallback when the dedicated extension is unavailable.
gemini extensions install https://github.com/gemini-cli-extensions/alloydb-omni --auto-update
gemini extensions config alloydb-omni --scope workspace
Guide the user through the required connection variables before starting Gemini:
export ALLOYDB_OMNI_HOST="<database-host>"
export ALLOYDB_OMNI_PORT="<database-port>"
export ALLOYDB_OMNI_DATABASE="<database-name>"
export ALLOYDB_OMNI_USER="<database-user>"
export ALLOYDB_OMNI_PASSWORD="<database-password>"
export ALLOYDB_OMNI_QUERY_PARAMS="<optional-query-string>"
Important configuration guidance:
v0.6.0 or newer..env file when possible.For non-Gemini agents, or when the user needs a shared MCP endpoint, guide them to MCP Toolbox using the AlloyDB Omni prebuilt config rather than inventing a custom setup.
For reusable project workflows, prefer generated workspace skills:
toolbox --prebuilt alloydb-omni skills-generate \
--name alloydb-omni-optimize \
--toolset optimize \
--description "AlloyDB Omni optimization skill" \
--output-dir .agents/skills
If neither Gemini extensions nor MCP Toolbox are available, fall back to the manual Docker/Podman/Kubernetes/RPM workflows and psql diagnostics already documented in this skill's references.
For detailed guides and code examples, refer to the following documents in references/:
systemd lifecycle, configuration, upgrades, and operational validation.