Cloud SQL

The authoritative list of supported versions, their end-of-life dates and the default for new instances is the database versions and version policies page; the exact version strings used by --database-version (for example POSTGRES_18, MYSQL_8_4, SQLSERVER_2022_STANDARD) are listed by gcloud sql tiers list and the create reference.

Cloud SQL has two editions for PostgreSQL and MySQL. SQL Server instances use Enterprise and Enterprise Plus as well.

Choose Enterprise for development, tests and low-traffic services where a minute of maintenance downtime is acceptable and cost matters most; choose Enterprise Plus for production services that need the higher SLA, longer PITR window or data cache. An edition can be changed later with gcloud sql instances patch --edition (an instance restart is needed when the machine family changes). The exact tier names available in a region come from gcloud sql tiers list; do not hard-code a tier from a blog post.

Derived from Introduction to Cloud SQL editions and Instance settings.

A Cloud SQL instance runs in a Google-managed project, not in yours. Your applications reach it through one of three network paths, and then authenticate with a database password or with IAM.

A single instance can have both a public and a private address, and (for PSC) can have --no-assign-ip set so that it has no public address at all. The organization policy constraint constraints/sql.restrictPublicIp enforces this.

The commands below assume a project with billing and the shell variables below. Enable the APIs once:

Derived from Create instances and Enable and disable services.

Derived from Configure private services access.

The database password lives in Secret Manager as catalog-db-password, never in a command line, a YAML file or the repository (the secrets service is described in Secret Manager and Cloud KMS):

Derived from Create and access secrets.

The DB_PASSWORD shell variable holds the value only for the current shell session; never echo it or commit it.

Which connection method to use depends on where the client runs and on whether you prefer a library or a separate process. All of them use IAM to authorize the connection and encrypt the traffic, whatever the network path.

Cloud SQL distinguishes the built-in database users from IAM principals.

Derived from Manage IAM users and groups.

With IAM database authentication nobody keeps a database password: the client presents an OAuth 2.0 access token, which Cloud SQL validates against IAM, and access is revoked by removing the IAM role. The steps for the Bookshelf service account are:

Then grant the database privileges inside PostgreSQL, because IAM only controls the login:

Derived from Log in using IAM database authentication.

Clients enable it with the connector flag enableIamAuth=true (JDBC) or with the proxy’s --auto-iam-authn. A human can log in with gcloud sql connect "$INSTANCE" --user=alice@example.com --database=catalog after the gcloud account is the same IAM user. IAM tokens are valid for about an hour; the connector refreshes them before a new connection is opened, so a long-lived pooled connection continues to work until it is closed, but the pool must replace connections regularly (max-lifetime in Hikari). Built-in users remain necessary for tools that cannot present tokens.

A regional instance (--availability-type=REGIONAL) keeps a standby in a second zone of the same region. Data is written synchronously to a regional persistent disk, so a zone failure promotes the standby with no data loss. The instance keeps one stable IP address and connection name, but connections are dropped and clients must reconnect; applications need connection retries and short pool lifetimes.

Derived from High availability and Configure high availability.

High availability protects against zone failures and some maintenance, not against dropped tables, corrupt data or a regional outage. Backups and cross-region replicas cover those cases. Plan failover tests the way you plan restore tests.

A read replica is a read-only copy kept in sync asynchronously. Use replicas to offload reporting and read-heavy queries, to place data near users in another region and to prepare disaster recovery.

Derived from Create read replicas, Cross-region replicas and Perform a switchover.

Replication lag is asynchronous and shown in Cloud Monitoring (database/replication/replica_lag); reads from a replica can be stale, so route only tolerant queries there. Promotion is for disaster recovery: after promotion the old primary is no longer a source. With Enterprise Plus, advanced disaster recovery gives a switchover and replica failover that keep the original topology intact (the old primary becomes a replica), so a regional drill does not require rebuilding. A read replica has its own connection name and IP; Spring can route reads to it with a second DataSource or a routing data source (see Spring Data JPA).

Cloud SQL provides two layers of protection that you should both understand:

PostgreSQL extensions are installed per database by a user with the cloudsqlsuperuser role. The set of supported extensions depends on the major version (see the supported extensions page).

Derived from Work with vector embeddings in Cloud SQL and the pgvector documentation. The vector types, distance operators, HNSW and IVFFlat tuning are explained in PostgreSQL & pgvector, and the comparison with other vector stores is in Comparing Vector Databases. The vector extension keeps the index in memory-oriented storage, so size the instance memory for the index, and consider AlloyDB with ScaNN when the corpus becomes large. The ellipsis in the query stands for the remaining vector components, which an application supplies as a parameter. Newer versions also offer full-text-search related extensions such as pg_textsearch; check the extensions page for the availability on your version. MySQL 9.7 adds native vector data types and distance functions at the SQL level; see the MySQL vector documentation for their syntax.

Database flags tune the engine without SSH access. Use gcloud sql flags list --database-version=POSTGRES_18 to see the supported ones and gcloud sql instances patch "$INSTANCE" --database-flags=max_connections=200,log_min_duration_statement=500 to set them. The patch replaces the whole list, so always send every flag that should remain. Some flags restart the instance.

Managed Connection Pooling (Enterprise Plus, PostgreSQL) puts a pooler in front of the database, so thousands of short-lived client connections share a smaller set of server connections without running PgBouncer yourself. Enable it from the instance’s Connections settings in the console or with the gcloud sql instances patch pooling flags (check gcloud sql instances patch --help for the current spelling) and connect to the pooler port documented on the page below. Transaction pooling does not keep session state, so features such as session-level advisory locks, SET without LOCAL and prepared statements behave differently, and the application should keep its own small Hikari pool. This feature is the answer to a Cloud Run fleet that would otherwise exhaust max_connections.

Derived from Managed Connection Pooling.

Derived from About maintenance, Use Query insights and Monitor instances.

Cloud SQL bills vCPU and memory per hour (doubled for the standby of a regional instance, higher per vCPU on Enterprise Plus, with the SQL Server license included), storage per GB-month (a regional instance pays for the standby too, and auto-increase never shrinks), backup storage beyond the free allowance (retained backups keep billing after the instance is deleted), network egress between regions and to the internet, and extended support for end-of-life major versions. Committed use discounts apply to compute. Stopping an instance (gcloud sql instances patch "$INSTANCE" --activation-policy=NEVER) stops compute charges, but storage and backups keep billing, so deleting is the only way to stop all charges. Current prices are on the pricing page; instance quotas and limits are on the quotas and limits page.

This sequence takes catalog-api from nothing to a running service on a private, IAM-authenticated, regional instance:

With a password instead of IAM, mount catalog-db-password as DB_PASSWORD (see Connecting). The entities and Spring Data repositories of catalog-api are ordinary JPA code (see Spring Data JPA); nothing in them is specific to Cloud SQL, which is the point of a managed PostgreSQL. The SQL language itself is covered by the SQL reference.

Derived from Diagnose issues and Auth Proxy troubleshooting.

Delete in dependency order: replicas first (a primary cannot be deleted while it has replicas), then the primary. Turn off deletion protection before deleting. Decide on purpose whether the retained and final backups should survive; for a throwaway lab, delete them as well.

Derived from Delete an instance, Retained backups and gcloud sql backups delete.

Skip the commands for resources you did not create. Delete the VPC peering only when no other managed service (for example Memorystore or AlloyDB) uses the same private range. A deleted instance’s name cannot be reused for up to a week, so use a new name for a quick re-creation. Backups made by Backup and DR Service follow the vault’s retention and may not be deletable until it expires. For a throwaway project, deleting the project removes everything, with the usual 30-day recovery window (see Resource Hierarchy and Projects).