一月 20, 2024
摘要：pgagroal是一个 PostgreSQL 的高性能连接池。
目录
用法
首先，确保pgagroal已安装到您的路径中，你可以使用pgagroal -?来进行检查。
用法：pgagroal [ -c CONFIG_FILE ] [ -a HBA_FILE ] [ -d ]
选项：
-
-c, --config CONFIG_FILE
设置 pgagroal.conf 文件的路径
-
-a, --hba HBA_FILE
设置 pgagroal_hba.conf 文件的路径
-
-l, --limit LIMIT_FILE
设置 pgagroal_databases.conf 文件的路径
-
-u, --users USERS_FILE
设置 pgagroal_users.conf 文件的路径
-
-F, --frontend FRONTEND_USERS_FILE
设置 pgagroal_frontend_users.conf 文件的路径
-
-A, --admins ADMINS_FILE
设置 pgagroal_admins.conf 文件的路径
-
-S, --superuser SUPERUSER_FILE
设置 pgagroal_superuser.conf 文件的路径
-
-d, --daemon
作为后台守护进程运行
-
-V, --version
显示版本信息
-
-?, --help
显示帮助
配置
让我们创建一个简单的名为pgagroal.conf的配置文件，包含以下内容
[pgagroal]
host = *
port = 2345
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
在名为[pgagroal]的主要部分中，我们设置pgagroal在所有网络地址的端口 2345 上进行监听。日志将使用info级别进行记录，并放在名为/tmp/pgagroal.log的一个文件中。我们希望最多有 100 个连接，这些连接在空闲 10 分钟后会被关闭，并且我们还指定不希望执行任何连接验证。最后，我们指定了用于管理操作的unix_socket_dir的位置。
接下来，我们创建一个名为[primary]的部分，其中包含有关 PostgreSQL 实例的信息。在本例中，它在localhost的端口5432上运行。
现在我们需要一个基于主机的身份验证（HBA）文件。创建一个名为pgagroal_hba.conf的 HBA 文件，包含以下内容
#
# TYPE DATABASE USER ADDRESS METHOD
#
host all all all all
这指示了pgagroal，它可以接受来自所有网络地址的，对于所有数据库和所有用户名的连接。
我们现在已经准备好运行pgagroal了。
有关所有配置选项，请参阅配置。
运行
我们将使用以下命令运行pgagroal
pgagroal -c pgagroal.conf -a pgagroal_hba.conf
如果这没有出现错误，那么我们就可以连接了。
我们假设在 PostgreSQL 实例中，有一个带有密码test的名为test的用户。有关如何设置 PostgreSQL、添加用户和添加数据库，请参阅文档。
我们将使用 psql 应用程序连接到pgagroal。
psql -h localhost -p 2345 -U test test
这应该会给你一个输入密码的提示，此处你应该输入test。您现在已通过pgagroal连接到了 PostgreSQL。
键入\q以退出 psql，pgagroal现在会将您使用的连接放入连接池中。
如果再次键入上述的psql命令，pgagroal将重用现有的连接，从而降低与 PostgreSQL 建立连接的开销。
现在，您已准备好将应用程序指向使用pgagroal，而不是直接连到 PostgreSQL。pgagroal可以与任何适用于 PostgreSQL 的驱动程序一起使用，例如 pgjdbc、Npgsql 和 pq。
pgagroal可以通过在启动它的控制台中按 Ctrl-C（^C），或者使用kill <pid>向进程发送SIGTERM信号来停止。
运行时管理
pgagroal有一个名为pgagroal-cli的运行时管理工具。
您可以使用pgagroal-cli -?来查看它支持的命令。
pgagroal-cli - pgagroal 的命令行工具
用法：pgagroal-cli [ -c CONFIG_FILE ] [ COMMAND ]
选项：
-
-c, --config CONFIG_FILE
设置 pgagroal.conf 文件的路径
-
-h, --host HOST
设置主机名
-
-p, --port PORT
设置端口号
-
-U, --user USERNAME
设置用户名
-
-P, --password PASSWORD
设置密码
-
-L, --logfile FILE
设置日志文件
-
-v, --verbose
输出结果的文本字符串
-
-V, --version
显示版本信息
-
-?, --help
显示帮助
命令：
-
flush-idle
刷新空闲连接
-
flush-gracefully
优雅地刷新所有连接
-
flush-all
刷新所有连接。请谨慎使用！
-
is-alive
检测 pgagroal 是否在正常运行
-
enable
启用数据库
-
disable
禁用数据库
-
gracefully
优雅地停止 pgagroal
-
stop
停止 pgagroal
-
cancel-shutdown
取消正常的关闭动作
-
status
pgagroal 的状态
-
details
pgagroal 的详细状态
-
switch-to
切换到另一个主节点
-
reload
重新加载配置
-
reset
重置 Prometheus 统计信息
-
reset-server
重置服务器的状态
此工具可用在运行pgagroal的机器上，刷新连接。
要刷新所有空闲连接，你可以使用
pgagroal-cli -c pgagroal.conf flush-idle
要停止 pgagroal，你可以使用
pgagroal-cli -c pgagroal.conf stop
可通过验证退出码，来检查操作的结果，例如
echo $?
或者使用-v标志。
如果 pgagroal 同时启用了传输层安全性（TLS）和management，则pgagroal-cli可以使用文件~/.pgagroal/pgagroal.key（必须具有 0600 权限）、~/.pgagroal/pgagroal.crt和~/.pgagroal/root.crt，建立 TLS 连接。
管理
pgagroal有一个名为pgagroal-admin的管理工具，可用于控制pgagroal的用户注册。
您可以使用pgagroal-admin -?，来查看它支持的命令。
pgagroal-admin - pgagroal 的管理工具
用法：pgagroal-admin [ -f FILE ] [ COMMAND ]
选项：
-
-f, --file FILE
设置用户文件的路径
-
-U, --user USER
设置用户名
-
-P, --password PASSWORD
为用户设置密码
-
-g, --generate
生成一个密码
-
-l, --length
密码长度
-
-V, --version
显示版本信息
-
-?, --help
显示帮助
命令：
-
master-key
创建或更新主密钥
-
add-user
添加一个用户
-
update-user
更新一个用户
-
remove-user
删除一个用户
-
list-users
列出所有用户
为了给所有用户设置主密钥，您可以使用
pgagroal-admin -g master-key
主密钥必须至少有 8 个字符。
然后使用其他命令添加、更新、删除或列出当前用户名，例如
pgagroal-admin -f pgagroal_users.conf add-user
后续步骤
要改进 pgagroal 配置，可能的后续步骤有
- 使用系统所需的设置，更新
pgagroal.conf - 在
pgagroal_hba.conf中为每个用户和数据库设置访问权限 - 使用
pgagroal-admin添加一个pgagroal_users.conf文件，其中包含已知的用户列表 - 通过设置
allow_unknown_users为false，禁止未知用户的访问 - 定义一个
pgagroal_databases.conf文件，其中包含每个数据库的限制和预填充设置 - 启用传输层安全性 v1.2+（TLS）
- 部署 Grafana 仪表板
有关这些主题的更多信息，请参阅配置。