PostgreSQLUsers

Create a cluster

Create a PostgreSQL cluster in the portal — name and placement, version and database, compute plan, storage and instances, pooling, backups and monitoring — or with the CLI or the API.

Requires: postgrescluster/write

Creating a cluster needs the postgrescluster/write permission in the resource group; the Owner, Contributor and Databases Operator roles have it.

Open the wizard

In the portal at https://portal.example.com, open PostgreSQL in the sidebar and choose Create PostgreSQL Databases. The Create PostgreSQL Database Cluster wizard has six steps: Basics, Database Configuration, Resources, Backup, Monitoring and Review & Create. Next checks a step before it moves on, and Submit on the last step creates the cluster.

Basics

PostgreSQL Server Name — 3 to 50 characters: lowercase letters, digits and hyphens, not starting or ending with a hyphen, and unique in the resource group. The name cannot be changed later; the cluster's in-cluster addresses are made from it, such as <name>-rw for the primary.
Boundary, Cluster and Resource group — where the cluster runs. Each is filled in for you when there is only one choice.

Database Configuration

PostgreSQL Version — the major version: 13, 14, 15 or 16. The default is 16.
Database Name — the database the cluster is created with: a lowercase letter first, then lowercase letters, digits and underscores, at most 63 characters. It is also the name of the user that owns the database and that the connection string logs in as.

Neither can be changed in the portal afterwards. The version can be raised later through the API — see Upgrade the major version.

Resources

The compute plan — one card per plan, with its CPU, memory and description. Picking a plan fills in the instance count and the storage size below, and sets the CPU and memory of each instance. The plans are listed in Compute plans and parameters. When the boundary restricts which plans may be used, the others are shown but cannot be chosen, with the reason. A plan that no node of the cluster could run is refused when you submit, with the reason.
Storage Size — the size of each instance's data volume, in whole GB. It can be increased later, never decreased.

Under Advanced:

Number of Instances — 1 to 10. It starts at the plan's count; with more than one, a replica takes over when the primary fails. A count other than the plan's leaves the cluster on no plan — Custom — see Tune resources individually.
Enable PgBouncer — runs a PgBouncer connection pooler in front of the primary. It is off unless you turn it on here, whichever plan you picked. With it on, set PgBouncer Instances (1 to 5) and the Pool Mode: Session (the default), Transaction or Statement. How applications use the pooler is described in Through the pooler.

Tip

Decide on pooling here. Once the cluster runs on a plan, the Enable PgBouncer switch in its configuration is read-only in the portal — see Connection pooling.

Each instance also gets a separate volume for the write-ahead log on every plan but nano; its size comes from the plan.

Backup

Enable Backups — off by default. With it on, the cluster archives to the platform's backup store and takes a scheduled snapshot; see Backups and point-in-time recovery. Backups need a backup target set up by the platform's operators.
Backup Retention Policy — a number and a unit: d for days, w for weeks, m for months, such as 30d (the default), 4w or 6m. See Retention for what applies today.
Backup schedule — Daily or Weekly at a time of day in UTC, or a Custom cron expression with five fields, in UTC. The default is daily at 03:00 UTC.

Monitoring

Enable Monitoring — on by default — has the operator publish PostgreSQL's own metrics for a Prometheus that collects them. The Metrics card on the cluster's Overview shows the instances' resource use whether or not it is on.

Review & Create

Review & Create shows the name, resource group, version and database, the storage and resources, the instances — marked High Availability when there is more than one — pooling, monitoring and backups. Submit creates the cluster and returns to the list.

The cluster's status then follows the operator's progress and reads Running once every instance is ready. The cluster's Operations tab shows each instance being created, and why one is held up — see Find out why a cluster is not ready.

With the CLI

bash

stsh pg create orders-db -g my-resource-group -c my-cluster \
  --set computePlan=small --set databaseName=orders --set backupConfigured=true

-c names the Kubernetes cluster to place the database on; the platform refuses a create without one. Every setting of the wizard is a field you can --set; stsh pg create --help lists them. The command waits for the create operation to finish, and exits non-zero if it fails.

Created through the CLI or the API, a cluster on the standard plan or larger gets PgBouncer by default — in transaction mode, with two instances — unless you set pgBouncerEnabled=false. The wizard always says whether pooling is on, so this default never applies to it.

Through the API

http

POST https://api.example.com/boundaries/<boundary-id>/resourcegroups/<resource-group>/resources/postgresclusters/orders-db
Content-Type: application/json

{
  "clusterId": "<cluster-id>",
  "computePlan": "small",
  "postgresVersion": "16",
  "databaseName": "orders",
  "backupConfigured": true,
  "backupSchedule": "0 3 * * *",
  "backupRetentionPolicy": "30d"
}

The API accepts the versions 12 to 17. clusterId is required. The fields are listed in the module's API reference.