PostgreSQL¶
The PostgreSQL service runs PostgreSQL databases for you on your organization's infrastructure. You pick a tier, a version and a disk size; the platform provisions the database and handles resizing, version upgrades, high availability and monitoring.
Each instance is one PostgreSQL server (with replicas if you turn on high availability) holding one database you name. Under the hood it runs on the CloudNativePG operator on a Kubernetes cluster, either one the platform creates or one your organization runs. That cluster is managed by your organization administrator; you only ever work with the instance, and this page uses "cluster" only where it explains where your instance runs.
Your instances are under MANAGED SERVICES > PostgreSQL in the console.
Key features¶
- Tiers: pick from compute shapes (CPU and memory per replica) your organization administrator offers.
- High availability: optionally run three replicas so the database stays up if one fails.
- Resizing: change tier, grow the disk, or turn high availability on or off.
- Version upgrades: move an instance to a newer PostgreSQL version.
- Live credentials: read connection details when you need them; the platform never stores your password.
- Metrics: availability, connections, database size, transactions and replication lag.
Before you start¶
An organization administrator must set up PostgreSQL databases on a service config of the infrastructure, add at least one tier and offer it to users. See PostgreSQL databases. Service configs that can't take an instance yet are shown disabled in the create form, with the reason.
You also need quota and permissions.
Tiers¶
A tier sets the CPU and memory each replica gets, and the kind of storage (storage class) its disks use. Your organization administrator defines the tiers per service config; the storage class is their choice and isn't shown to you. You choose the disk size yourself.
An instance can later move only to tiers that use the same storage class as its current one; the Resize dialog lists only those. The instance keeps the CPU and memory it was created or resized with, so the administrator adding or removing tiers never changes a running database. A tier can't be removed while instances use it.
Create an instance¶
- Go to MANAGED SERVICES > PostgreSQL and click Create Instance.
- Choose the project, the infrastructure and a service config that offers PostgreSQL. A name is optional; an instance without one is shown by its ID.
- Choose the Tier and the PostgreSQL version. One version is offered per PostgreSQL major (for example
16.10); which majors depends on the service config. - Set Storage (GiB), the disk size per replica: 20 GiB by default, and it can only grow later. With high availability, each of the three replicas gets its own disk of this size.
- Turn on High availability to run three replicas instead of one. Monitoring is on by default.
- Optionally expand Database to name the database (default
app) and its owner role (defaultadmin). The owner owns the database but isn't a PostgreSQL superuser. - Review and click Create PostgreSQL instance.
Database and owner names are permanent
Use 1 to 63 lowercase letters, digits and underscores, not starting with a digit (for example orders_db). postgres, streaming_replica, template0, template1 and names starting with pg_ or cnpg_ are reserved.
The instance goes through Pending and Creating to Active.
Connect to your database¶
The instance's Overview tab shows the host, port, database and user. To get the password too, open the Connection tab and click Load Connection Details. You get each value with a copy button and a ready-made postgresql://… connection string.
The host is an address the cluster's load balancer gives your instance, and the connection details can be loaded once it has been assigned. On a Fully managed setup it is an address on the infrastructure's external network, so treat it as reachable from outside your organization: the platform doesn't restrict which clients can connect, so keep the password safe. The server accepts encrypted (TLS) connections with a certificate the platform doesn't publish, so clients can encrypt the connection but can't verify the server.
Credentials are read live each time and never stored by the platform. Refresh credentials reads them again; it doesn't change the password.
You connect as the database's owner role. The platform has no way to rotate the password or add other database users.
The connection details are a credential
They give full access to your database. Handle them like any other secret. Reading them needs its own permission (see Permissions).
Change an instance¶
Changes are under Available Operations on the Overview tab. They work while the instance is Active or Degraded, one at a time: while a change runs the instance shows Updating, and you can cancel it from Action History.
Resize¶
Resize changes any of:
- Tier: only tiers on the same storage class are offered.
- Storage (GiB): the disk per replica. It can only grow.
- High availability: three replicas or one.
Resizing restarts the database
Replicas restart while the change rolls out, so connections may drop for several minutes. Without high availability there is no standby, so expect a short outage.
Growing the disk or turning on high availability can be refused if the tier's storage class no longer exists on the cluster or can't grow volumes. Ask your organization administrator.
Upgrade the PostgreSQL version¶
Upgrade offers only versions newer than the current one. A newer major version, or a newer minor of your current major once the service config offers it, is an upgrade you start yourself.
Upgrades are one-way
PostgreSQL can't be downgraded. The database restarts during the upgrade, so connections may drop, and it can take several minutes.
Name and description¶
Edit changes the name and description.
What you can't change¶
The project, infrastructure, service config, database name and owner are fixed. To change any of them, create a new instance. Instances can't be shared with other projects.
If your organization administrator stops offering PostgreSQL on a service config, only new instances are blocked; existing ones keep running and can still be changed and deleted.
Backups¶
The platform doesn't back up PostgreSQL instances, and it has no point-in-time recovery or export. Deleting an instance, or losing its disks, loses the data. Take your own backups, for example with pg_dump over the connection details above, and store them outside the platform.
Monitoring and metrics¶
With monitoring on, the Metrics tab charts availability, active connections, database size, transactions and (with high availability) replication lag over the last 1 hour to 7 days. It's on by default; switch it with Enable Monitoring / Disable Monitoring. This re-applies the instance but never touches your data. The first data points take a few minutes to appear.
If the instance runs on a cluster your organization operates and the charts stay at No data yet, that cluster may not be able to reach the platform's metrics collector; ask your organization administrator.
Delete an instance¶
Click Delete on the instance's page and confirm. Deleting removes the database and all its data permanently. You can delete an instance while it is Active, Degraded or in Error.
Lifecycle states¶
Instances use the resource statuses. A Degraded instance may not match its configuration: run Sync to re-apply it. An instance in Error can only be deleted.
Quotas¶
Each instance uses one postgresql-instances unit until it is deleted, whatever its tier, disk or high availability. See Resource Quotas.
Permissions¶
| Task | Permission |
|---|---|
| Find instances in the list | postgresql_instance_list |
| See an instance without its credentials | postgresql_instance_metadata_get |
| Read the connection details | postgresql_instance_connection_get |
| See metrics | postgresql_instance_metrics_get |
| Create | postgresql_instance_create |
| Resize | postgresql_instance_resize_update |
| Upgrade | postgresql_instance_upgrade_update |
| Switch monitoring | postgresql_instance_monitoring_update |
| Edit name and description | postgresql_instance_metadata_update |
| Sync, cancel an action | postgresql_instance_action_update |
| Delete | postgresql_instance_delete |
postgresql_instance_get includes the metadata, connection and metrics reads; postgresql_instance_update includes every change. The create and resize forms load tiers and versions with postgresql_instance_metadata_get, and the create form also needs some organization-level permissions to pick where the instance runs: see What project members typically need. Full list: Permissions Reference.