Beyond Linux® From Scratch (systemd Edition) - Version r12.2-652

Chapter 22. Databases

PostgreSQL-17.1

Introduction to PostgreSQL

PostgreSQL is an advanced object-relational database management system (ORDBMS), derived from the Berkeley Postgres database management system.

[Note]

Note

Development versions of BLFS may not build or run some packages properly if LFS or dependencies have been updated since the most recent stable versions of the books.

Package Information

PostgreSQL Dependencies

Optional

ICU-76.1, libxml2-2.13.5, libxslt-1.1.42, OpenLDAP-2.6.8, Linux-PAM-1.7.0, MIT Kerberos V5-1.21.3 and Bonjour

Optional (To Regenerate Documentation)

fop-2.10, docbook-4.5-dtd, docbook-dsssl-1.79, DocBook-utils-0.6.14, OpenJade-1.3.2, and SGMLSpm-1.1

Editor Notes: https://wiki.linuxfromscratch.org/blfs/wiki/postgresql

Installation of PostgreSQL

For enhanced security, it is better to have a dedicated group and user for running the PostgreSQL server. First, issue as the root user: 

groupadd -g 41 postgres &&
useradd -c "PostgreSQL Server" -g postgres -d /srv/pgsql/data \
        -u 41 postgres
[Note]

Note

There are several configuration items that add additional functionality with optional packages to PostgreSQL. Use ./configure --help to see a list.

Install PostgreSQL with the following commands: 

sed -i '/DEFAULT_PGSOCKET_DIR/s@/tmp@/run/postgresql@' src/include/pg_config_manual.h &&

./configure --prefix=/usr \
            --docdir=/usr/share/doc/postgresql-17.1 &&
make

There are a number of programs in the contrib/ directory. If you are going to run this installation as a server and wish to build some of them, enter make -C contrib or make -C contrib/<SUBDIR-NAME> for each subdirectory.

Tests must be run as an unprivileged user because they need to start a temporary server and this is prevented as the root user. For the same reason, you need to stop all PostgreSQL servers if any are running. If a previous version of PostgreSQL is installed, it may be necessary to use --disable-rpath with configure to avoid failures, but installing the binaries created using this switch is not recommended. To test the results, issue: make check.

[Note]

Note

If you are installing PostgreSQL to upgrade an existing installation, there are important steps that you need to follow. If the major version of the new build is greater than the previous version, there is a chance that the data file format has changed. New software cannot use the existing data files. In this case, the server will not start because the old programs have been overwritten, so the data is unavailable until it's file format has been converted.

Before upgrading an existing installation of PostgreSQL, check the documentation for any considerations that you must keep in mind during the upgrade. Note that new major versions might use a different binary format in the data objects, causing potential incompatibilities. For more information, please review upstream's documentation about upgrading PostgreSQL here: https://www.postgresql.org/docs/current/upgrading.html.

At this point, you may have both the old and the new binaries installed on your filesystem. These binaries can be used to perform an upgrade of your existing database files. For the following instructions it is assumed that

  • The actual data files are stored in /srv/pgsql/data

  • The upgraded data files will be stored in /srv/pgsql/newdata

  • There is enough disk space to hold the actual data files twice. The upgrade is not an inline upgrade but it will copy the data to new database files.

First, do a temporary install which makes access to the new binaries much easier: 

make DESTDIR=$(pwd)/DESTDIR install

Next, create a directory which is writable by the postgres user, as the root user: 

install -d -o postgres $(pwd)/DESTDIR/tmp

Now, stop the existing instance of PostgreSQL and start the upgrade process as the root user: 

pushd $(pwd)/DESTDIR/tmp
systemctl stop postgresql
su postgres -c "../usr/bin/initdb -D /srv/pgsql/newdata"
su postgres -c "../usr/bin/pg_upgrade \
                    -d /srv/pgsql/data    -b /usr/bin \
                    -D /srv/pgsql/newdata -B ../usr/bin"
popd

At this point, your database files are available in two locations on disk. The old data is located in /srv/pgsql/data, and the new data is in /srv/pgsql/newdata. Backing up the old database files is recommended before continuing.

Next, remove the old database files, and rename the new data directory as the root user: 

rm -rf /srv/pgsql/data
mv /srv/pgsql/newdata /srv/pgsql/data

Now, as the root user: 

make install      &&
make install-docs

If you made any of the contrib/ programs, as the root user: 

make -C contrib/<SUBDIR-NAME> install
[Tip]

Tip

If you only intend to use PostgreSQL as a client to connect to a server on another machine, your installation is complete and you should not run the remaining commands.

If you have upgraded an existing database, skip the rest of the commands because your database is ready to use. If this is the first time you install PostgreSQL, continue with the initialization.

Initialize a database cluster with the following commands issued by the root user: 

install -v -dm700 /srv/pgsql/data &&
install -v -dm755 /run/postgresql &&
chown -Rv postgres:postgres /srv/pgsql /run/postgresql

Now, initialize the database as the root user: 

su - postgres -c '/usr/bin/initdb -D /srv/pgsql/data'

Command Explanations

sed -i ...: This sed changes the server socket location from /tmp to /run/postgresql.

--with-openssl: builds the package with support for OpenSSL encrypted connections.

--with-perl: builds the PL/Perl server-side language.

--with-python: builds the PL/Python server-side language.

--with-tcl: builds the PL/Tcl server-side language.

Configuring PostgreSQL

Config Files

$PGDATA/pg_ident.con, $PGDATA/pg_hba.conf, and $PGDATA/postgresql.conf

The PGDATA environment variable is used to distinguish database clusters from one another by setting it to the value of the directory which contains the cluster desired. The three configuration files exist in every PGDATA/ directory. Details on the format of the files and the options that can be set in each can be found in /usr/share/doc/postgresql-17.1/html/index.html.

Systemd Unit

Install the postgresql.service unit included in the blfs-systemd-units-20240916 package: 

make install-postgresql

Starting the PostgreSQL Server and Creating a Sample Database

The database server can be manually started with the following command (as the root user): 

su - postgres -c '/usr/bin/postgres -D /srv/pgsql/data > \
                  /srv/pgsql/data/logfile 2>&1 &'
[Note]

Note

If you are scripting this part, you should wait for the server to start before going on, by adding for example sleep 2 after the above command.

The instructions below show how to create a database, add a table to it, insert some rows into the table and select them, to verify that the installation is working properly. Still as user root, issue: 

su - postgres -c '/usr/bin/createdb test' &&
echo "create table t1 ( name varchar(20), state_province varchar(20) );" \
    | (su - postgres -c '/usr/bin/psql test ') &&
echo "insert into t1 values ('Billy', 'NewYork');" \
    | (su - postgres -c '/usr/bin/psql test ') &&
echo "insert into t1 values ('Evanidus', 'Quebec');" \
    | (su - postgres -c '/usr/bin/psql test ') &&
echo "insert into t1 values ('Jesse', 'Ontario');" \
    | (su - postgres -c '/usr/bin/psql test ') &&
echo "select * from t1;" | (su - postgres -c '/usr/bin/psql test')

When you are done with testing, you can shut down the server, by issuing as root: 

su - postgres -c "/usr/bin/pg_ctl stop -D /srv/pgsql/data"

Contents

Installed Programs: clusterdb, createdb, createuser, dropdb, dropuser, ecpg, initdb, pg_amcheck, pg_archivecleanup, pg_basebackup, pg_checksums, pg_config, pg_controldata, pg_ctl, pg_dump, pg_dumpall, pg_isready, pg_receivewal, pg_recvlogical, pg_resetwal, pg_restore, pg_rewind, pg_test_fsync, pg_test_timing, pg_upgrade, pg_verifybackup, pg_waldump, pgbench, postgres, psql, reindexdb, vacuumdb, optionally, if Tcl support has been built, pltcl_delmod, pltcl_listmod, pltcl_loadmod, and optionally (in contrib/) oid2name, pg_standby, vacuumlo, and many others
Installed Libraries: libecpg.{so,a}, libecpg_compat.{so,a}, libpgcommon.a, libpgcommon_shlib.a, libpgfeutils.a, libpgport.a, libpgport_shlib.a, libpgtypes.{so,a}, libpq.{so,a}, various charset modules and optionally programming language modules under /usr/lib/postgresql
Installed Directories: /usr/include/{libpq,postgresql}, /usr/lib/postgresql, /usr/share/{doc/postgresql-17.1,postgresql}, and /srv/pgsql

Short Descriptions

clusterdb

is a utility for reclustering tables in a PostgreSQL database

createdb

creates a new PostgreSQL database

createuser

defines a new PostgreSQL user account

dropdb

removes a PostgreSQL database

dropuser

removes a PostgreSQL user account

ecpg

is the embedded SQL preprocessor

initdb

creates a new database cluster

oid2name

resolves OIDs (Object IDs) and file nodes in a PostgreSQL data directory

pg_amcheck

checks for corruption in one or more PostgreSQL databases

pg_archivecleanup

cleans up PostgreSQL WAL (write-ahead log) archive files

pg_basebackup

takes base backups of a running PostgreSQL cluster

pg_checksums

enables, disables, or checks data checksums in a PostgreSQL database cluster

pg_config

retrieves PostgreSQL version information

pg_controldata

returns information initialized during initdb, such as the catalog version and server locale

pg_ctl

controls stopping and starting the database server

pg_dump

dumps database data and metadata into scripts which are used to recreate the database

pg_dumpall

recursively calls pg_dump for each database in a cluster

pg_isready

checks the connection status of a PostgreSQL server

pg_receivewal

is used to stream write-ahead logs from a PostgreSQL server

pg_recvlogical

controls PostgreSQL logical decoding streams

pg_resetwal

resets the write-ahead log and other control information of a PostgreSQL database cluster

pg_restore

creates databases from dump files created by pg_dump

pg_rewind

synchronizes a PostgreSQL data directory with another data directory that was forked from the first one

pg_standby

supports the creation of a PostgreSQL warm standby server

pg_test_fsync

determines the fastest wal_sync method for PostgreSQL

pg_test_timing

measures timing overhead

pg_upgrade

upgrades a PostgreSQL server instance

pg_verifybackup

verifies the integrity of a base backup of a PostgreSQL cluster

pg_waldump

displays a human-readable rendering of the write-ahead log of a PostgreSQL database cluster

pgbench

runs a benchmark test on PostgreSQL

pltcl_delmod

is a support script used to delete a module from a PL/Tcl table. The command requires the Pgtcl package to be installed

pltcl_listmod

is a support script used to list the modules in a PL/Tcl table. The command requires the Pgtcl package to be installed

pltcl_loadmod

is a support script used to load a module into a PL/Tcl table. The command requires the Pgtcl package to be installed

postgres

is the PostgreSQL database server

psql

is a console based database shell

reindexdb

is a utility for rebuilding indexes in a database

vacuumdb

compacts databases and generates statistics for the query analyzer

vacuumlo

removes orphaned large objects from a PostgreSQL database

libecpg.{so,a}

contains functions to support embedded SQL in C programs

libecpg_compat.{so,a}

is the ecpg compatibility library

libgport.a

is the port-specific subsystem of the Postgres backend

libpgtypes.{so,a}

contains functions for dealing with Postgres data types

libpq.{so,a}

is the C programmer's API to Postgres