Пошаговая инструкция по начальной загрузке, установке и запуску

Описывается сценарий установки СУБД «Квант-Гибрид» в первый раз, или установки и обновления при начальной инициализации кластера базы данных, если есть возможность произвести бэкап и восстановление данных во вновь создаваемый кластер.

Внимание!
В случаях, когда

  • необходимо обновление или миграция (бинарная) с других СУБД, или с младших версий СУБД «Квант-Гибрид»,
  • когда каталог базы данных уже существует и не может быть создан заново,
  • когда необходимо сохранить данные уже используемой базы данных в бинарном виде,

обратитесь к разделу документации Краткая инструкция по обновлению.
Также настоятельно рекомендуется использовать процедуры Резервного копирования и восстановления.

Загрузка и установка бинарных пакетов

Обратите внимание
При установке команды должны выполняться от пользователя с правами суперпользователя. Если пользователь не обладает правами суперпользователя, выполните в терминале команду (понадобится ввести пароль суперпользователя)

su -

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

sudo -i

Загрузка и установка бинарных пакетов производится из репозитория СУБД «Квант-Гибрид». Обратитесь к разделу документации Поддерживаемые платформы для уточнения, какие именно платформы поддерживаются СУБД «Квант-Гибрид».

Для Centos 7 и 8

Обратите внимание, что команды должны выполняться от пользователя с правами суперпользователя.

Установите репозиторий программного продукта СУБД «Квант-Гибрид» командой:

rpm --import https://repo.granit-concern.ru/qhb/keys/RPM-GPG-KEY-qhb

и далее, для CentOs 7:

yum-config-manager --add-repo https://repo.granit-concern.ru/qhb/std-1/centos/7/x86_64/qhb.repo

или для CentOs 8:

dnf config-manager --add-repo https://repo.granit-concern.ru/qhb/std-1/centos/8/x86_64/qhb.repo

Установите бинарные пакеты командой:

yum install qhb-core [qhb-contrib] [qcp] [qdl] [qbackup] [metricsd]

Например:

yum install qhb-core

В результате установки пакета ядра QHB будет создан пользователь qhb. Ядро QHB, по умолчанию, установится в каталог /usr/local/qhb.

Многие утилиты QHB устанавливаются в каталог /usr/local/qhb/bin. Если этот каталог указать в переменной окружения $PATH, это облегчит их запуск.

Смотрите дополнительно: Состав поставки, Страница загрузки

Для Альт Сервер 9

Обратите внимание, что команды должны выполняться от пользователя с правами суперпользователя.

Для установки потребуется дополнительная библиотека libicu.

Скачайте библиотеку (подходит версия 60.3-2) в любую локальную папку:

wget -c http://mirror.centos.org/centos/8/BaseOS/x86_64/os/Packages/libicu-60.3-2.el8_1.x86_64.rpm

Скачайте в эту же папку пакеты программного продукта СУБД «Квант-Гибрид» из репозитория командой:

wget -c -r -l1 -A '*.rpm' -nd -np https://repo.granit-concern.ru/qhb/std-1/centos/8/x86_64/

Обновите описания пакетов:

apt-get update

Находясь в этой же локальной папке, установите бинарные пакеты командой, например:

apt-get install *.rpm

Вы можете установить не все пакеты QHB, а только необходимые вам. В этом случае вы можете перечислить в команде нужные вам пакеты rpm через пробел. Выбирайте последние версии из rpm пакетов, которые скачались.

Библиотека libicu и пакет qhb-core - обязательны.

В результате установки пакета ядра QHB будет создан пользователь qhb, ядро QHB, по умолчанию, установится в каталог /usr/local/qhb. Многие утилиты QHB устанавливаются в каталог /usr/local/qhb/bin. Если этот каталог указать в переменной окружения $PATH, это облегчит их запуск.

Смотрите дополнительно: Состав поставки, Страница загрузки

Для Fedora 32 и 33

Обратите внимание, что команды должны выполняться от пользователя с правами суперпользователя.

Установите репозиторий программного продукта СУБД «Квант-Гибрид» командой:

rpm --import https://repo.granit-concern.ru/qhb/keys/RPM-GPG-KEY-qhb

и далее, для Fedora 32:

dnf config-manager --add-repo https://repo.granit-concern.ru/qhb/std-1/fedora/32/x86_64/qhb.repo

или для Fedora 33:

dnf config-manager --add-repo https://repo.granit-concern.ru/qhb/std-1/fedora/33/x86_64/qhb.repo

Установите бинарные пакеты командой:

dnf install qhb-core [qhb-contrib] [qcp] [qdl] [qbackup] [metricsd]

Например:

dnf install qhb-core

В результате установки пакета ядра QHB будет создан пользователь qhb. Ядро QHB, по умолчанию, установится в каталог /usr/local/qhb.

Многие утилиты QHB устанавливаются в каталог /usr/local/qhb/bin. Если этот каталог указать в переменной окружения $PATH, это облегчит их запуск.

Смотрите дополнительно: Состав поставки, Страница загрузки

Для Debian и Astra

Обратите внимание, что команды должны выполняться от пользователя с правами суперпользователя.

Для подключения к репозиторию выполните следующую команду:

apt install gnupg2 apt-transport-https wget

Для Astra требуется установка корневых сертификатов. Установите их с помощью команды:

apt-get install ca-certificates

Установите репозиторий программного продукта СУБД «Квант-Гибрид» командой:

wget -qO - https://repo.granit-concern.ru/qhb/keys/RPM-GPG-KEY-qhb | apt-key add -

Далее выполните команды:

echo 'deb https://repo.granit-concern.ru/qhb/std-1/debian stretch main' >> /etc/apt/sources.list

и

apt update

Установите бинарные пакеты командой:

apt install qhb-core [qhb-contrib] [qcp] [qdl] [qbackup] [metricsd]

Например:

apt install qhb-core

В результате установки пакета ядра QHB будет создан пользователь qhb. Ядро QHB, по умолчанию, установится в каталог /usr/local/qhb.

Многие утилиты QHB устанавливаются в каталог /usr/local/qhb/bin. Если этот каталог указать в переменной окружения $PATH, это облегчит их запуск.

Смотрите дополнительно: Состав поставки, Страница загрузки

В виде docker контейнера

Предлагается конфигурация: сервер СУБД «Квант-Гибрид» с расширениями и пул соединений QCP.

Получение Dockerfile и конфигураций

Создайте локальный каталог и разверните в нём скрипты docker из репозитория СУБД «Квант-Гибрид»:

wget https://repo.granit-concern.ru/qhb/std-1/docker/qhb-docker-image.tar.gz -O - | tar -xz

Создание образов

Внимание!
Потребуется docker-compose. Здесь и далее, запускать docker-compose следует из-под обычного пользователя (не root). Возможно, для этого надо будет выполнить рекомендации по настройке docker.

Как правило, не требуется вручную создавать образ, т.к. он автоматически создаётся при первом запуске. Однако это можно сделать и явным образом:

docker-compose build

Замечание.
Если возникают проблемы с построением образа, связанные с недоступностью репозитория centos, нужно проверить сетевые разрешения. Иногда, перед построением, просто помогает выполнение таких команд:

sudo firewall-cmd --zone=public --add-masquerade --permanent
sudo firewall-cmd --reload

Запуск контейнера

Для запуска контейнеров СУБД «Квант-Гибрид» и QCP с настройками по умолчанию, выполните в текущем каталоге:

docker-compose up

Прервать выполнение можно с помощью Ctrl+C, или же выполнив из другой консоли в текущем каталоге:

docker-compose down

Для запуска контейнеров в режиме "демона", выполните:

docker-compose up -d

При первом запуске база данных будет автоматически инициализирована.

Посмотреть логи можно с помощью команды:

docker-compose logs

По умолчанию, база данных сохраняется на диске в каталоге qhb/pgdata.

Остановка контейнеров

Если контейнеры были запущен посредством docker-compose up, то для остановки достаточно нажать Ctrl+C. Если же контейнеры были запущены в режиме "демона", т.е. посредством docker-compose up -d, то для остановки контейнеров выполните (из любой консоли) в текущем каталоге: docker-compose down. Эту команду также можно выполнять и при остановленных контейнерах.

Настройка QCP

По умолчанию, сервис QCP отключён. Для его запуска необходимо в файле docker-compose.yaml убрать (закомментировать) запись

entrypoint: ["echo", "Service qcp disabled"]

из раздела services: -> qcp:, а также настроить сервис, в частности, параметры подключения к серверу.

Настройка QCP осуществляется посредством редактирования файла ./qcp/config.yaml.

Обязательно замените в разделе servers:

%USER% - на имя пользователя, от имени которого запускается docker-compose, и

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

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

Отредактируйте файл docker-compose.yaml следующим образом:

В разделе services: -> qhb: -> volumes: замените

- ./qhb/pgdata:/qhb-data/

на

- /path/to/pgdata:/qhb-data/

где /path/to/pgdata — абсолютный путь до каталога базы данных с существующей базой данных.

В разделе services: -> qhb: -> environment: замените - USER на - USER=USERNAME

Запустите контейнер с помощью команды

docker-compose -e USER="USERNAME" up

где USERNAME — имя пользователя, владеющего каталогом /path/to/pgdata.

Пример отредактированного файла docker-compose.yaml:

version: "3.3"
services:
  qhb:
    build: qhb
    image: qhb
    network_mode: "host"
    environment:
      - USER=qhb
    volumes:
      - ./qhb/pgdata:/qhb-data/

  qcp:
    build: qcp
    image: qcp
    network_mode: "host"
    entrypoint: ["echo", "Service qcp disabled"]  # Comment this line if will use QCP
    volumes:
      - ./qcp/config.yaml:/config.yaml:ro

В данном сценарии уже подготовлены и при запуске будут проделаны шаги по инициализации кластера, запуску сервера и созданию базы данных.

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

Инициализация кластера базы данных

Создайте каталог для размещения базы данных командой

sudo mkdir <путь/имя каталога>

Например:

sudo mkdir /usr/local/qhb/data

Разрешите доступ к нему пользователю qhb командой

sudo chown qhb <путь/имя каталога>

В нашем случае:

sudo chown qhb /usr/local/qhb/data

Далее рекомендуется переключиться на пользователя qhb и выполнять команды от его имени. В ином случае необходимо использовать sudo -u qhb для всех последующих команд, если вы работаете от пользователя с правами sudo.

Инициализируйте кластер базы данных при помощи утилиты initdb или qhb_bootstrap

<путь к бинарным утилитам QHB>/initdb -D <путь/имя каталога> -U qhb

В нашем случае:

/usr/local/qhb/bin/initdb -D /usr/local/qhb/data -U qhb

или, если установлена переменная окружения $PATH:

initdb -D /usr/local/qhb/data -U qhb

В дальнейшем, данный каталог будет использоваться при запуске и остановке сервера QHB. Его можно указать в переменной окружения $PGDATA, что облегчит запуск следующих утилит - можно будет не указывать каталог в параметре -D.

Смотрите дополнительно: Создание кластера базы данных, initdb, qhb_bootstrap

Запуск и остановка сервера

Рекомендуется переключиться на пользователя qhb и выполнять команды от его имени. В ином случае необходимо использовать sudo -u qhb для всех последующих команд если вы работаете от пользователя с правами sudo.

Для запуска сервера используйте команду:

<путь к бинарным утилитам QHB>/qhb_ctl -D <путь/имя каталога> start

В нашем случае:

/usr/local/qhb/bin/qhb_ctl -D /usr/local/qhb/data start

Или, если установлены переменные окружения $PGDATA и $PATH:

qhb_ctl start

Для остановки сервера используйте команду:

<путь к бинарным утилитам QHB>/qhb_ctl -D <путь/имя каталога> stop

В нашем случае:

/usr/local/qhb/bin/qhb_ctl -D /usr/local/qhb/data stop

Или, если установлена переменная окружения $PGDATA:

qhb_ctl stop

Смотрите дополнительно: Запуск сервера базы данных, Завершение работы сервера

Запуск и остановка сервера с помощью сервиса systemd

Замечание.
Описывается запуск QHB сервиса через подсистему инициализации и управления службами systemd. Уточните, что она установлена в вашем дистрибутиве Linux.

При установке из пакета rpm, имеется возможность использовать сервис systemd для автоматического запуска сервера БД при старте системы. Для этого, необходимо уточнить предварительно установленный скрипт запуска сервиса. Если необходимо поменять расположение каталога базы данных, задаваемое по умолчанию, выполните:

sudo systemctl edit qhb

Далее, в открывшемся редакторе (файл изначально пуст) укажите нужный путь:

[Service]
Environment=PGDATA=/opt/qhb/data

Сохраните изменения и завершите работу редактора.

Перестройте сервис и, если необходимо, разрешите ему запускаться при перезагрузке ОС:

sudo systemctl daemon-reload
sudo systemctl enable qhb

В дальнейшем, после начальной настройки (см. Начало работы), запускать сервис нужно будет командой:

sudo systemctl start qhb

А останавливать командой:

sudo systemctl stop qhb

Создание базы данных

Первый тест, чтобы увидеть, можете ли вы получить доступ к серверу базы данных - попытаться создать базу данных. Работающий сервер QHB может управлять многими базами данных. Как правило, отдельная база данных используется для каждого проекта или для каждого пользователя.

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

Чтобы создать новую базу данных, в этом примере с именем mydb, вы используете следующую команду:

createdb mydb -h localhost

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

Если вы видите сообщение, похожее на:

createdb: command not found

тогда QHB не был установлен должным образом. Либо он вообще не был установлен, либо путь поиска вашей оболочки не был настроен на его включение. Попробуйте вместо этого вызвать команду с абсолютным путем:

/usr/local/qhb/bin/createdb mydb

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

Другой ответ может быть таким:

createdb: could not connect to database qhb: could not connect to server: No such file or directory
        Is the server running locally and accepting
        connections on Unix domain socket "/tmp/.s.PGSQL.5432"?

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

Другой ответ может быть таким:

createdb: could not connect to database qhb: FATAL:  role "joe" does not exist

где упоминается ваше имя пользователя. Это произойдет, если администратор не создал для вас учетную запись пользователя QHB. (Учетные записи пользователей QHB отличаются от учетных записей пользователей операционной системы). Если вы являетесь администратором, обратитесь к главе Роли в базе данных за помощью в создании учетных записей. Вам нужно стать пользователем операционной системы, под которой был установлен QHB (обычно qhb), чтобы создать первую учетную запись пользователя. Возможно также, что вам было присвоено имя пользователя QHB, отличающееся от имени пользователя вашей операционной системы; в этом случае вам нужно использовать ключ -U или установить окружение PGUSER, чтобы указать свое имя пользователя в QHB.

Если у вас есть учетная запись пользователя, но у нее нет прав, необходимых для создания базы данных, вы увидите следующее:

createdb: database creation failed: ERROR:  permission denied to create database

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

Вы также можете создавать базы данных с другими именами. QHB позволяет создавать любое количество баз данных. Имена баз данных должны иметь алфавитный первый символ и иметь длину не более 63 байтов. Удобный выбор - создать базу данных с тем же именем, что и ваше текущее имя пользователя. Многие инструменты предполагают, что имя базы данных используется как имя по умолчанию, поэтому оно поможет вам сэкономить время при наборе текста. Чтобы создать эту базу данных, просто введите:

createdb

Если вы больше не хотите использовать свою базу данных, вы можете удалить ее. Например, если вы являетесь владельцем (создателем) базы данных mydb, вы можете уничтожить ее, используя следующую команду:

dropdb mydb

(Для этой команды имя базы данных по умолчанию не совпадает с именем учетной записи пользователя. Вы всегда должны указывать его.) Это действие физически удаляет все файлы, связанные с базой данных, и не может быть отменено, так что это должно быть сделано только с большим количеством предусмотрительности.

Больше информации по командам createdb и dropdb можно найти в соответствующих разделах.

1

В качестве объяснения того, почему это работает: имена пользователей QHB отделены от учетных записей пользователей операционной системы. Когда вы подключаетесь к базе данных, вы можете выбрать, какое имя пользователя QHB будет подключаться; если вы этого не сделаете, по умолчанию будет использоваться то же имя, что и ваша текущая учетная запись операционной системы. Как это бывает, всегда будет учетная запись пользователя QHB, имя которой совпадает с именем пользователя операционной системы, запустившего сервер, и также бывает, что этот пользователь всегда имеет разрешение на создание баз данных. Вместо входа в систему под этим пользователем вы также можете указать опцию -U везде, чтобы выбрать имя пользователя QHB для подключения.

Доступ к базе данных

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

  • С помощью интерактивного терминала QHB, называемого qsql, который позволяет в интерактивном режиме вводить, редактировать и выполнять команды SQL.

  • С использованием существующего графического инструмента внешнего интерфейса, например, pgAdmin, DBeaver или офисного пакета с поддержкой ODBC или JDBC. Эти возможности не рассматриваются в этом руководстве.

  • Написав собственное приложение с использованием одной из нескольких доступных языковых привязок.

Возможно, вы захотите запустить qsql, чтобы попробовать примеры из этого урока. Его можно запустить для базы данных mydb, набрав команду:

$ qsql -h localhost -d mydb

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

Внутри qsql вы увидите следующее сообщение:

qsql - Interactive terminal qhb (1.2.0)
Enter "\help" in order to get help

mydb(username)=#

Это будет означать, что вы являетесь суперпользователем базы данных, что наиболее вероятно, если вы установили экземпляр QHB самостоятельно. Суперпользователь имеет неограниченный доступ к базе данных; впрочем, для целей урока это не имеет значения.

Если вы столкнулись с проблемами при запуске qsql, вернитесь к предыдущему разделу. Диагностика createdb и qsql схожи, и если первый сработал, последний также должен сработать.

Последняя строка, напечатанная qsql является приглашением и указывает, что qsql ожидает ввод, то есть вы можете вводить запросы SQL в рабочее пространство. Попробуйте эти команды:

mydb(username)=# select version();
version   
----------
QHB 1.2.0 
(1 строка)

mydb(username)=# SELECT current_date;
    date
------------
 2020-10-07

mydb(username)=# SELECT 2 + 2;
 ?column?
----------
4
(1 строка)

Программа qsql имеет ряд внутренних команд, которые не являются командами SQL. Они начинаются с символа обратной косой черты "\". Например, чтобы выйти из qsql, введите:

mydb(username)=# \q

и qsql завершит работу и вернёт вас в командную оболочку.

Все возможности qsql описаны в соответствующем разделе: qsql.