Step 4 - Installing the PGD software v4
Installing the PGD software
With the repositories configured, you can now install the Postgres Distributed software. You must perform these steps on each host before proceeding to the next step.
- Install the packages.
- Install the PGD packages, which include a server-specific BDR package and generic PGD CLI packages(
edb-bdr4-<postgresversion>
andedb-pgd-cli
).
- Install the PGD packages, which include a server-specific BDR package and generic PGD CLI packages(
- Ensure the Postgres database server was initialized and started.
- Use
systemctl status
to check the service is running. - If it isn't, initialize the database and start the service.
- Use
- Configure the BDR extension.
- Add the BDR extension (
$libdir/bdr
) at the start of theshared_preload_libraries
setting inpostgresql.conf
. - Set the
wal_level
GUC variable tological
inpostgresql.conf
. - Turn on commit timestamp tracking by setting
track_commit_timestamp
to'on'
inpostgresql.conf
. - Raise the maximum worker processes to 16 or higher by setting
max_worker_processes
to'16'
inpostgresql.conf
.The
max_worker_processes
valueThe
max_worker_processes
value is derived from the topology of the cluster, the number of peers, number of databases, and other factors. To calculate the needed value, see Postgres configuration/settings. The value of 16 was calculated for the size of cluster being deployed in this example and must be raised for larger clusters. - Set a password on the EnterprisedDB/Postgres user.
- Add rules to
pg_hba.conf
to allow nodes to connect to each other.- Ensure that these lines are present in
pg_hba.conf
:
- Ensure that these lines are present in
- Add a
.pgpass
file to allow nodes to authenticate each other.- Configure a user with sufficient privileges to be able to log into the other nodes.
- See The Password File in the Postgres documentation for more on the
.pgpass
file.
- Add the BDR extension (
- Restart the server.
- Verify the restarted server is running with the modified settings and that the BDR extension is available.
- Create the replicated database.
- Log in to the server's default database (
edb
for EDB Postgres Advanced Server,postgres
for EDB Postgres Extended Server and community Postgres). - Use
CREATE DATABASE bdrdb
to create the default PGD replicated database. - Log out and then log back in to
bdrdb
. - Use
CREATE EXTENSION bdr
to enable the BDR extension and PGD to run on that database.
- Log in to the server's default database (
The worked example that follows explores these steps in detail for EDB Postgres Advanced Server.
If you're installing PGD with EDB Postgres Extended Server or community Postgres, the steps are similar, but details such as package names and paths are different. These differences are summarized in Installing PGD for EDB Postgres Extended Server and Installing PGD for Postgresql.
Worked example
Install the packages
The first step is to install the packages. For each Postgres package, there's an edb-bdr4-<postgresversion>
package to go with it.
For example, if you're installing EDB Postgres Advanced Server (epas) version 14, you install edb-bdr4-epas14
.
There in one other packages to also install:
edb-pgd-cli
for the PGD command line tool
To install all of these packages on a RHEL or RHEL-compatible Linux, run:
Ensure the database is initialized and started
If it wasn't initialized and started by the database's package initialization (or you're repeating the process), you need to initialize and start the server.
To see if the server is running, you can check the service. The service name for EDB Advanced Server is edb-as-14
, so run:
If the server isn't running, the response is:
The "Active: inactive (dead)" tells you that you need to initialize and start the server.
You need to know the path to the setup script for your particular Postgres flavor.
For EDB Postgres Advanced Server, this script can be found in /usr/edb/as14/bin
as edb-as-14-setup
.
This command needs to be run with the initdb
parameter, passing an option setting the database to use UTF-8:
Once the database is initialized, start it, which enables you to continue configuring the BDR extension"
Configure the BDR extension
Installing EDB Postgres Advanced Server creates a system user enterprisedb with admin capabilities when connected to the database. In this example, this user configures the BDR extension.
Preload the BDR library
The BDR library needs to be preloaded with other libraries. EDB Postgres Advanced Server has a number of libraries already preloaded, so you have to prefix the existing list with the BDR library:
Tip
This command format (echo ... | sudo ... tee -a ...
) appends the echoed string to the end of the postgresql.conf
file, which is owned by another user.
Set the wal_level
The BDR extension needs to set the server to perform logical replication. You can do this by setting wal_level
to logical
:
Enable commit timestamp tracking
The BDR extension also needs the commit timestamp tracking enabled:
Raise max_worker_processes
To communicate between multiple nodes, Postgres Distributed nodes run more worker processes than usual. The default limit (8) is too low even for a small cluster.
The max_worker_processes
value is derived from the topology of the cluster, the number of peers, number of databases, and other factors.
To calculate the needed value, see Postgres configuration/settings.
This example, with a 3-node cluster, uses the value of 16.
Raise the maximum number of worker processes to 16 with this command:
This value must be raised for larger clusters.
Add a password to the Postgres enterprisedb user
To allow connections between nodes, a password needs to be set on the Postgres enterprisedb user.
This example uses the password secret
.
Select a different password for your deployments.
You will need this password when you get to Creating the PGD cluster.
Enable inter-node authentication in pg_hba.conf
Out of the box, Postgres allows local authentication and connections with the database but not external network connections.
To enable this, edit pg_hba.conf
and add appropriate rules, including rules for the replication users.
To simplify the process, use this command:
It appends the following to pg_hba.conf
, which enables the nodes to replicate:
Enable authentication between nodes
As part of the process of connecting nodes for replication, PGD logs into other nodes.
It performs that login as the user that Postgres is running under.
For EDB Postgres Advanced Server, this is the enterprisedb user.
That user needs credentials to log into the other nodes.
This example supplies these credentials using the .pgpass
file, which needs to reside in the user's home directory.
The home directory for enterprisedb is /var/lib/edb
.
Run this command to create the file:
You can read more about the .pgpass
file in The Password File in the PostgreSQL documentation.
Restart the server
After all these configuration changes, we recommend that you restart the server with:
Check the extension has been installed
At this point, it's worth checking the extension is actually available and the configuration was correctly loaded. You can query the pg_available_extensions
table for the BDR extension like this:
This command returns an entry for the extension and its version:
You can also confirm the other server settings using this command:
Create the replicated database
The server is now prepared for PGD.
Next, create a database named bdrdb
and install the BDR extension when logged into it.
Finally, test the connection by logging into the server.
You're connected to the server.
Execute the command \dx
to list extensions installed.
Notice that the BDR extension is listed in the table, showing that it's installed.
Summaries
Installing PGD4 for EDB Postgres Advanced Server
These are all the commands used in this section gathered together for your convenience.
Installing PGD for EDB Postgres Extended Server
If you're installing PGD with EDB Postgres Extended Server, there are a number of differences from the EDB Postgres Advanced Server installation:
- The BDR package to install is named
edb-bdrV-pgextendedNN
, where V is the PGD version and NN is the PGE version number. - Call a different setup utility:
/usr/edb/pgeNN/bin/edb-pge-NN-setup
- The service name is
edb-pge-NN
. - The system user is postgres, not enterprisedb.
- The home directory for the postgres user is
/var/lib/pgqsl
. shared_preload_libraries
is empty by default and needs only$libdir/bdr
added to it.
Installing PGD for PostgreSQL
If installing PGD with PostgreSQL, there are a number of differences from the EDB Postgres Advanced Server installation.
- The BDR package to install is named
edb-bdrV-pgNN
, where V is the PGD version and NN is the PostgreSQL version number. - Call a different setup utility:
/usr/pgsql-NN/bin/postgresql-NN-setup
. - The service name is
postgresql-NN
. - The system user is postgres, not enterprisedb.
- The home directory for the postgres user is
/var/lib/pgqsl
. shared_preload_libraries
is empty by default and needs only$libdir/bdr
added to it.