QMAN — Справочник команд

Этот раздел описывает команды QMAN в пользовательской формулировке, без внутренних шаблонов и примеров вызова curl. Все операции выполняются через интерфейс QMAN и/или агента; параметры соединения и аутентификация задаются в настройках системы. Свод составлен на основе текущего списка команд и их описаний. Источник: «Список-команд.md».

Как читать

Назначение — что делает команда.
Параметры — входные аргументы/настройки.
Результат — формат и смысл возвращаемых данных.
Примечания — особенности, статусы (устарело/предпросмотр) и зависимые настройки.

Примечания по безопасности
В примерах исключены прямые вызовы curl и ссылки на внутренние шаблоны.

Параметры соединения, учетные данные и адреса репозиториев настраиваются централизованно и не публикуются в пользовательской документации.

Агент и операции уровня ОС

qman-agent-status

Назначение: Проверяет работоспособность агента QMAN (возвращает ok).
Параметры: Нет.
Результат: Строка состояния.
Примечания: Используется как быстрая самопроверка.

dir-make-list

Назначение: Создает каталог (если тот отсутствует) и выводит его содержимое.
Параметры: dir_name — путь к каталогу.
Результат: Список файлов/каталогов с атрибутами.
Примечания: Вывод аналогичен ls -l.

log-from-file

Назначение: Возвращает фрагмент файла журнала за указанный период.
Параметры: log_path, timestamp1, timestamp2, show_log_rows.
Результат: Текстовая выборка строк лога.
Примечания: Путь к текущему логу берите через команду log-path.

Управление экземплярами QHB (qhb_ctl)

qhb-status

Назначение: Показывает, запущен ли экземпляр QHB.
Параметры: pgdata — путь к каталогу данных (PGDATA).
Результат: Статус экземпляра.

qhb-start

Назначение: Запускает экземпляр QHB.
Параметры: pgdata.
Результат: JSON: output (журнал сообщений старта), result_code (0 — успех).
Пример результата:

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

qhb-stop

Назначение: Останавливает экземпляр QHB.
Параметры: pgdata.
Результат: Код завершения и сопроводительное сообщение.

qhb-promote

Назначение: Переводит резервный сервер в роль основного (promote).
Параметры: pgdata.
Результат: Код выполнения и сообщение.

qhb-reload

Назначение: Перечитывает конфигурацию экземпляра (SIGHUP).
Параметры: pgdata.
Результат: Код выполнения и сообщение.

qhb-restart

Назначение: Выполняет рестарт экземпляра QHB.
Параметры: pgdata.
Результат: Код выполнения и сообщение.

Журналы экземпляров

log-path

Назначение: Возвращает путь и имя текущего файла журнала экземпляра.
Параметры: Параметры соединения.
Результат: Строка с абсолютным путем к файлу.

log-list

Назначение: Список доступных файлов журнала экземпляра.
Параметры: Параметры соединения.
Результат: Перечень файлов/периодов логов.

Резервное копирование и восстановление (qbackup)

backup-settings

Назначение: Показывает параметры, влияющие на операцию копирования.
Параметры: Контекст соединения.
Результат: Справочный список настроек.

backup-list

Назначение: Выводит список доступных резервных копий.
Параметры: backups_dir.
Результат: JSON‑перечень копий.

backup-full

Назначение: Запускает полное резервное копирование.
Параметры: backups_dir, data_directory, port.
Результат: Идентификатор процесса/задачи и журнал выполнения.
Примечания: Прогресс и итог смотрите через backup-log.

backup-incremental

Назначение: Запускает инкрементальное резервное копирование (копируются измененные блоки).
Параметры: backups_dir, data_directory, port.
Результат: Идентификатор процесса/задачи и журнал выполнения.

backup-log

Назначение: Показывает текущий/последний журнал резервного копирования.
Параметры: backups_dir.
Результат: Текст журнала qbackup.log.

backup-remove

Назначение: Удаляет выбранную резервную копию.
Параметры: backups_dir, backup_id.
Результат: Подтверждение операции.

backup-validate

Назначение: Проверяет контрольные суммы резервной копии.
Параметры: backups_dir, backup_id.
Результат: Итог проверки в журнале qbackup (см. backup-log).

backup-restore

Назначение: Восстанавливает кластер из полной резервной копии.
Параметры: backups_dir, backup_id, target_data_directory, to_last_lsn.
Результат: Статус операции и лог восстановления.
Примечания: to_last_lsn = --target-lsn=latest для восстановления до последнего LSN; пустое значение — до последнего изменения внутри копии.

backup-restore-pitr

Назначение: Восстанавливает кластер до указанной точки (PITR).
Параметры: backups_dir, backup_id, target_data_directory, target_type (time|xid|lsn|name), target_value.
Результат: Статус операции и лог восстановления.

Дерево инфраструктуры и редактирование (репозиторий QMAN)

node-tree

Назначение: Возвращает общее дерево: группы, хосты, кластеры и экземпляры QHB.
Параметры: Нет.
Результат: JSON‑дерево (включая cluster_parent_id у экземпляров).
Пример результата (фрагмент):

{
  "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

Назначение: Показывает список экземпляров QHB на указанном хосте.
Параметры: host_id.
Результат: JSON‑список экземпляров.

node-tree-new

Назначение: Добавляет узел дерева.
Параметры: ty (тип узла), parent (описание родителя).
Результат: Идентификатор и тип созданного узла.

node-tree-upd

Назначение: Обновляет атрибуты узла.
Параметры: current, name, comment, info.
Результат: Обновленные поля узла.

node-tree-del

Назначение: Удаляет узел из дерева.
Параметры: current, parent.
Результат: Подтверждение удаления.

node-tree-cluster-list

Назначение: Список зарегистрированных кластеров (тип/имя).
Параметры: Нет.
Результат: Перечень кластеров.

node-tree-update-cluster

Назначение: Привязывает экземпляр к кластеру по cluster_parent_id.
Параметры: id (экземпляра), cluster_parent_id.
Результат: Подтверждение изменения.

Конфигурация и доступ

hba-settings

Назначение: Показывает значимые строки qhb_hba.conf.
Параметры: Нет.
Результат: Столбцы: line_number (номер строки), type (тип), database (база данных), user_name (имя пользователя), address (адрес), netmask (маска сети), auth_method (метод аутентификации), options (параметры), error (ошибка).

common-settings

Назначение: Выводит все настройки экземпляра; поддерживает фильтр по имени параметра.
Параметры: param_name (необязательно).
Результат: Список пар «параметр → значение».

special-settings (устаревшая)

Назначение: Ранее возвращала pg_db_role_setting.
Примечания: Актуальные данные включены в db-info и role-info/role-list.

is-replica

Назначение: Определяет, является ли экземпляр репликой.
Параметры: Параметры соединения.
Результат: Логический признак/статус.

Пользователи и роли

role-list

Назначение: Список ролей/пользователей и их атрибутов.
Поля: name (oid), comment, memberof, rolsuper, rolinherit, rolcreaterole, rolcreatedb, rolcanlogin, rolreplication, rolbypassrls, rolconnlimit, rolvaliduntil, special_settings, user_db_list.
Результат: JSON со списком ролей и их параметров.

role-privs

Назначение: Возвращает права роли (включая наследуемые).
Параметры: rolename, recursive (true|false).
Результат: Перечень прав в разрезе объектов.

user-attr-change

Назначение: Меняет атрибут роли/пользователя.
Параметры: rolname, attrname, attrvalue.
Допустимые имена атрибутов: rolcanlogin, rolsuper, rolcreaterole, rolcreatedb, rolreplication, rolbypassrls, rolinherit, rolconnlimit, rolvaliduntil.
Результат: Сообщение о выполнении.
Примечания: Часть атрибутов принимает 'yes'/'no' (строки), rolconnlimit — число (строка), rolvaliduntil — дата/время YYYY-MM-DD HH:MI:SS.

role-tree (устаревшая)

Назначение: Ранее строила дерево ролей пользователя.
Примечания: Актуальные данные доступны через role-list и role-info.

user-db-list (устаревшая)

Назначение: Ранее возвращала базы, доступные роли.
Примечания: Сведения включены в role-list и role-info.

Базы, схемы и объекты

db-list

Назначение: Список баз данных экземпляра и основные параметры.
Параметры: Параметры соединения.
Результат: JSON‑список баз.

db-info

Назначение: Ключевые показатели базы и ее настройки.
Параметры: oid базы.
Результат: JSON со свойствами базы.

all-db-list

Назначение: Простой список баз (идентификатор, имя, комментарий).
Параметры: Параметры соединения.
Результат: Перечень баз.

schema-list

Назначение: Список схем в базе.
Параметры: Контекст соединения; тикет доступа (если включена аутентификация).
Результат: Перечень схем с владельцами/описанием.

schema-objects

Назначение: Объекты внутри указанной схемы.
Параметры: schema, а также параметры хоста/порта/базы (контекст вызова).
Результат: Ветвистая JSON‑структура по объектам.

obj-depend-list

Назначение: Список зависимостей для объекта по OID.
Параметры: obj_oid.
Результат: Перечень зависимых/зависящих объектов.

ts-list

Назначение: Список табличных пространств.
Параметры: Нет.
Результат: Перечень табличных пространств.

ext-list / available-ext-list

Назначение: Установленные расширения / расширения, доступные для установки.
Параметры: Контекст соединения.
Результат: Перечни расширений.

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

Назначение: Справочные списки компонентов обертки сторонних данных.
Параметры: Нет.
Результат: Перечни оберток, серверов и сопоставлений пользователей.

Репликация и статусы

instance-list

(см. раздел Дерево инфраструктуры и редактирование (репозиторий QMAN))
Назначение: Перечень экземпляров на хосте — удобно для выбора источника статусов.

is-replica

(см. раздел Конфигурация и доступ)
Назначение: Признак роли экземпляра (ведущий/реплика).

Мониторинг и метрики

active-sessions

Назначение: Список активных сеансов.
Параметры: Параметры соединения.
Результат: JSON по текущим подключениям.

long-transactions

Назначение: Долгие транзакции за интервал.
Параметры: period_sec.
Результат: Перечень транзакций с длительностью.

blocked-sessions / blocked-objects

Назначение: Заблокированные сеансы/объекты.
Параметры: Для объектов важен dbname (конкретная база).
Результат: Текущие блокировки и их контекст.

lock-list

Назначение: Дерево блокировок по экземпляру.
Параметры: Параметры соединения.
Результат: Иерархия процессов с корнем _root.
Пример сценария:

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

inst-space

Назначение: Использование дискового пространства на уровне экземпляра.
Параметры: Параметры соединения.
Результат: Свод по размерам.

db-top-tables-space

Назначение: ТОП‑N таблиц по объему и суммарное «прочее».
Параметры: top_n.
Результат: Перечень таблиц и их размер.

bloat-table-list / bloat-index-list

Назначение: Списки «раздувшихся» таблиц/индексов.
Параметры: Контекст соединения (для базы).
Результат: Кандидаты для обслуживания (VACUUM/REINDEX).

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

Назначение: Порог «заморозки» транзакций и горизонты на уровне БД/таблиц.
Параметры: Для табличного горизонта — dbname.
Результат: Метаданные по очистке/заморозке.

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

Назначение: Оценка запаса транзакций.
Параметры: Нет.
Результат: Сводные величины (по БД/транзакциям).

vacuum-monitoring

Назначение: Текущие процессы VACUUM.
Параметры: Нет.
Результат: Перечень активных процессов очистки.

random-data

Назначение: Генерация синтетических данных/рядов.
Параметры: base_value, random_delta, interval_sec, time_points.
Результат: Набор значений для тестов/демо.

metrics-list

Назначение: Список доступных метрик экземпляра за период.
Параметры: instance_name, start_dt, finish_dt.
Результат: Перечень метрик; данные хранятся в базе metrics.

metrics-data

Назначение: Значения указанных метрик за период.
Параметры: instance_name, start_dt, finish_dt, metric_name_list, metric_name_ext_list.
Результат: Ряды значений.
Примечания: Для метрик типа timer используются расширения имен (например, p95, p99); для Counter/Gauge — пустой суффикс.

Планы выполнения и профилирование

explain-analyze / explain-analyze-cached-plan

Назначение: Анализ выполнения SQL‑запроса (в т. ч. с планом из общего кеша).
Параметры: Коннект; для «cached-plan» — query_id и флаги детализации.
Результат: План/статистики исполнения.

sql-explain

Назначение: Вывод плана запроса.
Параметры: sql_text.
Результат: План объяснения.

sql-cache-info / sql-plans-info

Назначение: Сводка по общему кешу планов и списку запросов.
Параметры: Нет.
Результат: Справочные данные по кешу.

sql-profile-queries

Назначение: Список «долгих» запросов для профилирования.
Параметры: Контекст соединения/тикет.
Примечания: Требует включения профилирования запросов и настроек очереди сообщений на стороне QHB.

sql-profile-dump-qep

Назначение: Дерево плана (QEP) для запроса из профиля.
Параметры: query_id.
Результат: Структура плана.

sql-profile-wait-qep

Назначение: Ожидание/получение QEP для заданных запроса и обслуживающего процесса.
Параметры: query_id, backend_id.
Результат: QEP либо таймаут ожидания.

Аутентификация и тикеты

qman-login

Назначение: Аутентифицирует пользователя в QMAN и возвращает тикет доступа.
Параметры: Имя пользователя и пароль.
Результат: Тикет, используемый в последующих командах.

check-ticket

Назначение: Проверяет валидность тикета перед выполнением команды.
Параметры: ticket.
Результат: Статус проверки (служебная операция).

Интеграции Patroni (REST)

patroni-cluster / patroni-status

Назначение: Получение сводки по кластеру и статуса узла через REST Patroni.
Параметры: Нет.
Результат: Структура с ролями узлов, временной шкалой, версией, атрибутами pending_restart и пр.
Пример результата (фрагмент):

{
  "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

Назначение: Преднастроенные REST‑запросы к Patroni (GET).
Параметры: Нет.
Результат: Сводка по кластеру / статус узла.

Устаревшие команды

host-tree — заменена на node-tree (общее дерево).
role-tree — заменена сведениями в role-list/role-info.
user-db-list — включена в role-list/role-info.