What Is Cloud SQL? Managed PostgreSQL on Google Cloud Explained
Cloud SQL is Google Cloud's managed relational database service. What it runs for you, how high availability, backups and private IP work, how applications connect, and how a backend gets a Cloud SQL Postgres database from code.
Cloud SQL is the managed relational database service on Google Cloud, and Cloud SQL for PostgreSQL is what most GCP backends use for their primary database. You choose a version, machine size, storage and region, and Google runs the instance, its backups, patching and failover.
Cloud SQL for PostgreSQL runs standard PostgreSQL, so existing drivers, ORMs and SQL work unchanged, while some superuser features are restricted and extensions are limited to the ones Google supports. This guide covers what Cloud SQL manages, how high availability, backups and point-in-time recovery work, how applications connect, and how to get a Cloud SQL database from application code with Encore (infrastructure from code).
Cloud SQL at a glance
How Cloud SQL works
A Cloud SQL instance is a VM managed by Google with attached storage that can grow automatically. With the high availability configuration, Cloud SQL keeps a standby in another zone of the same region with synchronously replicated storage and fails over to it if the primary zone or instance fails, keeping the same IP. Read replicas are separate instances that serve read traffic, in the same or other regions. The Cloud SQL overview lists supported versions and features.
Automated backups run daily, and with point-in-time recovery enabled Cloud SQL keeps write-ahead logs so you can restore to a specific moment within the retention window. A point-in-time restore creates a new instance, which the application then needs to be pointed at.
Connecting from your application
Most setups use one of three connection paths: a private IP places the instance on your VPC through private services access, so Cloud Run, GKE or Compute Engine connect over internal addresses. A public IP with authorized networks works but exposes the instance to the internet. The Cloud SQL Auth Proxy and the language connectors authorize connections with IAM and encrypt them, which avoids managing SSL certificates and IP allowlists and is the usual way to connect from a laptop.
Cloud Run instances each hold their own connection pool, so a service that scales to many instances can exhaust max_connections. Sizing pools per instance and capping the maximum instance count are part of running Cloud SQL behind Cloud Run.
Cloud SQL editions
Cloud SQL for PostgreSQL comes in two editions, compared in the Cloud SQL editions overview. Enterprise is the general purpose edition with a 99.95% availability SLA that excludes maintenance, up to 7 days of point-in-time log retention and maintenance that takes a few minutes of downtime. Enterprise Plus adds a 99.99% SLA that includes maintenance, sub-second downtime for maintenance and planned operations, a data cache on local SSD for faster reads, read pools, up to 35 days of point-in-time log retention and advanced disaster recovery.
An existing instance can be moved between editions with an in-place upgrade, so starting on Enterprise and moving a production database to Enterprise Plus later does not require a migration.
How Encore provisions Cloud SQL
Encore is infrastructure from code for TypeScript and Go, with a platform that provisions and deploys into your own AWS or GCP account. On GCP, a database declared in code becomes a Cloud SQL for PostgreSQL instance in the environment's dedicated project, with daily backups kept for 7 days, point-in-time recovery and placement on a private network, as described in the GCP infrastructure docs.
Set up the app
Run in your terminal to get started locally.
The database is declared in the service that owns it:
// invoices/encore.service.ts
import { Service } from "encore.dev/service";
export default new Service("invoices");
// invoices/invoices.ts
import { api } from "encore.dev/api";
import { SQLDatabase } from "encore.dev/storage/sqldb";
// Cloud SQL for PostgreSQL on GCP, a local Postgres under encore run.
const db = new SQLDatabase("invoices", { migrations: "./migrations" });
interface Invoice {
id: number;
customer: string;
amountCents: number;
}
export const create = api(
{ expose: true, method: "POST", path: "/invoices" },
async (p: { customer: string; amountCents: number }): Promise<Invoice> => {
const row = await db.queryRow<{ id: number }>`
INSERT INTO invoices (customer, amount_cents)
VALUES (${p.customer}, ${p.amountCents}) RETURNING id`;
return { id: row!.id, ...p };
},
);
encore run starts Postgres locally and applies the SQL files in migrations, so there is no Auth Proxy to run during development. On deploy, Encore creates the Cloud SQL instance, applies migrations, and injects the connection details at runtime, so there is no connection string or password in the repo. Query APIs are in the TypeScript database docs, and an existing instance can be attached with import a Cloud SQL instance.
Good to know
- Cloud SQL storage can grow automatically but never shrinks, so start small.
- Enable point-in-time recovery before you need it, since it cannot recover past changes made before it was turned on.
- Plan connection pools around the maximum instance count of each Cloud Run service.
Related guides
Frequently asked questions
What is Cloud SQL used for?
Cloud SQL runs managed relational databases such as PostgreSQL on Google Cloud. Google handles the VM, storage, automated backups, patching and failover, while you manage schemas, queries, connection handling and instance sizing.
Is Cloud SQL the same as PostgreSQL?
Cloud SQL for PostgreSQL runs standard PostgreSQL, so drivers, ORMs and SQL work unchanged. Some superuser features are restricted, and extensions are limited to the list Google supports.
How do applications connect to Cloud SQL?
Applications connect over a private IP inside a VPC, over a public IP with authorized networks, or through the Cloud SQL Auth Proxy and language connectors, which use IAM to authorize and encrypt connections without managing SSL certificates or IP allowlists.
How do I create a Cloud SQL database for a TypeScript backend without Terraform?
With Encore, declare the database with new SQLDatabase() from encore.dev/storage/sqldb and a migrations folder, then query it with db.queryRow. encore run starts Postgres locally, and deploying to GCP creates a Cloud SQL for PostgreSQL instance on a private network with daily backups and point-in-time recovery.
Deploy to your cloud on AWS and Google Cloud
without managing infrastructure
Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.
