diff --git a/docs/enable-extensions.md b/docs/enable-extensions.md index 3fda56507..9a0948df5 100644 --- a/docs/enable-extensions.md +++ b/docs/enable-extensions.md @@ -1,8 +1,8 @@ -# Enable Percona Distribution for PostgreSQL extensions +# Enable Percona Distribution for PostgreSQL components -Some extensions require additional configuration before using them with Percona Distribution for PostgreSQL. This sections provides configuration instructions per extension. +Some components require additional configuration before using them with Percona Distribution for PostgreSQL. This sections provides configuration instructions per extension. -**Patroni** +## Patroni Patroni is the third-party high availability solution for PostgreSQL. The [High Availability in PostgreSQL with Patroni](solutions/high-availability.md) chapter provides details about the solution overview and architecture deployment. @@ -10,9 +10,10 @@ While setting up a high availability PostgreSQL cluster with Patroni, you will n - Patroni installed on every ``postresql`` node. -- Distributed Configuration Store (DCS). Patroni supports such DCSs as etcd, zookeeper, Kubernetes though [etcd](https://etcd.io/) is the most popular one. It is available within Percona Distribution for PostgreSQL for all supported operating systems. - -- [HAProxy :octicons-link-external-16:](http://www.haproxy.org/). +- Distributed Configuration Store (DCS). Patroni supports such DCSs as ETCD, zookeeper, Kubernetes though [ETCD](https://etcd.io/) is the most popular one. ETCD is included in Percona distribution for PostgreSQL. + +- [HAProxy](http://www.haproxy.org/). + See the configuration guidelines for [Debian and Ubuntu](solutions/ha-setup-apt.md) and [RHEL and CentOS](solutions/ha-setup-yum.md). @@ -25,7 +26,7 @@ See the configuration guidelines for [Debian and Ubuntu](solutions/ha-setup-apt. - [PostgreSQL HA with Patroni: Your Turn to Test Failure Scenarios :octicons-link-external-16:](https://www.percona.com/blog/2021/06/11/postgresql-ha-with-patroni-your-turn-to-test-failure-scenarios/) -**pgBadger** +## pgBadger Enable the following options in `postgresql.conf` configuration file before starting the service: @@ -43,7 +44,31 @@ log_error_verbosity = default For details about each option, see [pdBadger documentation :octicons-link-external-16:](https://github.com/darold/pgbadger/#POSTGRESQL-CONFIGURATION). -**pgAudit set-user** +## pgaudit + +Add the `pgaudit` to `shared_preload_libraries` in `postgresql.conf`. The recommended way is to use the [ALTER SYSTEM](https://www.postgresql.org/docs/16/sql-altersystem.html) command. [Connect to psql](#connect-to-the-postgresql-server) and use the following command: + +```sql +ALTER SYSTEM SET shared_preload_libraries = 'pgaudit'; +``` + +Start / restart the server to apply the configuration. + +To configure `pgaudit`, you must have the privileges of a superuser. You can specify the settings in one of these ways: + +* globally (in postgresql.conf or using ALTER SYSTEM ... SET), +* at the database level (using ALTER DATABASE ... SET), +* at the role level (using ALTER ROLE ... SET). Note that settings are not inherited through normal role inheritance and SET ROLE will not alter a user's pgAudit settings. This is a limitation of the roles system and not inherent to pgAudit. + +Refer to the [pgaudit documentation](https://github.com/pgaudit/pgaudit/blob/master/README.md#settings) for details about available settings. + +To enable `pgaudit`, connect to psql and run the CREATE EXTENSION command: + +```sql +CREATE EXTENSION pgaudit; +``` + +## pgaudit set-user Add the `set-user` to `shared_preload_libraries` in `postgresql.conf`. The recommended way is to use the [ALTER SYSTEM :octicons-link-external-16:](https://www.postgresql.org/docs/12/sql-altersystem.html) command. [Connect to psql](connect.md) and use the following command: @@ -53,9 +78,42 @@ ALTER SYSTEM SET shared_preload_libraries = 'set-user'; Start / restart the server to apply the configuration. -You can fine-tune user behavior with the [custom parameters :octicons-link-external-16:](https://github.com/pgaudit/set_user#configuration-options) supplied with the extension. +Install the extension into your database: + +```sql +psql +CREATE EXTENSION set_user; +``` + +You can fine-tune user behavior with the [custom parameters](https://github.com/pgaudit/set_user#configuration-options) supplied with the extension. + +## pgbouncer + +`pgbouncer` requires the `pgbouncer.ini` configuration file to start. The default path is `/etc/pgbouncer/pgbouncer.ini`. When installing `pgbouncer` from a [tarball](tarball.md), the path is `percona-pgbouncer/etc/pgbouncer.ini`. + +Find detailed information about configuration file options in the [`pgbouncer documentation`](https://www.pgbouncer.org/config.html). + +## pgpool2 + +`pgpool-II` requires the configuration file to start. When you install pgpool from a package, the configuration file is automatically created for you at the path `/etc/pgpool2/pgpool.conf` on Debian and Ubuntu and `/etc/pgpool-II/pgpool.conf` on RHEL and derivatives. + +When you installed pgpool from tarballs, you can use the sample configuration file `/percona-pgpool-II/etc/pgpool2/pgpool.conf.sample`: + +```{.bash data-prompt="$"} +$ cp /percona-pgpool-II/etc/pgpool2/pgpool.conf.sample /pgpool.conf +``` + +Specify the path to it when starting pgpool: + +```{.bash data-prompt="$"} +$ pgpool -f /pgpool.conf +``` + +## pg_stat_monitor + +Please refer to [`pg_stat_monitor`](pg-stat-monitor.md#setup) for setup steps. -**wal2json** +## wal2json After the installation, enable the following option in `postgresql.conf` configuration file before starting the service: diff --git a/docs/tarball.md b/docs/tarball.md new file mode 100644 index 000000000..41321ae69 --- /dev/null +++ b/docs/tarball.md @@ -0,0 +1,171 @@ +# Install Percona Distribiution for PostgreSQL from binary tarballs + +You can find the binary tarballs on the [Percona website](https://www.percona.com/downloads). Select the desired version from a version dropdown and _All_ from the Select Platform dropdown. + +There are the following tarballs available: + +* percona-postgresql-{{dockertag}}-ssl1.1-linux-x86_64.tar.gz - for operating systems that run OpenSSL version 1.x +* percona-postgresql-{{dockertag}}-ssl3-linux-x86_64.tar.gz - for for operating systems that run OpenSSL version 3.x + +To check what OpenSSL version you have, run the following command: + +```{.bash data-prompt="$"} +$ openssl version +``` + +## Tarball contents + +The tarballs include the following components: + +| Component | Description | +|-----------|-------------| +| percona-postgresql{{pgversion}}| The latest version of PostgreSQL server and the following extensions:
- `pgaudit`
- `pgAudit_set_user`
- `pg_repack`
- `pg_stat_monitor`
- `pg_gather`
- `wal2json`
- the set of [contrib extensions](contrib.md)| +| percona-haproxy | A high-availability solution and load-balancing solution | +| percona-patroni | A high-availability solution for PostgreSQL | +| percona-pgbackrest| A backup and restore tool | +| percona-pgbadger| PostgreSQL log analyzer with fully detailed reports and graphs | +| percona-pgbouncer| Lightweight connection pooler for PostgreSQL | +| percona-pgpool-II| A middleware between PostgreSQL server and client for high availability, connection pooling and load balancing | +| percona-perl | A Perl module required to create the `plperl` extension - a procedural language handler for PostgreSQL that allows writing functions in the Perl programming language| +| percona-python3 | A Python3 module required to create `plpython` extension - a procedural language handler for PostgreSQL that allows writing functions in the Python programming language. Python is also required by Patroni +| percona-tcl | Tcl development libraries required to create the `pltcl` extension - a loadable procedural language for the PostgreSQL database system that enables the creation of functions and trigger procedures in the Tcl language | +| percona-etcd | A key-value distributed store that stores the state of the PostgreSQL cluster| + + +## Preconditions + +=== "Debian and Ubuntu" + + 1. Uninstall the upstream PostgreSQL package. + 2. Create the user to own the PostgreSQL process. For example, `mypguser`. Run the following command: + + ```{.bash data-prompt="$"} + $ sudo useradd -m mypguser + ``` + + Set the password for the user: + + ```{.bash data-prompt="$"} + $ sudo passwd mypguser + ``` + +=== "RHEL and derivatives" + + Create the user to own the PostgreSQL process. For example, `mypguser`, Run the following command: + + ```{.bash data-prompt="$"} + $ sudo useradd mypguser -m + ``` + + Set the password for the user: + + ```{.bash data-prompt="$"} + $ sudo passwd mypguser + ``` + +## Procedure + +The steps below install the tarballs for OpenSSL 3.x. Use another tarball if your operating system has OpenSSL version 1.x. + +1. Create the directory where you will store the binaries. For example, `/opt/pgdistro` + +2. Grant access to this directory for the `mypguser` user. + + ```{.bash data-prompt="$"} + $ sudo chown mypguser:mypguser /opt/pgdistro/ + ``` + +3. Fetch the binary tarball: + + ```{.bash data-prompt="$"} + $ wget https://downloads.percona.com/downloads/postgresql-distribution-{{pgversion}}/{{dockertag}}/binary/tarball/percona-postgresql-{{dockertag}}-ssl3-linux-x86_64.tar.gz + ``` + +4. Extract the tarball to the directory for binaries that you created on step 1. + + ```{.bash data-prompt="$"} + $ sudo tar -xfv percona-postgresql-{{dockertag}}-ssl3-linux-x86_64.tar.gz -C /opt/pgdistro/ + ``` + +5. If you extracted the tarball in a directory other than `/opt`, copy `percona-python3`, `percona-tcl` and `percona-perl` to the `/opt` directory. This is required for the correct run of libraries that require those modules. + + ```{.bash data-prompt="$"} + $ sudo cp /percona-perl /percona-python3 /percona-tcl /opt/ + ``` + +6. Add the location of the binaries to the PATH variable: + + ```{.bash data-prompt="$"} + $ export PATH=:/opt/pgdistro/percona-haproxy/sbin/:/opt/pgdistro/percona-patroni/bin/:/opt/pgdistro/percona-pgbackrest/bin/:/opt/pgdistro/percona-pgbadger/:/opt/pgdistro/percona-pgbouncer/bin/:/opt/pgdistro/percona-pgpool-II/bin/:/opt/pgdistro/percona-postgresql{{pgversion}}/bin/:/opt/pgdistro/percona-etcd/bin/:/opt/percona-perl/bin/:/opt/percona-tcl/bin/:/opt/percona-python3/bin/:$PATH + ``` + +6. Create the data directory for PostgreSQL server. For example, `/usr/local/pgsql/data`. +7. Grant access to this directory for the `mypguser` user. + + ```{.bash data-prompt="$"} + $ sudo chown mypguser:mypguser /usr/local/pgsql/data + ``` + +8. Switch to the user that owns the Postgres process. In our example, `mypguser`: + + ```{.bash data-prompt="$"} + $ su - mypguser + ``` + +9. Initiate the PostgreSQL data directory: + + ```{.bash data-prompt="$"} + $ /opt/pgdistro/percona-postgresql{{pgversion}}/bin/initdb -D /usr/local/pgsql/data + ``` + + ??? example "Sample output" + + ```{.text .no-copy} + Success. You can now start the database server using: + + /opt/pgdistro/percona-postgresql{{pgversion}}/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start + ``` + +10. Start the PostgreSQL server: + + ```{.bash data-prompt="$"} + $ /opt/pgdistro/percona-postgresql{{pgversion}}/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start + ``` + + ??? example "Sample output" + + ```{.text .no-copy} + waiting for server to start.... done + server started + ``` + +11. To use the `createuser` binary to create a database user, set the `LD_LIBRARY_PATH` environment variable to the server's library path. + + ```{.bash data-prompt="$"} + export LD_LIBRARY_PATH=/opt/pgdistro/percona-postgresql{{pgversion}}/lib:$LD_LIBRARY_PATH + ``` + +12. Connect to `psql` + + ```{.bash data-prompt="$"} + $ /opt/pgdistro/percona-postgresql{{pgversion}}/bin/psql + ``` + + ??? example "Sample output" + + ```{.text .no-copy} + psql ({{dockertag}}) + Type "help" for help. + + postgres=# + ``` + +### Start the components + +After you unpacked the tarball and added the location of the components' binaries to the $PATH variable, the components are available for use. You can invoke a component by running its command-line tool. For example, to check HAProxy version, type: + +```{.bash data-prompt="$"} +$ haproxy version +``` + +Some components require additional setup. Check the [Enabling extensions](enable-extensions.md) page for details. \ No newline at end of file diff --git a/docs/uninstalling.md b/docs/uninstalling.md index b4f6c4e60..d707aaf16 100644 --- a/docs/uninstalling.md +++ b/docs/uninstalling.md @@ -55,3 +55,26 @@ To uninstall Percona Distribution for PostgreSQL, remove all the installed packa ```{.bash data-prompt="$"} $ rm -rf /var/lib/pgsql/12/data ``` + +## Uninstall from tarballs + +If you [installed Percona Distribution for PostgreSQL from binary tarballs](tarball.md), stop the PostgreSQL server and remove the folder with the binary tarballs. + +1. Stop the `postgres` server: + + ```{.bash data-prompt="$"} + $ /path/to/tarballs/percona-postgresql{{pgversion}}/bin/pg_ctl -D path/to/datadir -l logfile stop + ``` + + ??? example "Sample output" + + ```{.text .no-copy} + waiting for server to shut down.... done + server stopped + ``` + +2. Remove the directory with extracted tarballs + + ```{.bash data-prompt="$"} + $ sudo rm -rf /path/to/tarballs/ + ``` \ No newline at end of file diff --git a/mkdocs-base.yml b/mkdocs-base.yml index af3a1664d..3a0462fef 100644 --- a/mkdocs-base.yml +++ b/mkdocs-base.yml @@ -163,6 +163,7 @@ nav: - 1. Install: - Via apt: apt.md - Via yum: yum.md + - From tarballs: tarball.md - Run in Docker: docker.md - enable-extensions.md - repo-overview.md