pgagroal: 开始上手

一月 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以退出 psqlpgagroal现在会将您使用的连接放入连接池中。

如果再次键入上述的psql命令,pgagroal将重用现有的连接,从而降低与 PostgreSQL 建立连接的开销。

现在,您已准备好将应用程序指向使用pgagroal,而不是直接连到 PostgreSQL。pgagroal可以与任何适用于 PostgreSQL 的驱动程序一起使用,例如 pgjdbcNpgsqlpq

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_usersfalse,禁止未知用户的访问
  • 定义一个pgagroal_databases.conf文件,其中包含每个数据库的限制和预填充设置
  • 启用传输层安全性 v1.2+(TLS)
  • 部署 Grafana 仪表板

有关这些主题的更多信息,请参阅配置。