Процесс qhb

qhb — сервер баз данных QHB


Синтаксис

qhb [параметр...]

или

qhbmaster [параметр...]

Описание

qhb — это сервер баз данных QHB. Чтобы получить доступ к базе данных, клиентское приложение подключается (по сети или локально) к работающему экземпляру qhb. Затем экземпляр qhb запускает отдельный серверный процесс для обработки соединения.

Один экземпляр qhb всегда управляет данными только одного кластера баз данных. Кластер баз данных — это набор баз данных, который хранится в определенном месте общей файловой системы («область данных»). В системе одновременно может работать несколько экземпляров qhb, если они используют разные области данных и разные коммуникационные порты (см. ниже). Когда qhb запускается, он должен знать местоположение области данных. Местоположение следует указать с помощью параметра -D или переменной среды PGDATA; значение по умолчанию отсутствует. Как правило, -D или PGDATA указывает непосредственно на каталог области данных, созданный qhb_bootstrap (или initdb). Другие возможные шаблоны файлов описаны в разделе Расположение файлов.

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

Также команду qhb можно вызвать в однопользовательском режиме. В основном этот режим используется во время начального создания базы при помощи qhb_bootstrap, но иногда применяется и для отладки или аварийного восстановления. Обратите внимание, что использование однопользовательского режима не совсем подходит для полноценной отладки сервера, поскольку в нем не будет реалистичного межпроцессного взаимодействия и блокировок. При вызове в однопользовательском режиме из командной оболочки пользователь может вводить запросы, и результаты будут выводиться на экран, но в форме, которая более полезна для разработчиков, чем для конечных пользователей. В этом режиме пользователем сеанса будет считаться пользователь с номером идентификатора 1, и ему будут предоставлены неявные полномочия суперпользователя. Этому пользователю необязательно существовать на самом деле, поэтому однопользовательский режим можно использовать для ручного восстановления после некоторых видов случайного повреждения системных каталогов.


Параметры

qhb принимает ряд аргументов командной строки. Подробно эти параметры рассматриваются в главе Конфигурация сервера. Настроив файл конфигурации, можно сэкономить время на ввод большинства этих параметров. Некоторые (безопасные) параметры также можно установить со стороны подключающегося клиента (в зависимости от приложения), чтобы они применялись только для этого сеанса. Например, если установлена переменная среды PGOPTIONS, клиенты на основе libpq передадут эту строку на сервер, который будет интерпретировать ее как параметры командной строки qhb.


Общие параметры

-B количество-буферов
Устанавливает количество разделяемых буферов для использования процессами сервера. Значение по умолчанию для этого параметра автоматически выбирается qhb_bootstrap. Указание этого параметра равнозначно установке параметра конфигурации shared_buffers.

-c имя=значение
Устанавливает именованный параметр времени выполнения. Параметры конфигурации, поддерживаемые QHB, описаны в главе Конфигурация сервера. Большинство других параметров командной строки на самом деле являются краткими формами такого назначения параметров. Указав -c несколько раз, можно установить несколько параметров.

-C имя
Выводит значение именованного параметра времени выполнения и завершает работу. (Подробности см. выше в описании параметра -c.) Это возвращает из qhb.conf значения с изменениями, вызванными любыми параметрами в этом вызове. Не отражает параметры, предоставленные при запуске кластера.
Для большинства параметров это можно использовать на работающем сервере. Однако для некоторых параметров, вычисляемых во время выполнения, (например, для shared_memory_size, shared_memory_size_in_huge_pages и wal_segment_size) сервер необходимо выключать.
Этот параметр предназначен для других программ, которые взаимодействуют с экземпляром сервера (как, например, qhb_ctl) и запрашивают значения параметров конфигурации. Пользовательские приложения должны вместо этого использовать команду SHOW или представление pg_settings.

-d уровень-отладки
Устанавливает уровень отладки. Чем выше это значение, тем больше выходных данных отладки записывается в журнал сервера. Значения находятся в диапазоне от 1 до 5. Также для отдельного сеанса возможно передать -d 0, что не даст уровню серверного журнала родительского процесса qhb распространиться на него.

-D каталог-данных
Задает расположение файловой системы файлов конфигурации базы данных. Подробную информацию см. в разделе Расположение файлов.

-e
Устанавливает формат даты по умолчанию в «European», то есть порядок вводимых значений даты вида ДМГ. Это также приводит к тому, что в определенных форматах вывода даты день отображается перед месяцем. Подробную информацию см. в разделе Типы даты/времени.

-F
Выключает вызовы fsync для повышения производительности, хотя и с риском повреждения данных в случае сбоя системы. Указание этого параметра равнозначно выключению параметра конфигурации fsync. Перед использованием этого параметра прочтите подробную документацию!

-h имя-хоста
Задает IP-адрес или имя хоста, по которому qhb должен принимать подключения по TCP/IP от клиентских приложений. Значением также может быть список адресов через запятую или символ *, означающий все доступные интерфейсы. Пустое значение указывает, что не принимается ни один IP-адрес, и в этом случае подключение к серверу возможно только через сокеты домена Unix. По умолчанию принимаются подключения только к локальной рабочей станции. Указание этого параметра равнозначно установке параметра конфигурации listen_addresses.

-i
Позволяет удаленным клиентам подключаться по TCP/IP (интернет-домен). Без этого параметра принимаются только локальные подключения. Он равнозначен установке в параметре listen_addresses значения * в qhb.conf или посредством параметра -h.
Этот параметр считается устаревшим, так как не позволяет получить доступ ко всем функциям listen_addresses. Обычно лучше устанавливать listen_addresses напрямую.

-k каталог
Задает каталог сокета домена Unix, в котором qhb должен принимать подключения от клиентских приложений. Значение также может быть разделенным запятыми списком каталогов. Пустое значение указывает, что не принимается ни один сокет домена Unix, и в этом случае подключение к серверу возможно только через сокеты TCP/IP. Значением по умолчанию обычно является /tmp, но его можно изменить во время сборки. Указание этого параметра равнозначно установке параметра конфигурации unix_socket_directories.

-l
Включает поддержку безопасных подключений с использованием SSL. Чтобы этот параметр был доступен, QHB нужно скомпилировать с поддержкой SSL. Более подробную информацию по использованию SSL см. в разделе Защита TCP/IP-соединений посредством SSL.

-N максимум-соединений
Задает максимальное количество клиентских подключений, которые будет принимать этот сервер. Значение по умолчанию для этого параметра автоматически выбирает qhb_bootstrap. Указание этого параметра равнозначно установке параметра конфигурации max_connections.

-p порт
Задает порт TCP/IP или расширение файла локального сокета домена Unix, на котором qhb должен принимать подключения от клиентских приложений. По умолчанию используется значение переменной среды PGPORT или, если оно не указано, то по умолчанию используется значение, установленное во время компиляции (обычно 5432). Если вы указываете порт, отличный от порта по умолчанию, то все клиентские приложения должны указывать один и тот же порт, используя либо параметры командной строки, либо PGPORT.

-s
Выводит информацию о времени и другую статистику в конце каждой команды. Это полезно для оценки производительности системы или для настройки количества буферов.

-S рабочая-память
Задает базовый объем памяти, который будет использоваться для сортировок и хеш-таблиц, прежде чем прибегнуть к применению временных файлов на диске. Описание аналогичного параметра конфигурации work_mem см. в подразделе Память.

-V
--version
Показать версию qhb и завершиться.

--имя=значение
Устанавливает именованный параметр времени выполнения; является более короткой формой параметра -c.

--describe-config
Этот параметр выгружает внутренние переменные конфигурации сервера, их описания и значения по умолчанию в формате команды COPY с разделителями в виде знаков табуляции. Он предназначен в первую очередь для использования инструментами администрирования.

-?
--help
Показать справку об аргументах командной строки qhb и завершиться.


Параметры для внутреннего использования

Описанные здесь параметры используются в основном для целей отладки, а в некоторых случаях — для помощи в восстановлении сильно поврежденных баз данных. Не должно быть никаких причин использовать их при настройке производственной базы данных. Они перечислены здесь только для использования системными разработчиками QHB. Кроме того, эти параметры могут быть изменены или удалены в будущих версиях без предварительного уведомления.

-f { s | i | o | b | t | n | m | h }
Запрещает использование определенных методов сканирования и объединения: s и i выключают последовательное и индексное сканирование соответственно, o, b и t — сканирование только по индексу, сканирование по индексу битовой карты и сканирование TID соответственно, а n, m и h — соединения с помощью вложенных циклов, слияния и хеширования соответственно.
Ни последовательное сканирование, ни соединение с вложенным циклом нельзя выключить полностью; параметры -fs и -fn просто не позволят оптимизатору использовать эти типы планов, если у того есть какая-либо другая альтернатива.

-n
Этот параметр предназначен для отладки проблем, которые приводят к аварийному завершению серверного процесса. Обычная стратегия в этой ситуации состоит в том, чтобы уведомить все остальные серверные процессы, что они должны завершиться, а затем повторно инициализировать разделяемую память и семафоры. Это связано с тем, что вызвавший ошибку серверный процесс перед завершением мог повредить некоторое разделяемое состояние. Этот параметр указывает, что qhb не будет повторно инициализировать разделяемые структуры данных. Опытный системный программист может затем использовать отладчик для проверки состояния разделяемой памяти и семафора.

-O
Позволяет изменять структуру системных таблиц. Этот параметр используется утилитой qhb_bootstrap.

-P
Игнорировать системные индексы при чтении системных таблиц, но по-прежнему обновлять индексы при изменении этих таблиц. Это полезно при восстановлении поврежденных системных индексов.

-t pa[rser] | pl[anner] | e[xecutor]
Выводить статистику по времени выполнения каждого запроса, относящегося к каждому из основных системных модулей. Этот параметр нельзя использовать совместно с параметром -s.

-T
Этот параметр предназначен для отладки проблем, которые приводят к аварийному завершению серверного процесса. Обычная стратегия в этой ситуации состоит в том, чтобы уведомить все другие серверные процессы, что они должны завершиться, а затем повторно инициализировать разделяемую память и семафоры. Это связано с тем, что вызвавший ошибку серверный процесс перед завершением мог повредить некоторое разделяемое состояние. Этот параметр указывает, что qhb остановит все остальные серверные процессы, отправив сигнал SIGSTOP, но не вызовет их завершение. Это позволит системным программистам вручную собрать дампы ядра всех процессов сервера.

-v протокол
Задает номер версии протокола взаимодействия клиент-сервер, который будет использоваться для конкретного сеанса. Этот параметр предназначен только для внутреннего использования.

-W секунды
При запуске нового серверного процесса после проведения процедуры аутентификации возникает задержка на заданное количество секунд. Назначение этого параметра — дать возможность подключиться к серверному процессу с помощью отладчика.


Параметры для однопользовательского режима

Следующие параметры применимы только к однопользовательскому режиму (см. параграф Однопользовательский режим ниже).

--single
Выбирает однопользовательский режим. Этот аргумент должен быть первым в командной строке.

база_данных
Задает имя базы данных, к которой открывается доступ. Этот аргумент должен быть последним в командной строке. Если он опущен, по умолчанию используется имя пользователя.

-E
Выводить все команды на стандартное устройство вывода перед их выполнением.

-j
Использовать в качестве завершающих символов ввода команды точку с запятой и два символа перевода строки, а не просто перевод строки.

-r имя_файла
Отправлять весь вывод журнала сервера в файл имя_файла. Этот параметр учитывается только в том случае, если он указан в командной строке.


Переменные среды

PGCLIENTENCODING
Кодировка символов по умолчанию, используемая клиентами. (Клиенты могут переопределить ее индивидуально.) Это значение также можно установить в файле конфигурации.

PGDATA
Местоположение по умолчанию для каталога данных.

PGDATESTYLE
Значение по умолчанию для параметра времени выполнения DateStyle. (Использование этой переменной среды считается устаревшим.)

PGPORT
Номер порта по умолчанию (желательно установить в файле конфигурации).


Диагностика

Сообщение об ошибке, в котором упоминается semget или shmget, скорее всего, означает необходимость сконфигурировать ядро для предоставления достаточного объема разделяемой памяти и семафоров. Более подробно это рассматривается в разделе Управление ресурсами ядра. Переконфигурирование ядра можно отложить, уменьшив значение параметра shared_buffers для снижения потребления разделяемой памяти QHB, и/или уменьшив значение параметра max_connections для снижения затрат на использование семафоров.

Сообщение об ошибке, указывающее на то, что другой сервер уже запущен, следует тщательно проверить, например, с помощью команды

$ ps ax | grep qhb

или

$ ps -ef | grep qhb

в зависимости от ОС. Если вы уверены, что конфликтующий сервер не запущен, можно удалить указанный в сообщении файл блокировки и повторить попытку.

Сообщение об ошибке, указывающее на невозможность привязки к порту, может означать, что этот порт уже используется некоторым процессом, не связанным с QHB. Также эту ошибку можно получить, если завершить работу qhb и немедленно перезапустить его, используя тот же порт; в этом случае следует просто подождать несколько секунд, пока операционная система не закроет порт, прежде чем попытаться снова. Наконец, эту ошибку можно получить, если указать номер порта, который ваша ОС считает зарезервированным. Например, многие версии Unix считают номера портов менее 1024 «доверенными» и разрешают доступ к ним только суперпользователю Unix.


Примечания

qhbmaster является устаревшим псевдонимом qhb.

Для безопасного и удобного запуска и выключения сервера qhb можно использовать утилиту qhb_ctl.

Если это вообще возможно, не используйте сигнал SIGKILL для остановки основного сервера qhb, иначе qhb не освободит системные ресурсы (например разделяемую память и семафоры), которые занимал перед остановкой. Такое поведение может вызвать проблемы при запуске нового экземпляра qhb.

Для нормального завершения работы сервера qhb можно использовать сигналы SIGTERM, SIGINT или SIGQUIT. При первом сервер перед выходом будет дожидаться завершения работы всех клиентов, при втором все клиенты будут принудительно отключены, а третий приведет к немедленному выходу без корректного завершения, вследствие чего во время перезапуска выполнится процедура восстановления.

Сигнал SIGHUP перезагрузит файлы конфигурации сервера. Также возможно отправить SIGHUP на отдельный процесс сервера, но это обычно не имеет смысла.

Чтобы отменить текущий запрос, отправьте сигнал SIGINT процессу, выполняющему эту команду. Чтобы завершить внутренний процесс, отправьте этому процессу сигнал SIGTERM. См. также в подразделе Функции для передачи сигналов серверу описание функций pg_cancel_backend и pg_terminate_backend, которые являются вызываемыми из SQL аналогами этих двух действий.

Сервер qhb использует SIGQUIT, чтобы приказать подчиненным серверным процессам завершиться без обычной очистки. Пользователям нельзя использовать этот сигнал. Также неразумно отправлять SIGKILL на серверный процесс — основной процесс qhb будет интерпретировать это как сбой и заставит все родственные процессы завершиться как часть стандартной процедуры восстановления после сбоя.


Ошибки

Параметры с -- не будут работать на FreeBSD или OpenBSD; используйте вместо них -c. Это ошибка ОС.


Однопользовательский режим

Чтобы запустить сервер в однопользовательском режиме, используйте команду вроде

qhb --single -D /var/lib/qhb/data other-options my_database

Укажите правильный путь к каталогу базы данных с помощью -D или задайте переменную среды PGDATA. Также укажите имя конкретной базы данных, в которой хотите работать.

Обычно в однопользовательском режиме сервер обрабатывает символ перевода строки как окончание ввода команды; точка с запятой не является синтаксическим разделителем, как в psql. Чтобы ввести команду, занимающую несколько строк, следует перед каждым символом перевода строки, кроме последнего, использовать обратный слэш. При этом обратный слэш и соседний символ перевода строки удаляются из вводимой команды. Обратите внимание, что это происходит даже внутри строкового литерала или комментария.

Но если воспользоваться параметром командной строки -j, одиночный символ перевода строки не завершит ввод команды; вместо него это будет делать последовательность из точки с запятой и двух символов перевода строки. То есть для завершения команды следует ввести точку с запятой, а следом совершенно пустую строку. Обратный слэш с последующим символом перевода строки в этом режиме не имеют специального значения. Опять же, внутри строкового литерала или комментария такая последовательность тоже не работает.

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

Для завершения сеанса введите символ конца файла (EOF, обычно это Ctrl+D). Если после введения последней завершающей последовательности команды вы вводили какой-либо текст, то EOF будет восприниматься как завершающая последовательность команды, и для выхода понадобится еще один EOF.

Обратите внимание, что однопользовательский режим не предоставляет продвинутых возможностей для редактирования строк (например, здесь нет истории команд). Также в однопользовательском режиме не производится фоновая обработка, например, не выполняются автоматические контрольные точки или репликация.


Примеры

Чтобы запустить qhb в фоновом режиме, используя значения по умолчанию, введите:

$ nohup qhb >logfile 2>&1 </dev/null &

Чтобы запустить qhb с определенным портом, например 1234, введите:

$ qhb -p 1234

Чтобы подключиться к этому серверу с помощью psql, укажите этот порт в параметре -p:

$ psql -p 1234

или установите переменную среды PGPORT:

$ export PGPORT=1234
$ psql

Именованные параметры времени выполнения можно установить в любом из следующих стилей:

$ qhb -c work_mem=1234
$ qhb --work-mem=1234

Любая из этих форм переопределяет любое значение параметра work_mem в qhb.conf. Обратите внимание, что подчеркивания в именах параметров в командной строке могут быть записаны как подчеркивание или тире. За исключением краткосрочных экспериментов, вероятно, лучше отредактировать параметр в qhb.conf, чем задавать его в аргументах командной строки.


См. также

qhb_bootstrap, qhb_ctl