Manage a cluster

Everything on this page needs postgrescluster/write on the cluster — the Owner, Contributor and Databases Operator roles have it — except where a section says otherwise. Each change, except stsh pg scale, starts an operation that the cluster's Operations tab follows step by step; see Operations.

Start, stop and restart

The buttons are in the cluster's header:

• Stop and Restart — while the cluster is Running.
• Start — while it is Stopped.

Stop shuts every instance down and keeps the volumes and the configuration; nothing can connect until you start it again. Changing the configuration of a stopped cluster keeps it stopped. Start brings the instances back; with several instances this can take a few minutes.

Restart restarts the instances one at a time, the replicas first and the primary last, so a cluster with more than one instance keeps serving; connections to the primary drop once. A single instance is briefly unavailable. An instance that cannot become ready as it is — one stuck on an image it cannot pull or in a crash loop — is recreated instead of waited for.

stsh pg stop orders-db
stsh pg start orders-db
stsh pg restart orders-db

Change the compute plan

1. On the Configuration tab, section Runtime, pick another Compute Plan. Plans the boundary does not allow, or that no node could run, are shown but cannot be chosen.
2. Choose Save. Change compute plan? shows the plan you are leaving and the one you are moving to, and what applying it costs: with a single instance, "Applying this restarts the database. The instance will be briefly unavailable."; with more, the instances restart in turn and connections to the primary drop once.
3. Choose Change plan.

A plan change sets the CPU and memory of each instance and the number of instances. It does not touch the data volume — grow it on its own, see Grow the storage — and adds a WAL volume only when the cluster has none and the new plan has one. Connection pooling and the PostgreSQL parameters stay as they are; see Derived parameters.

stsh pg update orders-db --set computePlan=large

The response of an update says what it costs in restartImpact — none, restart or rolling — and lists in warnings any part of the change the platform could not make, and the notice of a major upgrade.

Tune resources individually

On the Configuration tab, section Database, Advanced Resource Settings has CPU Request, CPU Limit, Memory Request and Memory Limit for each instance. A limit must be at least its request. The portal takes memory in whole GB; through the API it can be as low as 256Mi. PostgreSQL sizes its memory against the limit, so keep the memory request equal to the limit: below it, the instance can be evicted exactly when it uses the memory it was configured for, and the section says so.

Values that match no plan leave the cluster on Custom, shown as Custom — … under Compute Plan. On Custom, Instances in Runtime can be edited. Picking a plan again replaces the individual values with the plan's.

Change the number of instances

While the cluster follows a plan, Instances is set by the plan: change the plan, or tune the resources individually first. With the CLI, which needs postgrescluster/scale instead of postgrescluster/write:

stsh pg scale orders-db --replicas 3
stsh pg scale orders-db                 # shows the current count

A count between 1 and 10 is accepted, and one that differs from the plan's leaves the cluster on Custom. Adding instances is refused when the storage provider has no room for their volumes. To take the cluster down to no instances, stop it.

Grow the storage

On the Configuration tab, section Database, raise Storage Size and choose Save. The volumes grow in place; the database keeps running. Storage can only be increased: the portal refuses a smaller size, and the CLI and the API keep the current size and say so in warnings.

If the storage provider cannot grow the volumes, the platform keeps the current size, applies the rest of the change and says why. While an earlier grow has not completed, a new size is not applied, and the cluster applies no other change either until the volumes have grown — see What the reasons mean. The storage class cannot be changed.

stsh pg update orders-db --set storageSize=50Gi

Connection pooling

On the Configuration tab, section Database, Connection Pooling (PgBouncer) holds Enable PgBouncer, PgBouncer Instances and Pool Mode. While the cluster follows a compute plan the switch is read-only, and its description reads "Enabled by the <plan> compute plan" whatever its state; on Custom it can be changed.

With the CLI or the API, pooling can be changed at any time:

stsh pg update orders-db --set pgBouncerEnabled=true --set pgBouncerPoolMode=transaction --set pgBouncerInstances=2
stsh pg update orders-db --set pgBouncerEnabled=false

Turning pooling off removes the pooler. If the pooler cannot be set up or removed, the rest of the change is still applied and a warning says so. How applications reach the pooler is described in Through the pooler.

Set PostgreSQL parameters

The portal does not edit PostgreSQL's parameters; the CLI and the API do, through postgresqlParameters:

stsh pg update orders-db --set postgresqlParameters='{"work_mem":"16MB","log_min_duration_statement":"500ms"}'

Your values are merged over the ones the plan derived, parameter by parameter; set a parameter to null to remove your value. The platform refuses a value PostgreSQL would reject at start-up, and a change to a parameter that only takes effect on a restart — max_connections or shared_buffers, for example — restarts the instances. The rules are in Parameters you can set.

Monitoring and backups

Monitoring & Backup on the Configuration tab, section Database, holds Enable Monitoring and the backup settings. Turning backups on and off is described in Turn on backups.

Upgrade the major version

The portal shows PostgreSQL Version as fixed. The CLI and the API accept a higher major version, up to 17:

stsh pg update orders-db --set postgresVersion=17

Warning

A major upgrade stops every instance, the primary included, while it runs, and it is one-way: the cluster cannot be moved back to the old version. Take a snapshot first — see Take and restore snapshots.

Revisions

Viewing the history needs only postgrescluster/read. The Revisions tab lists every change to the cluster's configuration, who made it, and — with View changes — what changed. PostgreSQL clusters offer no rollback from it; make the change again instead.

Delete a cluster

Deleting needs postgrescluster/delete, which postgrescluster/write includes: the Owner, Contributor and Databases Operator roles have it. On the Danger Zone tab choose Delete, type the cluster's name and choose Delete Permanently. With the CLI, which asks first:

stsh pg delete orders-db

The instances, their volumes, the pooler and the backup schedule go with the cluster, and so does the data. Backups already in the backup store are not deleted, but nothing in the portal or the CLI can restore them once the cluster is gone.