## Chapter 17. Binary Installation

## 17.1. Installing Postgres Pro Enterprise on Linux

For Linux-based operating systems, Postgres Pro Enterprise is shipped as binary packages. Each Postgres Pro binary distribution consists of several packages. The package structure differs from vanilla PostgreSQL and offers the following installation modes:

- Quick installation and setup. The `postgrespro-ent-10` package installs and configures all the components required for a viable ready-to-use configuration of both server and client components. Choose this option if you are going to install a single Postgres Pro instance only, and you are not worried about possible conflicts with other PostgreSQL-based products.

- Custom installation. You can select any packages required for your purposes, including development packages. This option needs manual configuration, so a good grasp of Linux and understanding of PostgreSQL architecture are required. This is the only option to choose if you are going to use Postgres Pro in one of the following scenarios:

  - Install several Postgres Pro versions side by side, or together with other PostgreSQL-based products.

  - Perform an upgrade from a previous version, or migrate from a different PostgreSQL-based product.

  - Control Postgres Pro server execution using high availability software, such as pacemaker, instead of the standard system service management facility.

### 17.1.1. Supported Linux Distributions

Postgres Pro binary packages are available for the following Linux-based systems:

- Red Hat Enterprise Linux (RHEL) systems and its derivatives: CentOS 6/7, Red Hat Enterprise Linux 7, Rosa Enterprise Linux Server 6, ROSA COBALT (server edition) based on Rosa platform 6/7

- Debian-based systems: Debian 8/9, Ubuntu 16.04, Astra Linux Smolensk 1.5

- ALT Linux 8, ALT Linux SPT 7.0

- SUSE Linux Enterprise Server 11/12.1

### Note

Postgres Pro binary packages rely on the tzdata library provided by the operating system, so you must ensure that the latest available version is installed. If tzdata is outdated, the time in your database may be incorrect.

### 17.1.2. Quick Installation and Setup

If you only need to install a single Postgres Pro instance and are not going to use any other PostgreSQL-based products on your system, you can use the quick installation mode. The typical process is as follows:

1. Add the package repository required for your operating system. You can get the exact repositories and commands for supported Linux distributions from the Postgres Pro Enterprise support team.

2. Install the `postgrespro-ent-10` package. It will bring all the required components via dependencies, together with documentation, create the default database, start the database server, as well as enable server autostart at system boot and make all the provided programs available in `PATH`. In the quick installation mode, the database cluster is initialized with checksums enabled.

Once the installation completes, you can launch psql on behalf of the `postgres` user and connect to the newly created database.

### 17.1.3. Custom Installation

Splitting the distribution into multiple packages enables customizing the installation for different purposes: database servers, client systems, or development workstations. Custom installations need to be configured manually, but give you more flexibility in using the product. You can install several Postgres Pro versions side by side, as well as together with other PostgreSQL-based products. In particular, this may be required when performing upgrades, or migrating from a different PostgreSQL-based product.

To perform a custom installation, complete the following steps:

1. Add the package repository required for your operating system. You can get the exact repositories and commands for supported Linux distributions from the Postgres Pro Enterprise support team.

2. Choose Postgres Pro packages required for your purposes and install them using the standard installation commands for your Linux distribution. The available packages are listed in Table 17.1.

   As a result, all files get installed into the `/opt/pgpro/ent-10` directory.

3. Run the pg-wrapper utility provided in the `postgrespro-ent-10-client` package to make the installed client and server programs available via `PATH` and add SQL man pages to the man page configuration file:

       pg-wrapper links update

   For details on how to handle possible conflicts, see pg-wrapper .

4. If you chose to install the `postgrespro-ent-10-server` package, make sure to complete the following server setup:

   1. Create the default database by running the helper script pg-setup as root with the `initdb` option:

          /opt/pgpro/ent-10/bin/pg-setup initdb [initdb_options]

      where `initdb_options` are regular initdb options.

      ### Note

      pg-setup initializes the database cluster with checksums enabled. If this is not what you expect, do not use pg-setup for cluster initialization and run initdb directly instead.

      The `pg-setup` script performs database administration operations as user `postgres`. If you do not specify any initdb options, the default database is created in the `/var/lib/pgpro/ent-10/data` directory, using localization settings specified in the `LANG` environment variable for the current session. All the `LC_*` environment variables are ignored.

   2. Start the server using `pg-setup`, as follows:

          pg-setup service start

      Like vanilla PostgreSQL, Postgres Pro server runs on behalf of the `postgres` user.

      ### Note

      By default, automatic server startup is disabled, so you can manually control the database recovery after a system reboot. Optionally, you can configure the Postgres Pro server to start automatically. For details, see Section 17.1.3.2.

#### 17.1.3.1. Choosing the Packages to Install

The table below lists all the available Postgres Pro packages.

Table 17.1. Postgres Pro Packages

Package | Description
--- | ---
`postgrespro-ent-10` | Top-level package that installs and configures Postgres Pro for server and client systems. Do not use this package for upgrades or migrations.
`postgrespro-ent-10-client` | Standard client applications, such as psql or pg_dump.
`postgrespro-ent-10-libs` | Shared libraries required to deploy client applications, including libpq; runtime libraries for ECPG processor.
`postgrespro-ent-10-server` | Postgres Pro server and PL/pgSQL server-side programming language.
`postgrespro-ent-10-contrib` | Additional extensions and programs deployable on database servers.
`postgrespro-ent-10-pgprobackup` | pg_probackup utility.
`postgrespro-ent-10-devel` | Header files and libraries for developing client applications and server extensions. On Debian-based systems, this package is called `postgrespro-ent-10-dev`.
`postgrespro-ent-10-plperl` | Server-side programming language based on Perl.
`postgrespro-ent-10-plpython` | Server-side programming language based on Python.
`postgrespro-ent-10-plpython3` | Server-side programming language based on Python 3. This package is only available on Debian-based systems.
`postgrespro-ent-10-pltcl` | Server-side programming language based on Tcl.
`postgrespro-ent-10-docs` | Documentation (English).
`postgrespro-ent-10-docs-ru` | Documentation (Russian).
`postgrespro-ent-10-test` | Test scripts for the server. This package is only available on RHEL-based and SUSE systems.

Additionally, Postgres Pro provides separate packages with debug information for some operating systems:

- On Debian-based systems, see the `postgrespro-ent-10-dbg` package.

- On RHEL-based systems, see the `postgrespro-ent-10-debuginfo` package.

- On ALT Linux, all packages containing binary files have the corresponding `-debuginfo` packages.

Server installations require at least the following packages:

- `postgrespro-ent-10-server`

- `postgrespro-ent-10-client`

- `postgrespro-ent-10-libs`

To use additional Postgres Pro extensions, you must also install the `postgrespro-ent-10-contrib` package. On Debian-based systems, `postgrespro-ent-10-server` package depends on `postgrespro-ent-10-contrib` package, so the latter must always be installed together with the server.

For client installations, it is usually enough to install the `postgrespro-ent-10-client` and `postgrespro-ent-10-libs` packages. If you use custom applications and do not need standard client utilities such as psql, you can install the `postgrespro-ent-10-libs` package only.

Development workstations require at least the following packages:

- `postgrespro-ent-10-libs`

- `postgrespro-ent-10-devel`/ `postgrespro-ent-10-dev`

You may also want to install and configure the server with a test database on development systems. For details on additional configuration that may be required, Section 17.1.4.

#### 17.1.3.2. Enabling Automatic Server Startup

If you are running a custom installation, automatic server startup is disabled by default. Once the default database is created, you can configure the server to start automatically upon system boot using service management solutions available in your operating system or third-party high-availability software. To facilitate this task, `postgrespro-ent-10-server` package provides the pg-setup script, which is installed in the `/opt/pgpro/ent-10/bin` directory.

To enable server autostart, run the pg-setup script with the following options:

    pg-setup service enable

If required, you can disable server autostart using the same script:

    pg-setup service disable

Alternatively, you can use system service management solutions directly by running the autostart scripts for SysV-style init.d and systemd provided in the `postgrespro-ent-10-server` package. Depending on your Linux distribution, Postgres Pro supports different service management solutions:

Linux Distribution | Provided Scripts
--- | ---
RHEL 7, SLES 12.1 | systemd unit file
RHEL 6 and compatible distributions, SLES 11, ALT Linux 6 | SysV-style init.d script
Debian, Ubuntu, ALT Linux 7/8 | Both systemd unit file and SysV-style init.d script

To use systemd for automatic server startup, run the following command:

    systemctl enable postgrespro-ent-10.service

To use SysV-style init.d script:

- On RHEL 6, SLES 11, and ALT Linux systems, use `chkconfig` command to add the `postgrespro-ent-10` script to the appropriate runlevel. See `chkconfig` man page for the exact syntax.

- On Debian systems, use `update-rc.d`. See the corresponding man page for details.

### 17.1.4. Setting up Development Workstations

While installing `postgrespro-ent-10-libs` and `postgrespro-ent-10-devel`/ `postgrespro-ent-10-dev` packages may be enough, it is usually convenient to have the server set up on the development system. For quick setup, you can install `postgrespro-ent-10` package, which automatically configures the provided client and server programs and creates the default database. However, if you are going to use several PostgreSQL-based products simultaneously, follow the custom installation instructions in Section 17.1.3.

To compile programs with Postgres Pro libraries using the pg_config utility shipped with Postgres Pro, you have to make sure that its path is specified in the `PATH` environment variable before the path to any other pg_config version. If you do not have any other pg_config versions on your system, you can use pg-wrapper provided in the `postgrespro-ent-10-client` package to create a symbolic link to pg_config in the standard binary directory.

To compile programs using pkg-config command, add the `/opt/pgpro/ent-10/lib/pkgconfig/` path to the `PKG_CONFIG_PATH` environment variable.

#### 17.1.4.1. Using Third-Party Programs with Postgres Pro

To use Postgres Pro server with a client program provided with a third-party product, you can install the version of PostgreSQL libraries that was used to compile this program. For example, if this program is provided with vanilla PostgreSQL, you may need to install the `libpq` or `postgresql-libs` packages available for your Linux distribution. In this case, the program may not be able to use some new features of Postgres Pro server, but it is probably not designed to use them anyway.

If you prefer to use Postgres Pro libraries with a third-party program, or would like to enable support for a new feature that does not require client application change, such as SCRAM authentication, you can recompile your program with Postgres Pro libraries.

### Important

If the program is compiled with one version of libpq but used with another, its stable work cannot be guaranteed.

If you are creating `.rpm` or `.deb` packages for your program, it is recommended to do the following:

1. Add `/opt/pgpro/ent-10/bin` to `PATH` inside your build scripts (`.spec` files or `debian/rules`).

2. Specify `postgrespro-ent-10-dev` in the `BuildDepends` or `BuildRequires` tags for your program.

Thus, you can ensure that your package build process calls the right version of pg_config whenever the source package is rebuilt.

### 17.1.5. Running Multiple Postgres Pro Instances

To run several instances of Postgres Pro server with different data directories, do the following:

1. Install and configure Postgres Pro as explained in Section 17.1.2 or Section 17.1.3.

2. Once the first default database is created, run initdb specifying the path to a different data directory and any other parameters required to initialize another server instance.

3. Specify different ports for your server instances in the corresponding `postgresql.conf` files to avoid conflicts.

4. If required, configure automatic server startup, as follows:

   1. Create a copy of `/etc/init.d/postgrespro-ent-10` or `/lib/systemd/system/postgrespro-ent-10.service` with a different name, specifying the path to the data directory.

   2. Enable automatic server startup using the provided autostart scripts for your system service management facility instead of `pg-setup`, as described in Section 17.1.3.2. Make sure to use the renamed copies of the scripts you created in step 1.

### 17.1.6. Migrating to Postgres Pro

Different major versions of Postgres Pro, as well as different PostgreSQL-based products based on the same major version, can have binary incompatible databases, so you cannot replace the server binary and continue running. To convert databases that used previous major versions, you must perform a dump/restore using pg_dumpall or use the pg_upgrade utility. The first option is safer, while the second is faster and can significantly speed up the upgrade process for large databases.

For upgrade instructions specific to a particular release, see the Release Notes for the corresponding Postgres Pro version.