[#472] Advanced connection management with pgagroal

doc/CMakeLists.txt

@@ -90,6 +90,7 @@ if(generation)
   FILE(GLOB UMDS_PRE "manual/user-0?-*.md")
   FILE(GLOB UMDS_POST "manual/user-1?-*.md")
   FILE(GLOB DMDS "manual/dev-??-*.md")
+  FILE(GLOB AG "manual/advanced/??-*.md")
 
   # Manuals definitions
   set(MANUAL_OUTPUT_DIR "${CMAKE_BINARY_DIR}/doc")
@@ -128,15 +129,30 @@ if(generation)
     COMMENT "Generating Developer Guide HTML documentation"
   )
 
+  add_custom_command(
+    OUTPUT ${MANUAL_OUTPUT_DIR}/pgagroal-advanced.pdf
+    COMMAND ${PANDOC_EXECUTABLE} -o ${MANUAL_OUTPUT_DIR}/pgagroal-advanced.pdf --from markdown --template eisvogel --listings -N --toc ${AG}
+    DEPENDS ${UMDS}
+    COMMENT "Generating Advanced PDF documentation"
+  )
+  add_custom_command(
+    OUTPUT ${MANUAL_OUTPUT_DIR}/pgagroal-advanced.html
+    COMMAND ${PANDOC_EXECUTABLE} -o ${MANUAL_OUTPUT_DIR}/pgagroal-advanced.html -s -f markdown-smart -N --toc -t html5 ${AG}
+    DEPENDS ${DMDS}
+    COMMENT "Generating Advanced HTML documentation"
+  )
+
   add_custom_target(
     all_docs ALL
-    DEPENDS copy_images ${MANUAL_OUTPUT_DIR}/pgagroal-user-guide.pdf ${MANUAL_OUTPUT_DIR}/pgagroal-user-guide.html ${MANUAL_OUTPUT_DIR}/pgagroal-dev-guide.pdf ${MANUAL_OUTPUT_DIR}/pgagroal-dev-guide.html
+    DEPENDS copy_images ${MANUAL_OUTPUT_DIR}/pgagroal-user-guide.pdf ${MANUAL_OUTPUT_DIR}/pgagroal-user-guide.html ${MANUAL_OUTPUT_DIR}/pgagroal-dev-guide.pdf ${MANUAL_OUTPUT_DIR}/pgagroal-dev-guide.html ${MANUAL_OUTPUT_DIR}/pgagroal-advanced.pdf ${MANUAL_OUTPUT_DIR}/pgagroal-advanced.html
   )
 
   install(FILES ${MANUAL_OUTPUT_DIR}/pgagroal-user-guide.pdf DESTINATION share/doc/pgagroal/manual)
   install(FILES ${MANUAL_OUTPUT_DIR}/pgagroal-user-guide.html DESTINATION share/doc/pgagroal/manual)
   install(FILES ${MANUAL_OUTPUT_DIR}/pgagroal-dev-guide.pdf DESTINATION share/doc/pgagroal/manual)
   install(FILES ${MANUAL_OUTPUT_DIR}/pgagroal-dev-guide.html DESTINATION share/doc/pgagroal/manual)
+  install(FILES ${MANUAL_OUTPUT_DIR}/pgagroal-advanced.pdf DESTINATION share/doc/pgagroal/manual)
+  install(FILES ${MANUAL_OUTPUT_DIR}/pgagroal-advanced-guide.html DESTINATION share/doc/pgagroal/manual)
 
 endif()
 

doc/manual/97-acknowledgement.md

@@ -45,5 +45,5 @@ Please, consult our [Code of Conduct][conduct] policies for interacting in our
 community.
 
 Consider giving the project a [star][star] on
-[GitHub][pagmoneta] if you find it useful. And, feel free to follow
-the project on [Twitter][twitter] as well.
+[GitHub][pgagroal] if you find it useful. And, feel free to follow
+the project on [Twitter][twitter] as well.

doc/manual/advanced/00-frontpage.md

@@ -0,0 +1,13 @@
+---
+title: "Advanced connection management with pgagroal"
+keywords: [pgagroal, PostgreSQL]
+lang: "en"
+titlepage: true,
+titlepage-color: "0064A5"
+titlepage-text-color: "FFFFFF"
+titlepage-rule-color: "360049"
+titlepage-rule-height: 0
+toc-own-page: true
+listings-disable-line-numbers: true
+table-use-row-colors: true
+...

doc/manual/advanced/01-preface.md

@@ -0,0 +1,12 @@
+# Preface
+
+Acme Boot is a startup company that have decided to use [**PostgreSQL**][postgresql] as
+its database technology.
+
+The following technologies will be used for the database cluster
+
+* [**Rocky Linux**][rocky] **9.x**
+* [**PostgreSQL**][postgresql] **17.x**
+* [**pgagroal**][pgagroal]
+
+Note, that this guide will focus on the [**pgagroal**][pgagroal] aspect of the platform.

doc/manual/advanced/02-introduction.md

@@ -0,0 +1,34 @@
+\newpage
+
+# Introduction
+
+[**pgagroal**][pgagroal] is a high-performance protocol-native connection pool for [PostgreSQL][postgresql].
+
+## Features
+
+* High performance
+* Connection pool
+* Limit connections for users and databases
+* Prefill support
+* Remove idle connections
+* Perform connection validation
+* Enable / disable database access
+* Graceful / fast shutdown
+* Prometheus support
+* Grafana 8 dashboard
+* Remote management
+* Authentication query support
+* Failover support
+* Transport Layer Security (TLS) v1.2+ support
+* Daemon mode
+* User vault
+
+## Platforms
+
+The supported platforms are
+
+* [Fedora][fedora] 32+
+* [RHEL][rhel] 8 / RockyLinux 8
+* [RHEL][rhel] 9 / RockyLinux 9
+* [FreeBSD][freebsd]
+* [OpenBSD][openbsd]

doc/manual/advanced/03-installation.md

@@ -0,0 +1,172 @@
+\newpage
+
+# Installation
+
+## Rocky Linux 9.x
+
+We can download the [Rocky Linux](https://www.rockylinux.org/) distruction from their web site
+
+```
+https://rockylinux.org/download
+```
+
+The installation and setup is beyond the scope of this guide.
+
+Ideally, you would use dedicated user accounts to run [**PostgreSQL**][postgresql] and [**pgagroal**][pgagroal]
+
+```
+useradd postgres
+usermod -a -G wheel postgres
+useradd pgagroal
+usermod -a -G wheel pgagroal
+```
+
+Add a configuration directory for [**pgagroal**][pgagroal]
+
+```
+mkdir /etc/pgagroal
+chown -R pgagroal:pgagroal /etc/pgagroal
+```
+
+and lets open the ports in the firewall that we will need
+
+```
+firewall-cmd --permanent --zone=public --add-port=2345/tcp
+firewall-cmd --permanent --zone=public --add-port=2346/tcp
+```
+
+## PostgreSQL 17
+
+We will install PostgreSQL 17 from the official [YUM repository][yum] with the community binaries,
+
+**x86_64**
+
+```
+dnf -qy module disable postgresql
+dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm
+```
+
+**aarch64**
+
+```
+dnf -qy module disable postgresql
+dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-aarch64/pgdg-redhat-repo-latest.noarch.rpm
+```
+
+and do the install via
+
+```
+dnf install -y postgresql17 postgresql17-server postgresql17-contrib
+```
+
+First, we will update `~/.bashrc` with
+
+```
+cat >> ~/.bashrc
+export PGHOST=/tmp
+export PATH=/usr/pgsql-17/bin/:$PATH
+```
+
+then Ctrl-d to save, and
+
+```
+source ~/.bashrc
+```
+
+to reload the Bash environment.
+
+Then we can do the PostgreSQL initialization
+
+```
+mkdir DB
+initdb -k DB
+```
+
+and update configuration - for a 8 GB memory machine.
+
+**postgresql.conf**
+```
+listen_addresses = '*'
+port = 5432
+max_connections = 100
+unix_socket_directories = '/tmp'
+password_encryption = scram-sha-256
+shared_buffers = 2GB
+huge_pages = try
+max_prepared_transactions = 100
+work_mem = 16MB
+dynamic_shared_memory_type = posix
+wal_level = replica
+wal_log_hints = on
+max_wal_size = 16GB
+min_wal_size = 2GB
+log_destination = 'stderr'
+logging_collector = on
+log_directory = 'log'
+log_filename = 'postgresql.log'
+log_rotation_age = 0
+log_rotation_size = 0
+log_truncate_on_rotation = on
+log_line_prefix = '%p [%m] [%x] '
+log_timezone = UTC
+datestyle = 'iso, mdy'
+timezone = UTC
+lc_messages = 'en_US.UTF-8'
+lc_monetary = 'en_US.UTF-8'
+lc_numeric = 'en_US.UTF-8'
+lc_time = 'en_US.UTF-8'
+```
+
+Please, check with other sources in order to create a setup for your local setup.
+
+Now, we are ready to start PostgreSQL
+
+```
+pg_ctl -D DB -l /tmp/ start
+```
+
+## pgagroal
+
+We will install [**pgagroal**][pgagroal] from the official [YUM repository][yum] as well,
+
+```
+dnf install -y pgagroal
+```
+
+First, we will need to create a master security key for the [**pgagroal**][pgagroal] installation, by
+
+```
+pgagroal-admin -g master-key
+```
+
+Then we will create the configuration for [**pgagroal**][pgagroal],
+
+```
+cat > /etc/pgagroal/pgagroal.conf
+[pgagroal]
+host = *
+port = 2345
+
+metrics = 2346
+
+log_type = file
+log_level = info
+log_path = /tmp/pgagroal.log
+
+max_connections = 100
+idle_timeout = 600
+validation = off
+unix_socket_dir = /tmp/
+
+[primary]
+host = localhost
+port = 5432
+```
+
+and end with a Ctrl-d to save the file.
+
+Start [**pgagroal**][pgagroal] now, by
+
+```
+pgagroal -d
+```