qos

Overview

Upstream PG15-18; RPM also carries PG14. Requires preload.

Version

Build

You can build the RPM / DEB packages for pg_qos using pig build:

pig build pkg pg_qos         # build RPM / DEB packages

Install

You can install pg_qos directly. First, make sure the PGDG and PIGSTY repositories are added and enabled:

pig repo add pgsql -u          # Add repo and update cache

Install the extension using pig or apt/yum/dnf:

pig install pg_qos;          # Install for current active PG version

pig ext install -y pg_qos -v 18  # PG 18
pig ext install -y pg_qos -v 17  # PG 17
pig ext install -y pg_qos -v 16  # PG 16
pig ext install -y pg_qos -v 15  # PG 15

dnf install -y pg_qos_18       # PG 18
dnf install -y pg_qos_17       # PG 17
dnf install -y pg_qos_16       # PG 16
dnf install -y pg_qos_15       # PG 15

apt install -y postgresql-18-qos   # PG 18
apt install -y postgresql-17-qos   # PG 17
apt install -y postgresql-16-qos   # PG 16
apt install -y postgresql-15-qos   # PG 15

Preload:

shared_preload_libraries = 'qos';

Create Extension:

CREATE EXTENSION qos;

Usage

Sources:

• README.md
• qos.control
• qos–1.0–1.1.sql
• qos–1.1.sql

qos 1.1 (distribution 1.1.0) applies per-role and per-database resource limits on PostgreSQL 15+. Merge qos into shared_preload_libraries and restart before creating its SQL objects as an administrator. CPU affinity limits require Linux.

Configure Limits

CREATE EXTENSION qos;
ALTER ROLE app_user SET qos.work_mem_limit = '32MB';
ALTER ROLE app_user SET qos.max_concurrent_select = '100';
ALTER ROLE app_user SET qos.max_select_rate = '10/500ms';
SELECT * FROM qos_stat_rate;

Limit Semantics

qos.work_mem_limit caps effective work memory; qos.cpu_core_limit controls CPU affinity on Linux and limits parallel workers on other platforms. qos.max_concurrent_tx, qos.max_concurrent_select, qos.max_concurrent_update, qos.max_concurrent_delete and qos.max_concurrent_insert cap concurrent operations.

qos.max_tx_rate, qos.max_select_rate, qos.max_update_rate, qos.max_delete_rate and qos.max_insert_rate use count/window pairs such as 100/1s. The default -1 disables each rate limit. Windows range from 100 ms to one day. Rate and concurrency violations raise SQLSTATE 54000; clients should use the retry hint. The most restrictive applicable role/database setting wins, and rate pairs are compared by normalized rate.

Observability and Upgrade

qos_stat_rate exposes live windows; the other qos_stat views expose activity and counters. qos_prometheus_metrics() renders Prometheus exposition text. Counters reset at server restart. Version 1.1 replaces the old nonfunctional qos_get_stats() with these views.

Upgrading requires replacing the library and restarting PostgreSQL because the shared-memory layout changes, followed by ALTER EXTENSION qos UPDATE TO '1.1' in each database. New rate limits stay disabled until configured. These controls do not replace application admission limits or operating-system isolation.