Step-by-Step Guides for Initial Download, Installation, Activation and Launch

This section describes the scenario of the first time DBMS «Quantum Hybrid Base» installation or installation and upgrade during initial database cluster initialization if it is possible to backup and restore data to a newly created cluster.

WARNING!
In cases where

an update or migration (binary) from other DBMS or from younger versions of DBMS «Quantum Hybrid Base» is required;

the database directory already exists and cannot be recreated;

it is necessary to save the data of the already used database in binary form

refer to Section Brief Upgrade Guide.
It is also highly recommended that you use the backup and restore procedures.

Downloading and Installing Binary Packages

Downloading and installing binary packages is performed from the DBMS «Quantum Hybrid Base» repository. Please refer to Section Supported Platforms to find out which platforms are supported by DBMS «Quantum Hybrid Base».

Note
Commands must be executed by a user with superuser privileges. If the user does not have superuser privileges, execute the following command in the terminal (you will need to enter the superuser password):
su -
or temporarily elevate the user's privileges to superuser via the command
sudo -i

For Centos 7 and 8

Note
Note that the commands must be executed by a user with superuser privileges.

Install the config-manager utility to manage repository configuration:

dnf install dnf-plugin-config-manager

Install the software product DBMS «Quantum Hybrid Base» repository using the command:

rpm --import https://repo.quantom.info/qhb/keys/RPM-GPG-KEY-qhb

Install the additional epel-release repository:

yum -y install epel-release

and then execute for CentOS 7:

dnf config-manager --add-repo https://repo.quantom.info/qhb/std-1/centos/7/x86_64/qhb.repo

To install qhb-patroni and postgis you need to add the postgresql repository:

 yum -y -q install https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm

For CentOS 8, execute:

dnf config-manager --add-repo https://repo.quantom.info/qhb/std-1/centos/8/x86_64/qhb.repo

Note
This OS may have problems installing DBMS «Quantum Hybrid Base» and its extensions due to lack of available repositories. Support for this OS may be removed in a future release.

To install qhb-patroni and postgis you need to add the postgresql repository:

 yum -y -q install https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm

For CentOS 8, if you need to install the postgis extension, additional repositories are required:

dnf config-manager --add-repo https://repo.quantom.info/qhb/additional-package/centos/8/qhb-add.repo
dnf config-manager --set-enabled powertools

Install binary packages using the command:

dnf install qhb-core qhb-contrib qcp qdl qdlm qbackup metricsd qhb-serial qluster qman qman-backend

Not all packages can be installed, but the minimum is to install the QHB kernel, for example:

dnf install qhb-core

Installing the QHB core package will create the user qhb. The QHB core will install itself into the /usr/local/qhb directory by default. Many QHB utilities are installed into the /usr/local/qhb/bin directory. Specifying this directory in the $PATH environment variable will make it easier to run them.

See also: Section Distribution Package, Section Download Page

For RED OS 7 and 8

Note
Note that commands must be executed by a user with superuser privileges.

Install the config-manager utility to manage repository configuration:

dnf install dnf-plugin-config-manager

Install the software product DBMS «Quantum Hybrid Base» repository with the command:

rpm --import https://repo.quantom.info/qhb/keys/RPM-GPG-KEY-qhb

and then execute for РЕД ОС 7:

dnf config-manager --add-repo https://repo.quantom.info/qhb/std-1/redos7/x86_64/qhb.repo

for РЕД ОС 8:

dnf config-manager --add-repo https://repo.quantom.info/qhb/std-1/redos8/x86_64/qhb.repo

Install binary packages using the command:

dnf install qhb-core qhb-contrib qcp qdl qdlm qbackup metricsd qhb-serial qluster qman qman-backend

Not all packages can be installed, but the minimum is to install the QHB kernel, for example:

dnf install qhb-core

See also: Section Distribution Package, Section Download Page

For ROSA CHROME 12.6

Note
Note that commands must be executed by a user with superuser privileges.

Install the config-manager utility to manage repository configuration:

dnf install dnf-plugin-config-manager

Install the software product DBMS «Quantum Hybrid Base» repository with the command:

rpm --import https://repo.quantom.info/qhb/keys/RPM-GPG-KEY-qhb

and then:

dnf config-manager --add-repo https://repo.quantom.info/qhb/std-1/rosa/x86_64/qhb.repo

Install binary packages using the command:

dnf install qhb-core qhb-contrib qcp qdl qdlm qbackup metricsd qhb-serial qluster qman qman-backend

Not all packages can be installed, but the minimum is to install the QHB kernel, for example:

dnf install qhb-core

See also: Section Distribution Package, Section Download Page

For Alt 8 SP

Note
Note that commands must be executed by a user with superuser privileges.

Note
The QHB DBMS supports Viola OS 8 SP only with core version 5.10.

Installation requires additional libraries libicu and libgostcrypto. You may also need to install or update the glibc library to version 2.34 or higher; check your library version in advance.

Download the library (version 60.3-2 is suitable) to any local folder:

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

Download the libgostcrypto library:

wget -c -r -l1 -A '*.rpm' -nd -np https://repo.quantom.info/qhb/std-1/centos/8/x86_64/libgostcrypto.0.6-0.6.1-1.x86_64.rpm

WARNING!
QHB DBMS for OS Viola 8 SP is supplied on disks. To receive it please contact us at qhb.support@quantom.info.

Copy all binary packages from the disk to a local folder and install using the command, for example:

apt-get install *.rpm

You can install not all QHB packages, but only those you need. In this case, you can list the rpm packages you need in the command, separated by a space. Select the latest versions from the rpm packages that have been downloaded.

The libicu library and the qhb-core package are required.

See also: Section Distribution Package, Section Download Page

For Alt Server 9

Note
Note that for DBMS «Quantum Hybrid Base» version 1.5.1 and above on the server under OS Alt Server 9 control, the GLIBC library version not older than 2.28 must be installed.

Note
Note that commands must be executed by a user with superuser privileges.

Installation requires additional library libicu. It's also possible you will need to install or update the glibc library.

Download the library (version 60.3-2 is suitable) to any local folder:

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

Download DBMS «Quantum Hybrid Base» software product packages from repository to the same local folder using the command:

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

Update package descriptions:

apt-get update

While in the same local folder, install the binary packages using the command, for example:

apt-get install *.rpm

The libicu library and the qhb-core package are required.

See also: Section Distribution Package, Section Download Page

For Fedora

Note
Note that the commands must be executed by a user with superuser privileges.

Install the config-manager utility to manage repository configuration:

dnf install dnf-plugin-config-manager

Install the software product DBMS «Quantum Hybrid Base» repository with the command:

rpm --import https://repo.quantom.info/qhb/keys/RPM-GPG-KEY-qhb

and then, for Fedora 36

Note
For this OS there may be problems with installing DBMS «Quantum Hybrid Base» and its extensions due to lack of available repositories. Support for this OS may be removed in the next release.

dnf config-manager --add-repo https://repo.quantom.info/qhb/std-1/fedora/36/x86_64/qhb.repo

for Fedora 37

Note
For this OS there may be problems with installing DBMS «Quantum Hybrid Base» and its extensions due to lack of available repositories. Support for this OS may be removed in the next release.

dnf config-manager --add-repo https://repo.quantom.info/qhb/std-1/fedora/37/x86_64/qhb.repo

for Fedora 38

Note
For this OS there may be problems with installing DBMS «Quantum Hybrid Base» and its extensions due to lack of available repositories. Support for this OS may be removed in the next release.

dnf config-manager --add-repo https://repo.quantom.info/qhb/std-1/fedora/38/x86_64/qhb.repo

for Fedora 39

Note
For this OS there may be problems with installing DBMS «Quantum Hybrid Base» and its extensions due to lack of available repositories. Support for this OS may be removed in the next release.

dnf config-manager --add-repo https://repo.quantom.info/qhb/std-1/fedora/39/x86_64/qhb.repo

for Fedora 40

Note
For this OS there may be problems with installing DBMS «Quantum Hybrid Base» and its extensions due to lack of available repositories. Support for this OS may be removed in the next release.

dnf config-manager --add-repo https://repo.quantom.info/qhb/std-1/fedora/40/x86_64/qhb.repo

for Fedora 41

Note
For this OS there may be problems with installing DBMS «Quantum Hybrid Base» and its extensions due to lack of available repositories. Support for this OS may be removed in the next release.

dnf config-manager --add-repo https://repo.quantom.info/qhb/std-1/fedora/41/x86_64/qhb.repo

or for Fedora 42

Note
For this OS there may be problems with installing DBMS «Quantum Hybrid Base» and its extensions due to lack of available repositories. Support for this OS may be removed in the next release.

dnf config-manager --add-repo https://repo.quantom.info/qhb/std-1/fedora/42/x86_64/qhb.repo

Install binary packages using the command:

dnf install qhb-core qhb-contrib qcp qdl qdlm qbackup metricsd qhb-serial qluster qman qman-backend

Not all packages can be installed, but the minimum is to install the QHB kernel, for example:

dnf install qhb-core

See also: Section Distribution Package, Section Download Page

For Debian

Note
Note that the commands must be executed by a user with superuser privileges.

To connect to the repository execute the following command:

apt install gnupg2 apt-transport-https wget

For correct operation of the DBMS «Quantum Hybrid Base» repository entry must be added to the repository configuration file /etc/apt/sources.list:

for Debian 10

Note
For this OS there may be problems with installing DBMS «Quantum Hybrid Base» and its extensions due to lack of available repositories. Support for this OS may be removed in the next release.

deb [arch=amd64] https://repo.quantom.info/qhb/std-1/debian/10 stretch main

for Debian 12

deb [arch=amd64] https://repo.quantom.info/qhb/std-1/debian/12 stretch main

Install the software product DBMS «Quantum Hybrid Base» repository using the command:

wget -qO - https://repo.quantom.info/qhb/keys/RPM-GPG-KEY-qhb --no-check-certificate | apt-key add -

Then execute the commands:

for Debian 10

echo 'deb [arch=amd64] https://repo.quantom.info/qhb/std-1/debian/10 stretch main' >> /etc/apt/sources.list

and

apt update

Install binary packages using the command:

apt install qhb-core qhb-contrib qcp qdl qdlm qbackup metricsd qhb-serial qluster qman qman-backend

Not all packages can be installed, but the minimum is to install the QHB kernel, for example:

apt install qhb-core

See also: Section Distribution Package, Section Download Page

For Astra

Note
Note that the commands must be executed by a user with superuser privileges.

To connect to the repository execute the following command:

apt install gnupg2 apt-transport-https wget

For correct operation of the DBMS «Quantum Hybrid Base» repository entry must be added to the repository configuration file /etc/apt/sources.list:

for Astra Linux Special Edition «Смоленск» 1.7

deb [arch=amd64] https://repo.quantom.info/qhb/std-1/astra-smolensk/1.7/  stretch main

for Astra Linux Special Edition «Смоленск» 1.8

deb [arch=amd64] https://repo.quantom.info/qhb/std-1/astra-smolensk/1.8/  stretch main

Note
Note that to exclude revoked security certificates from OS Astra Linux you should perform cleaning according to instruction for stopping the use of unwanted certificate.

Astra requires installation of root certificates. Install them using the command:

apt-get install ca-certificates

Install the software product DBMS «Quantum Hybrid Base» repository using the command:

wget -qO - https://repo.quantom.info/qhb/keys/RPM-GPG-KEY-qhb --no-check-certificate | apt-key add -

Then execute the commands:

for Astra Linux Special Edition «Смоленск» 1.7

echo 'deb [arch=amd64] https://repo.quantom.info/qhb/std-1/astra-smolensk/1.7/ stretch main' >> /etc/apt/sources.list

for Astra Linux Special Edition «Смоленск» 1.8

ln -s /etc/apt/trusted.gpg /etc/apt/trusted.gpg.d/trusted.gpg
echo 'deb [arch=amd64] https://repo.quantom.info/qhb/std-1/astra-smolensk/1.8/ stretch main' >> /etc/apt/sources.list.d/qhb.list

and

apt update

Note
If the apt update command of the QHB repository for Astra 1.7 arises the error:

Ошб:6 https://repo.quantom.info/qhb/std-1/debian stretch InRelease Следующие
подписи не могут быть проверены, так как недоступен открытый ключ:
NO_PUBKEY 67A97AD5112F6828
-- Ошб:6 https://repo.quantom.info/qhb/std-1/debian stretch InRelease The following
-- signatures cannot be verified because the public key is not available:
-- NO_PUBKEY 67A97AD5112F6828

you need to execute the command to import the QHB repository key for Astra 1.7:

apt-key adv --keyserver https://repo.quantom.info/qhb/keys/RPM-GPG-KEY-qhb --recv-keys 67A97AD5112F6828

Install binary packages using the command:

apt install qhb-core qhb-contrib qcp qdl qdlm qbackup metricsd qhb-serial qluster qman qman-backend

Not all packages can be installed, but the minimum is to install the QHB kernel, for example:

apt install qhb-core

See also: Section Distribution Package, Section Download Page

For Ubuntu

Note
Note that the commands must be executed by a user with superuser privileges.

To connect to the repository execute the following command:

apt install gnupg2 apt-transport-https wget

For correct operation of the DBMS «Quantum Hybrid Base» repository entry must be added to the repository configuration file /etc/apt/sources.list:

for Ubuntu 18.04

Note
For this OS there may be problems with installing DBMS «Quantum Hybrid Base» and its extensions due to lack of available repositories. Support for this OS may be removed in the next release.

echo 'deb https://repo.quantom.info/qhb/std-1/ubuntu/18 stretch main' >> /etc/apt/sources.list

for Ubuntu 22.04

echo 'deb https://repo.quantom.info/qhb/std-1/ubuntu/22 stretch main' >> /etc/apt/sources.list

or for Ubuntu 24.04

echo 'deb https://repo.quantom.info/qhb/std-1/ubuntu/24 stretch main' >> /etc/apt/sources.list

Install the software product DBMS «Quantum Hybrid Base» repository using the command:

wget -qO - https://repo.quantom.info/qhb/keys/RPM-GPG-KEY-qhb --no-check-certificate | apt-key add -

Then execute:

apt update

Install binary packages using the command:

apt install qhb-core qhb-contrib qcp qdl qdlm qbackup metricsd qhb-serial qluster qman qman-backend

Not all packages can be installed, but the minimum is to install the QHB kernel, for example:

apt install qhb-core

See also: Section Distribution Package, Section Download Page

For openSUSE

Note
Note that the commands must be executed by a user with superuser privileges.

Install the software product DBMS «Quantum Hybrid Base» repository using the command:

rpm --import https://repo.quantom.info/qhb/keys/RPM-GPG-KEY-qhb

zypper ar 'http://download.opensuse.org/distribution/leap/15.4/repo/oss/' openSuseMain
zypper --gpg-auto-import-keys addrepo -f https://repo.quantom.info/qhb/std-1/opensuse/15.4/x86_64 QHB-Repo

To install the Patroni and PostGIS extensions, additional repositories are required:

zypper ar https://download.postgresql.org/pub/repos/zypp/repo/pgdg-sles-15-pg11.repo
zypper ar https://ftp.lysator.liu.se/pub/opensuse/repositories/science/openSUSE_Leap_15.3/ science15.3-x86_64
zypper ar https://ftp.lysator.liu.se/pub/opensuse/repositories/science/15.4/ science15.4-x86_64
zypper --releasever 15.5 --no-gpg-checks ref

You should install the qhb-patroni package (and only it) using the command with the following flag:

zypper --releasever 15.5 -n install qhb-patroni

and then:

zypper refresh

Install binary packages using the command:

zypper install qhb-core qhb-contrib qcp qdl qdlm qbackup metricsd qhb-serial qluster qman qman-backend

Not all packages can be installed, but the minimum is to install the QHB kernel, for example:

zypper install qhb-core

See also: Section Distribution Package, Section Download Page

For MosOS

Note
Note that commands must be executed by a user with superuser privileges.

Install the software product DBMS «Quantum Hybrid Base» repository using the command:

rpm --import https://repo.quantom.info/qhb/keys/RPM-GPG-KEY-qhb

zypper --gpg-auto-import-keys addrepo -f https://repo.quantom.info/qhb/std-1/mosos/15.5/x86_64 QHB

and then:

zypper refresh

Install binary packages using the command:

zypper install -y qhb-core qhb-contrib qcp qdl qdlm qbackup metricsd qhb-serial qluster qman qman-backend

Not all packages can be installed, but the minimum is to install the QHB kernel, for example:

zypper install -y qhb-core

See also: Section Distribution Package, Section Download Page

As a Docker Container

Configuration offered: DBMS «Quantum Hybrid Base» server with extensions and connection pool QCP.

Getting Dockerfile and Configurations

Create a local directory and deploy docker scripts from the DBMS «Quantum Hybrid Base» repository there:

wget https://repo.quantom.info/qhb/std-1/docker/qhb-docker-image.tar.gz -O - | tar -xz

Creating Images

WARNING!
It requires docker-compose. Here and further below you should execute docker-compose as a regular user (not root). For this, you may need to follow recommendations for setting up docker.

Normally, there is no need to create the image manually as it is automatically created at first run. However, this can also be done explicitly:

docker-compose build

Note
If you have problems building the image due to unavailability centos repository, you need to check the network permissions. Sometimes, before building, simply executing the following commands helps:
sudo firewall-cmd --zone=public --add-masquerade --permanent
sudo firewall-cmd --reload

Starting a Container

To start DBMS «Quantum Hybrid Base» and QCP containers with default settings, execute in the current directory:

docker-compose up

You can interrupt execution using Ctrl+C or by executing from another console in the current directory:

docker-compose down

To start containers in daemon mode, execute:

docker-compose up -d

On first run, the database will be automatically initialized.

You can view log entries using the command:

docker-compose logs

By default, the database is saved on disk in the qhb/pgdata directory.

Stopping Containers

If containers were started using docker-compose up, then to stop just press Ctrl+C. If the containers were started in “daemon” mode, i.e. using docker-compose up -d, then to stop them execute (from any console) docker-compose down in the current directory. This command can also be executed even when containers are stopped.

Setting up QCP

By default, the QCP service is disabled. To start it you need remove (comment out) in the file docker-compose.yaml entry

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

from the services: -> qcp: section, and also configure the service, in particular the connection parameters for the server.

Configuring QCP is done by editing the ./qcp/config.yaml file.

Be sure to replace in the servers section:

%USER% — to the username under which docker-compose is run
%DATABASE% — to the database name; in the simplest case, the database is created with the name matching the username.

In the future, if you create another database, this option may be will need to be changed. By default, the QCP service runs on port 8080, if necessary, override this setting. Please note that the settings only apply at start.

Edit the docker-compose.yaml file as follows:

In the services: -> qhb: -> volumes: section, replace

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

- /путь/до/pgdata:/qhb-data/

where /path/to/pgdata is the absolute path to the database directory from the existing database.

In the services: -> qhb: -> environment: section, replace - USER with - USER=USERNAME.

Start the container using the command

docker-compose -e USER="USERNAME" up

where USERNAME is the name of the user who owns the directory /path/to/pgdata.

Example of an edited docker-compose.yaml file:

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 out this string if you use QCP
      - ./qcp/config.yaml:/config.yaml:ro

In this scenario, the steps to initialize the cluster, start the server, and create the database are already prepared and will be performed during startup.

Therefore, the following steps in this instruction can be skipped. Section Accessing a Database may be useful.

License Activation

After installing DBMS «Quantum Hybrid Base», the license must be activated. Without license activation, the product is fully functional, but its performance is limited.

The license activation process for DBMS «Quantum Hybrid Base» includes the following steps. If you plan to install on multiple hosts, you must repeat these steps for each one.

Generation of host identification features

On the host where DBMS «Quantum Hybrid Base» is installed, run the qhb-serial utility:

qhb-serial --report

Save the output for transmission to the vendor.

Sending features to the vendor

Send the output of the qhb-serial utility to the technical support address qhb.support@quantom.info.

Obtaining and applying the license file

In the archive you received in response, extract the signed license file to the installation directory DBMS «Quantum Hybrid Base» on the host where it was installed. By default, this is /usr/local/qhb.

There is no need to restart DBMS «Quantum Hybrid Base». The license will be picked up automatically. You can see a message about the fact of its use in the server log.

Database Cluster Initialization

Create a directory to place the database using the command

sudo mkdir <path/directory_name>

For example:

sudo mkdir /var/lib/qhb/data

Allow access to it for user qhb using the command

sudo chown qhb <path/directory_name>

In our case:

sudo chown qhb /var/lib/qhb/data

Next, it is recommended to switch to the qhb user and execute commands as it. Otherwise, you must use sudo -u qhb for all subsequent commands if you are working as a user with sudo privileges.

Initialize the database cluster using the qhb_bootstrap or initdb utility.

<path_to_binary_utilities QHB>/qhb_bootstrap -D <path/directory_name> -U qhb

In our case:

/usr/local/qhb/bin/qhb_bootstrap -D /var/lib/qhb/data -U qhb

or, if the $PATH environment variable is set:

qhb_bootstrap -D /var/lib/qhb/data -U qhb

Later this directory will be used when starting and stopping the server QHB. It can be specified in the $PGDATA environment variable, which will make it easier to run the following utilities — you will not need to specify the directory in the -D parameter.

Starting and Stopping the Server

It is recommended to switch to the qhb user and execute the commands as it. Otherwise, you must use sudo -u qhb for all subsequent commands if you are working as a user with sudo privileges.

To start the server, use the command:

<path_to_binary_utilities QHB>/qhb_ctl -D <path/directory_name> start

In our case:

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

Or, if the $PGDATA and $PATH environment variables are set:

qhb_ctl start

To stop the server, use the command:

<path_to_binary_utilities QHB>/qhb_ctl -D <path/directory_name> stop

In our case:

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

or, if the $PGDATA environment variable is set:

qhb_ctl stop

See also: Section Starting the Database Server, Section Shutting Down the Server

Starting and Stopping a Server Using systemd Service

Note
This section describes how to start the QHB service via the subsystem of systemd services initialization and management. Make sure it is installed on your Linux distribution.

When installing from the rpm package, it is possible to use the systemd service to automatically start the database server at system startup. For this you need to make sure you have a pre-installed service startup script. If you need to change the location of the database directory, specified by default, execute:

sudo systemctl edit qhb

Then, in the opened editor (the file is initially empty), specify the desired path:

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

Save changes and exit the editor.

Rebuild the service and, if necessary, allow it to start during operating system reload:

sudo systemctl daemon-reload
sudo systemctl enable qhb

In the future, after the initial setup (see chapter Getting Started), you should start the service using the command:

sudo systemctl start qhb

And stop it using the command:

sudo systemctl stop qhb

Creating a Database

The first test to see whether you can access the database server is to try to create a database. A running QHB server can manage many databases. Typically, a separate database is used for each project or for each user.

Possibly, your site administrator has already created a database for your use. In that case you can omit this step and skip ahead to the next section.

To create a new database, in this example named mydb, you use the following command:

$ createdb mydb -h localhost

If this produces no response then this step was successful and you can skip over the remainder of this section.

If you see a message similar to:

createdb: command not found

then QHB was not installed properly. Either it was not installed at all or your shell's search path was not set to include it. Try calling the command with an absolute path instead:

$ /usr/local/qhb/bin/createdb mydb

The path at your site might be different. Contact your site administrator or check the installation instructions to correct the situation.

Another response could be this:

createdb: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: No such file or directory
        Is the server running locally and accepting connections on that socket?

This means that the server was not started, or it is not listening where createdb expects to contact it. Again, check the installation instructions or consult the administrator.

Another response could be this:

createdb: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: FATAL:  role "joe" does not exist

where your own login name is mentioned. This will happen if the administrator has not created a QHB user account for you. (QHB user accounts are distinct from operating system user accounts.) If you are the administrator, see Chapter Database Roles for help creating accounts. You will need to become the operating system user under which QHB was installed (usually qhb) to create the first user account. It could also be that you were assigned a QHB user name that is different from your operating system user name; in that case you need to use the -U switch or set the PGUSER environment variable to specify your QHB user name.

If you have a user account but it does not have the privileges required to create a database, you will see the following:

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

Not every user has authorization to create new databases. If QHB refuses to create databases for you then the site administrator needs to grant you permission to create databases. Consult your site administrator if this occurs. If you installed QHB yourself then you should log in for the purposes of this tutorial under the user account that you started the server as.¹

You can also create databases with other names. QHB allows you to create any number of databases at a given site. Database names must have an alphabetic first character and are limited to 63 bytes in length. A convenient choice is to create a database with the same name as your current user name. Many tools assume that database name as the default, so it can save you some typing. To create that database, simply type:

$ createdb

If you do not want to use your database anymore you can remove it. For example, if you are the owner (creator) of the database mydb, you can destroy it using the following command:

$ dropdb mydb

(For this command, the database name does not default to the user account name. You always need to specify it.) This action physically removes all files associated with the database and cannot be undone, so this should only be done with a great deal of forethought.

More about createdb and dropdb can be found in createdb and dropdb respectively.

As an explanation for why this works: QHB user names are separate from operating system user accounts. When you connect to a database, you can choose what QHB user name to connect as; if you don't, it will default to the same name as your current operating system account. As it happens, there will always be a QHB user account that has the same name as the operating system user that started the server, and it also happens that that user always has permission to create databases. Instead of logging in as that user you can also specify the -U option everywhere to select a QHB user name to connect as.

Accessing a Database

Once you have created a database, you can access it by:

Running the QHB interactive terminal program, called psql, which allows you to interactively enter, edit, and execute SQL commands.
Using an existing graphical frontend tool like pgAdmin, DBeaver or an office suite with ODBC or JDBC support to create and manipulate a database. These possibilities are not covered in this tutorial.
Writing a custom application, using one of the several available language bindings.

You probably want to start up psql to try the examples in this tutorial. It can be activated for the mydb database by typing the command:

$ psql -h localhost -d mydb

If you do not supply the database name then it will default to your user account name. You already discovered this scheme in the previous section using createdb.

In psql, you will be greeted with the following message:

psql - Interactive terminal qhb (1.5.3)
Enter "\help" in order to get help

mydb(username)=#

That would mean you are a database superuser, which is most likely the case if you installed the QHB instance yourself. Being a superuser means that you are not subject to access controls. For the purposes of this tutorial that is not important.

If you encounter problems starting psql then go back to the previous section. The diagnostics of createdb and psql are similar, and if the former worked the latter should work as well.

The last line printed out by psql is the prompt, and it indicates that psql is listening to you and that you can type SQL queries into a work space maintained by psql. Try out these commands:

mydb(username)=# select version();
version   
----------
QHB 1.5.3
(1 row)

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

mydb(username)=# SELECT 2 + 2;
 ?column?
----------
        4
(1 row)

The psql program has a number of internal commands that are not SQL commands. They begin with the backslash character, “\”. For example, you can get help on the syntax of various QHB SQL commands by typing:

mydb(username)=# \h

To get out of psql, type:

mydb(username)=# \q

and psql will quit and return you to your command shell. (For more internal commands, type \? at the psql prompt.) The full capabilities of psql are documented in psql. In this tutorial we will not use these features explicitly, but you can use them yourself when it is helpful.