Skip to main content
Not yet released. This guide describes implemented changes awaiting rollout. Availability requires the corresponding backend and dashboard release.

​
Goal

Change how PostgreSQL behaves, safely and in one place, without logging in to the server.

​
Prerequisites

  • A Dedicated PostgreSQL database that is running
  • Write access to the database

​
Workflow

1
See which settings you can change with stackshift database parameter-definitions --query family=postgres17 (GET /api/v1/databases/parameter-definitions). Use your database’s version in family (postgres15 to postgres18).
2
Create a group with stackshift database parameter-group-create --file group.json (POST /api/v1/databases/parameter-groups), where the file holds {"name":"reporting","family":"postgres17","description":"Longer timeouts","parameters":{"statement_timeout":"60s","work_mem":"64MB"}}.
3
Assign it to a database with stackshift database parameter-group-set DATABASE --data '{"group_id":"GROUP_ID"}' (PUT /api/v1/databases/{id}/parameter-group).
4
Check the result with stackshift database parameters DATABASE (GET /api/v1/databases/{id}/parameters). When applied is true, the database is using your values.
5
If pending_restart lists a setting, apply it now with stackshift database parameters-apply DATABASE (POST /api/v1/databases/{id}/parameters/apply), or let it happen in your maintenance window.

​
The default and your groups

  • A database with no group runs the StackShift defaults, which are sized for its instance class and storage. Each setting then has source: default.
  • A group only holds the settings you want to change. Anything you leave out keeps its default. Settings you set show source: group.
  • A group belongs to your account and can be used by several databases. It has a name of 1 to 60 characters that is unique in your account, an optional description and a family.
  • The family is the PostgreSQL version, for example postgres17. A group keeps its family, and a database can only use a group of its own version.
  • Change a group with stackshift database parameter-group-update GROUP --file group.json (PATCH /api/v1/databases/parameter-groups/{groupID}; name, description and a full replacement of parameters). Every database using the group picks up the change.
  • Return a database to the defaults with stackshift database parameter-group-set DATABASE --data '{"group_id":null}'.
  • List your groups with stackshift database parameter-groups (GET /api/v1/databases/parameter-groups) and read one with stackshift database parameter-group GROUP.
  • Delete a group with stackshift database parameter-group-delete GROUP (DELETE …/parameter-groups/{groupID}). It is refused while a database still uses it.

​
Settings you can change

Only settings on the list can be changed. Anything else, such as connection limits, replication, TLS and file locations, is managed by StackShift so backups, failover and security keep working. Asking for one answers 400 with “… cannot be changed”.
  • Memory and planner: work_mem, maintenance_work_mem, effective_cache_size, shared_buffers, random_page_cost, effective_io_concurrency, default_statistics_target, max_parallel_workers_per_gather, jit.
  • Timeouts: statement_timeout, lock_timeout, idle_in_transaction_session_timeout, idle_session_timeout. 0 turns each one off.
  • Logging: log_min_duration_statement, auto_explain.log_min_duration (-1 turns them off) and log_statement (none, ddl, mod or all).
  • Autovacuum: autovacuum_vacuum_scale_factor, autovacuum_analyze_scale_factor, autovacuum_naptime and autovacuum_max_workers.
  • Each setting has a type and a range. Memory values look like 64MB, durations like 5s or 2min, and switches are on or off. A value outside its range is refused with 400 “… is out of range”.

​
Applied at once or after a restart

  • Most settings apply within a moment, with no restart and no dropped connections.
  • shared_buffers and autovacuum_max_workers need a restart. The definitions mark them with restart: true, and until the restart they appear in pending_restart.
  • The restart happens at your next maintenance window, or right away with stackshift database parameters-apply DATABASE. The database must be running.
  • With a standby or read replicas, the other servers restart first and the primary last. Without them, connections drop while the database restarts, so pick a quiet moment.
  • A pending_restart event appears in the events feed when a restart is waiting.
  • If the settings can’t be applied, error says why.

​
After a major version upgrade

A group belongs to one PostgreSQL version. After an upgrade, the database runs on the defaults for the new version until you assign a group of the new version. The upgrade check warns you about this first.

​
Availability

Dedicated databases are rolling out. If Create doesn’t offer Dedicated, it isn’t switched on for your account yet, and the API answers 403.

​
Expected result

Each setting shows your value with source: group, the others show the defaults for the database’s size, and nothing is left in pending_restart.

​
Common failures

  • 400 “… cannot be changed”: the setting isn’t on the list.
  • 400 “you already have a parameter group with that name”: pick another name.
  • 400 “this database needs a postgres17 parameter group” (or your version): create a group of the same version as the database.
  • 409 “Move the databases that use this parameter group to another group first.”: reassign them, then delete the group.
  • 409 “Start the database before applying its settings.”: start the database first.

Dedicated databases

Create a Dedicated PostgreSQL database, connect to it, resize it and manage its lifecycle.

Maintenance window and updates

Choose the weekly window when StackShift updates your Dedicated database, see what is waiting, and apply it now if you prefer.

PostgreSQL version upgrades

Upgrade a Dedicated database to a newer PostgreSQL major version, in place with a short outage or blue/green with a switch that takes seconds.

Performance Insights and events

See what a Dedicated database spends its time on, find its slowest queries, and read a feed of failovers, backups and maintenance.