QMAN — Command Reference

This section describes QMAN commands in user-defined language, without internal templates or curl call examples. All operations are performed via the QMAN interface and/or agent; connection parameters and authentication are specified in the system settings. This summary is based on the current list of commands and their descriptions. The source is "Список-команд.md".

How to read

  • Purpose — what the command does.
  • Options — input arguments/settings.
  • Result — format and meaning of the output data.
  • Notes — features, statuses (deprecated/preview) and dependent settings.

Safety Notes
The examples exclude direct calls to curl and references to internal templates.

Connection parameters, credentials, and repository addresses are configured centrally and are not published in the user documentation.

Agent and OS Level Operations

qman-agent-status

Purpose: Checks the functionality of the QMAN agent (returns ok).
Options: None.
Result: Status string.
Notes: Used as a quick self-check.

dir-make-list

Purpose: Creates a directory (if it does not exist) and displays its contents.
Options: dir_name — directory path.
Result: List of files/directories with attributes.
Notes: The output is similar to ls -l.

log-from-file

Purpose: Returns a fragment of the log file for the specified period..
Options: log_path, timestamp1, timestamp2, show_log_rows.
Result: Text selection of log rows.
Notes: Get the path to the current log using the log-path command.

Managing QHB Instances (qhb_ctl)

qhb-status

Purpose: Shows whether the QHB instance is running.
Options: pgdata — path to the data directory (PGDATA).
Result: Instance status.

qhb-start

Purpose: Starts the QHB instance.
Options: pgdata .
Result: JSON: output (start message log), result_code (0 — success).
Example result:

{
  "output": "waiting for server to start...\n...\nserver started\n",
  "result_code": 0
}

qhb-stop

Purpose: Stops the QHB instance.
Options: pgdata.
Result: Exit status and accompanying message.

qhb-promote

Purpose: Promotes the standby server to the primary role.
Options: pgdata.
Result: Exit status and message.

qhb-reload

Purpose: Rereads the instance configuration (SIGHUP).
Options: pgdata.
Result: Exit status and message.

qhb-restart

Purpose: Restarts the QHB instance.
Options: pgdata.
Result: Exit status and message.

Instance Logs

log-path

Purpose: Returns the path and name of the current instance log file.
Options: Connection parameters.
Result: A string with the absolute path to the file.

log-list

Purpose: List of available instance log files.
Options: Connection parameters.
Result: List of log files/periods.

Backup and Restore (qbackup)

backup-settings

Purpose: Shows parameters that affect the copy.
Options: Connection context.
Result: Setting reference list.

backup-list

Purpose: Displays a list of available backups.
Options: backups_dir.
Result: JSON list of backups.

backup-full

Purpose: Starts a full backup.
Options: backups_dir, data_directory, port.
Result: Process/task ID and execution log.
Notes: View progress and results via backup-log.

backup-incremental

Purpose: Runs an incremental backup (changed blocks are copied)
Options: backups_dir, data_directory, port.
Result: Process/task ID and execution log.

backup-log

Purpose: Shows the current/last backup log.
Options: backups_dir.
Result: The qbackup.log log text.

backup-remove

Purpose: Deletes the selected backup.
Options: backups_dir, backup_id.
Result: Confirmation of operation.

backup-validate

Purpose: Verifies backup checksums.
Options: backups_dir, backup_id.
Result: Verification result in the qbackup log (see backup-log).

backup-restore

Purpose: Restores a cluster from a full backup.
Options: backups_dir, backup_id, target_data_directory, to_last_lsn.
Result: Operation status and restore log.
Notes: to_last_lsn = --target-lsn=latest to restore to the latest LSN; an empty value means restoring to the last change within the backup.

backup-restore-pitr

Purpose: Restores the cluster to the specified point in time (PITR).
Options: backups_dir, backup_id, target_data_directory, target_type (time|xid|lsn|name), target_value.
Result: Operation status and restore log.

Infrastructure Tree and Editing (QMAN Repository)

node-tree

Purpose: Returns a general tree: groups, hosts, clusters, and QHB instances.
Options: None.
Result: JSON tree (including cluster_parent_id for instances).
Example result (fragment):

{
  "output": [
    { "id": 0, "name": "Структура", "node_type": "root" },
    { "id": 1, "name": "Группа 1", "node_type": "group", "parent_id": 0 },
    { "id": 2, "name": "Кластер QHB", "node_type": "cluster", "parent_id": 1 },
    { "id": 3, "name": "patroni-dev1", "node_type": "host", "parent_id": 1 },
    { "id": 5, "name": "qhb1", "node_type": "instance", "parent_id": 3, "cluster_parent_id": 2 }
  ],
  "result_code": 0
}

instance-list

Purpose: Shows a list of QHB instances on the specified host.
Options: host_id.
Result: JSON instance list.

node-tree-new

Purpose: Adds a tree node.
Options: ty (node ​​type), parent (parent description).
Result: ID and type of the created node.

node-tree-upd

Purpose: Updates node attributes.
Options: current, name, comment, info.
Result: Updated node fields.

node-tree-del

Purpose: Removes a node from the tree.
Options: current, parent.
Result: Confirmation of deletion.

node-tree-cluster-list

Purpose: List of registered clusters (type/name).
Options: None.
Result: List of clusters.

node-tree-update-cluster

Purpose: Associates an instance with a cluster by cluster_parent_id.
Options: id (instance), cluster_parent_id.
Result: Confirmation of change.

Configuration and Access

hba-settings

Purpose: Shows significant strings of qhb_hba.conf.
Options: None.
Result: Columns: line_number, type, database, user_name, address, netmask, auth_method, options, error.

common-settings

Purpose: Displays all instance settings; supports filtering by parameter name.
Options: param_name (optional).
Result: List of "parameter → value" pairs.

special-settings (deprecated)

Purpose: Previously returned pg_db_role_setting.
Notes: Current data is included in db-info and role-info/role-list.

is-replica

Purpose: Determines whether the instance is a replica.
Options: Connection parameters.
Result: Boolean flag/status.

Users and Roles

role-list

Purpose: List of roles/users and their attributes.
Поля: name (oid), comment, memberof, rolsuper, rolinherit, rolcreaterole, rolcreatedb, rolcanlogin, rolreplication, rolbypassrls, rolconnlimit, rolvaliduntil, special_settings, user_db_list.
Result: JSON with a list of roles and their parameters.

role-privs

Purpose: Returns the role's privileges (including inherited ones).
Options: rolename, recursive (true|false).
Result: List of privileges by object.

user-attr-change

Purpose: Changes a role/user attribute.
Options: rolname, attrname, attrvalue.
Valid attribute names: rolcanlogin, rolsuper, rolcreaterole, rolcreatedb, rolreplication, rolbypassrls, rolinherit, rolconnlimit, rolvaliduntil.
Result: Execution message.
Notes: Some attributes accept 'yes'/'no' (strings), rolconnlimit is a number (string), rolvaliduntil is a date/time YYYY-MM-DD HH:MI:SS.

role-tree (deprecated)

Purpose: Previously, it built a user role tree.
Notes: Current data is available via role-list and role-info.

user-db-list (deprecated)

Purpose: Previously, it returned databases and available roles.
Notes: Information is included in role-list and role-info.

Bases, Schemes and Objects

db-list

Purpose: List of instance databases and basic parameters.
Options: Connection parameters.
Result: JSON list of databases.

db-info

Purpose: Key database metrics and settings.
Options: Database oid.
Result: JSON with database properties.

all-db-list

Purpose: A simple database list (ID, name, comment).
Options: Connection parameters.
Result: A database list.

schema-list

Purpose: List of schemas in the database.
Options: Connection context; access ticket (if authentication is enabled).
Result: List of schemas with owners/descriptions..

schema-objects

Purpose: Objects within the specified schema.
Options: schema, as well as host/port/database parameters (call context).
Result: Branched JSON structure of objects.

obj-depend-list

Purpose: List of object dependencies by OID.
Options: obj_oid.
Result: List of dependent objects.

ts-list

Purpose: Tablespace list.
Options: None.
Result: Tablespace list.

ext-list / available-ext-list

Purpose: Installed extensions / extensions available for installation.
Options: Connection context.
Result: Extension lists.

fdw-list / fdw-server-list / fdw-user-mapping

Purpose: Reference lists of foreign data wrapper components.
Options: None.
Result: Lists of wrappers, servers, and user mappings.

Replication and Statuses

instance-list

(see Section Infrastructure Tree and Editing (QMAN Repository))
Purpose: List of instances on the host — convenient for selecting the source of statuses.

is-replica

(see Section Configuration and Access)
Purpose: Instance role flag (master/replica).

Monitoring and Metrics

active-sessions

Purpose: List of active sessions.
Options: Connection parameters.
Result: JSON for current connections.

long-transactions

Purpose: Long transactions per interval.
Options: period_sec.
Result: List of transactions with duration.

blocked-sessions / blocked-objects

Purpose: Locked sessions/objects.
Options: For objects, the dbname (specific database) is important.
Result: Current locks and their context.

lock-list

Purpose: Lock tree by instance.
Options: Connection parameters.
Result: Process hierarchy with root _root.
Sample script:

Сессия 1: BEGIN; INSERT INTO t1 VALUES (1);
Сессия 2: TRUNCATE TABLE t;
Сессия 3: VACUUM ALL t;
Сессия 4: SELECT COUNT(*) FROM t;

inst-space

Purpose: Instance-level disk space usage.
Options: Connection parameters.
Result: Size summary.

db-top-tables-space

Purpose: Top N tables by size and "other" summary.
Options: top_n.
Result: List of tables and their sizes.

bloat-table-list / bloat-index-list

Purpose: Lists of bloated tables/indexes.
Options: Connection context (for the database).
Result: Candidates for maintenance (VACUUM/REINDEX).

frozen-xid-settings / frozen-xid-db-horizon / frozen-xid-table-horizon

Purpose: Transaction freeze threshold and horizons at the database/table level.
Options: dbname for a table horizon.
Result: Vacuum/freeze metadata.

avail-xids-by-db / avail-xids-by-tran

Purpose: Transaction stock assessment.
Options: None.
Result: Summary values ​​(by database/transaction).

vacuum-monitoring

Purpose: Current VACUUM processes.
Options: None.
Result: List of active vacuuming processes.

random-data

Purpose: Generating synthetic data/series.
Options: base_value, random_delta, interval_sec, time_points.
Result: Set of values ​​for testing/demo.

metrics-list

Purpose: List of available instance metrics per period.
Options: instance_name, start_dt, finish_dt.
Result: List of metrics; data is stored in the metrics database.

metrics-data

Purpose: Values ​​of the specified metrics per period.
Options: instance_name, start_dt, finish_dt, metric_name_list, metric_name_ext_list.
Result: Value series.
Notes: For timer metrics, name suffixes are used (e.g., p95, p99); for Counter/Gauge it's an empty suffix.

Execution Plans and Profiling

explain-analyze / explain-analyze-cached-plan

Purpose: SQL query execution analysis (including with a plan from the shared cache).
Options: Connect; for "cached-plan" — query_id and detail flags.
Result: Execution plan/statistics.

sql-explain

Purpose: Query plan output.
Options: sql_text.
Result: Explain plan.

sql-cache-info / sql-plans-info

Purpose: Summary of the shared plan cache and query list.
Options: None.
Result: Cache reference data.

sql-profile-queries

Purpose: List of long queries to profile.
Options: Connection context/ticket.
Notes: Requires query profiling and message queue settings to be enabled on the QHB side.

sql-profile-dump-qep

Purpose: The query plan (QEP) tree for the profiled query.
Options: query_id.
Result: The plan structure.

sql-profile-wait-qep

Purpose: Waiting/getting the QEP for the specified query and backend.
Options: query_id, backend_id.
Result: The QEP or wait timeout.

Authentication and Tickets

qman-login

Purpose: Authenticates the user in QMAN and returns an access ticket.
Options: Username and password.
Result: Ticket used in subsequent commands.

check-ticket

Purpose: Checks the ticket's validity before executing the command.
Options: ticket.
Result: Check status (service operation).

Patroni Integrations (REST)

patroni-cluster / patroni-status

Purpose: Getting cluster summary and node status via REST Patroni.
Options: None.
Result: Structure with node roles, timeline, version, pending_restart attribute, etc.
Example result (fragment):

{
  "members": [
    { "name": "qhb1", "host": "…", "port": 5432, "role": "leader", "state": "running", "timeline": 12 },
    { "name": "qhb2", "host": "…", "port": 5432, "role": "replica", "state": "running", "timeline": 12 }
  ]
}

rest-cluster / rest-status

Purpose: Preconfigured REST queries to Patroni (GET).
Options: None.
Result: Cluster summary / node status.

Deprecated Commands

  • host-tree — replaced by node-tree (general tree).
  • role-tree — replaced by information in role-list/role-info.
  • user-db-list — included in role-list/role-info.

Copyright © KVANTOM LLC, 2019-2026