AlloyDB for PostgreSQL

Both services run community PostgreSQL semantics, so applications, drivers, ORMs and most extensions move between them without code changes. The differences are in the engine around PostgreSQL:

The AlloyDB Admin API is alloydb.googleapis.com. Instances do not have a public IP unless you explicitly enable public IP on an instance; the default and recommended path is private connectivity.

The catalog-api workload runs as a dedicated service account (see Identity and Access). It receives roles/alloydb.client, roles/alloydb.databaseUser and roles/serviceusage.serviceUsageConsumer on the project, and nothing broader. Downloaded service-account keys are not needed: Cloud Run, Compute Engine and GKE attach a service account to the workload and the connector uses Application Default Credentials. See AlloyDB IAM roles and permissions.

New customers and existing customers who have not yet used it can create a 30-day free trial cluster: a cluster with a single primary instance of limited size and storage, with no charge during the trial. Choose Free trial cluster when creating a cluster in the console, or pass --subscription-type=TRIAL on the CLI. At the end of the trial the cluster is upgraded to a standard cluster (billing starts) or deleted, depending on your choice, and the trial is not available for every organisation or region, so confirm the terms on the free trial page before relying on it. Trial clusters are meant for evaluation, not for production data.

An AlloyDB cluster is reachable only from private addresses, so decide the connectivity model before creating it.

See Instance configuration and AlloyDB database flags.

Connect through the Auth Proxy and create the database, extensions and a small catalog table that later sections reuse.

See Supported database extensions for the list of extensions per version. The postgres superuser in AlloyDB is not a full PostgreSQL superuser: it has the alloydbsuperuser role, which is sufficient for the extensions above.

The columnar engine keeps a copy of selected table columns in memory in a compressed column-oriented layout, and the planner chooses it automatically when a query scans many rows and touches few columns. The copy is maintained as rows change, so results are always consistent with the row store. It is most useful for aggregations over large tables, such as the nightly sales report in the Bookshelf scenario, and does little for primary-key lookups.

A read pool is a second instance in the same cluster, of type READ_POOL, with 1 to 20 nodes, each running its own PostgreSQL and buffer cache over the shared storage. Clients connect to one read pool endpoint (a private IP or a PSC attachment) and connections are load-balanced across the nodes. Replica lag is typically small because there is no data copy: reads see changes after the WAL is applied to storage, and the pool still serves possibly slightly stale data, so read-your-writes after a write must go to the primary. You can have several read pools in one cluster, for example one for the application and a bigger one with the columnar engine for reporting.

AlloyDB supports the pgvector extension, including its HNSW and IVFFlat indexes (see PostgreSQL & pgvector), and adds the ScaNN index (Scalable Nearest Neighbors), the algorithm that Google uses for its own search and recommendation systems. ScaNN builds a tree of quantised partitions with a compact in-memory representation, which gives faster index builds, much smaller indexes and higher query throughput than HNSW on large vector sets, and lets filters combine with the vector search. Concepts such as recall versus speed are explained in ANN Indexes: Flat, IVF, HNSW and Beyond; a cross-product view is in Comparing Vector Databases.

AlloyDB protects data in three layers, all stored outside the instances so they never affect compute.

A secondary cluster is an asynchronously replicated, read-only cluster in another region that serves disaster recovery and distant readers. It has its own storage, so a regional outage does not affect it. Promoting it makes it an independent writable cluster, with typically seconds of data loss bounded by replication lag.

See Work with cross-region replication. A planned role swap (switchover) keeps the old primary as a secondary; after a promotion the former primary is not rejoined automatically. Applications need their own failover step (new connection name, DNS or configuration), which is covered with the multi-region patterns in Architecture, Migration and Multicloud.

In-place major version upgrades keep the cluster, endpoints and IAM, and run pg_upgrade on the storage layer, causing an outage of minutes while instances restart. Upgrade a copy first: restore a backup into a throwaway cluster, upgrade it, and run your tests.

See gcloud alloydb clusters upgrade and Upgrade a cluster’s major version. Older majors reach end of support (check the version support policy) and, once unsupported, are upgraded for you, so plan an upgrade to PostgreSQL 18 before then. Minor-version maintenance runs in the maintenance window.

AlloyDB Omni is a downloadable edition of the AlloyDB engine for PostgreSQL that you run yourself: in a container on a laptop, a VM, your data centre or another cloud, or on Kubernetes using the AlloyDB Omni Kubernetes operator. It includes the columnar engine, ScaNN and the AI integration, so developers can build against the same features without a cloud cluster. It is self-managed: you handle backups, high availability, upgrades and patching, though the operator automates much of that on Kubernetes, and a separate offering manages Omni on Google Distributed Cloud. A developer edition is free for development use; production needs a licence, so check the terms.

See AlloyDB Omni quickstart and AlloyDB Omni overview. Pin an explicit image tag in anything beyond a local experiment. The same Omni image is a good way to run integration tests for catalog-api in CI, in the way the site describes for containers in Docker.

The catalog-api repository (package com.example.bookshelf) uses a plain JDBC datasource through the connector shown above, so no AlloyDB-specific API is needed. A repository class using JdbcClient runs the vector query:

Spring Boot with the Google Cloud Client Libraries uses Application Default Credentials, so the same code runs locally (gcloud auth application-default login with impersonation of the application service account) and on Cloud Run with its attached service account. Spring Cloud GCP (8.x for Spring Boot 4, 7.4.x for Spring Boot 3) provides the Cloud SQL starters; for AlloyDB the connector above is the supported path. See Java connector usage and Configuration and Profiles.

AlloyDB emits metrics to Cloud Monitoring (CPU, memory, connections, replication lag, columnar engine memory, storage used) and logs PostgreSQL output to Cloud Logging; set alerting policies for CPU above a threshold, connection counts near max_connections, and replica lag (Monitoring and Observability). Query insights shows the slowest queries, with tags to link them to application code, and the System insights dashboard shows instance health.

AlloyDB charges for: provisioned vCPU and memory per instance (including each read pool node) billed per second, storage used (billed on actual usage, not provisioned), backup and PITR storage, network egress and cross-region replication traffic, and optional features such as extended support for old versions. Committed use discounts reduce instance charges for steady workloads, and a free trial cluster covers evaluation for 30 days. Costs are driven mostly by instance size and node count, so right-size from Query Insights and Cloud Monitoring, scale read pools down when idle and delete test clusters promptly. Prices are not quoted here because they change by region and edition; see the AlloyDB pricing page and the pricing calculator (Cost Management and Billing).

AlloyDB clusters bill continuously while they exist, and backups survive cluster deletion. Delete in dependency order: read pools and secondary instances, then primaries, then clusters, then backups, then network pieces. If you used a throwaway project, gcloud projects delete "$PROJECT_ID" removes everything after a 30-day recovery window.

Derived from gcloud alloydb clusters delete, gcloud alloydb instances delete and gcloud alloydb backups delete. Automated and continuous backups of a deleted cluster expire according to their retention, while on-demand backups stay until deleted; the console lists them under Backups. Also remove the PSC forwarding rule and reserved internal address if you used Private Service Connect, the IAM bindings granted above, and the Terraform state if you provisioned with it.