连接

listen_addresses

指定 pgpool-II 将接受 TCP/IP 连接的主机名或者 IP 地址。'*' 将接受所有的连接。'' 将禁用 TCP/IP 连接。默认为 'localhost'。总是支持接受通过 UNIX 域套接字发起的连接。需要重启 pgpool-II 以使改动生效。

port

pgpool-II 监听 TCP/IP 连接的端口号。默认为 9999。需要重启 pgpool-II 以使改动生效。

socket_dir

pgpool-II 建立用于建立接受 UNIX 域套接字连接的目录。默认为 '/tmp'。注意，这个套接字可能被 cron 任务删除。我们建议设置这个值为 '/var/run' 或类似目录。需要重启 pgpool-II 以使改动生效。

pcp_port

PCP 进程接受连接的端口号。默认为 9898。本参数必须在服务器启动前设置。

pcp_socket_dir

PCP 进程用于建立接受 UNIX 域套接字连接的目录。默认为 '/tmp'。注意，这个套接字可能被 cron 任务删除。我们建议设置这个值为 '/var/run' 或类似目录。需要重启 pgpool-II 以使改动生效。

backend_socket_dir- V3.0

不推荐使用 : 为了保持和 libpq 策略的一致性，反对使用本参数。参考 backend_hostname 参数来定义你对应的配置。

本参数定义了 PostgreSQL 服务器的 UNIX 域套接字目录。默认为 '/tmp'.

本参数必须在服务器启动前设置。

pcp_timeout

PCP 连接超时值，单位为秒。如果客户端在设置的秒数内没有响应，PCP 关闭到这个客户端的连接。默认为 10 秒。0 表示没有超时。如果你改变了这个值，需要重新加载 pgpool.conf 以使变动生效。

池

num_init_children

预先生成的 pgpool-II 服务进程数。默认为 32。num_init_children 也是 pgpool-II 支持的从客户端发起的最大并发连接数。如果超过 num_init_children 数的客户端尝试连接到 pgpool-II，它们将被阻塞（而不是拒绝连接），直到到任何一个 pgpool-II 进程的连接被关闭为止。最多有 2*num_init_children 可以被放入等待队列。

对于以上内容的一些提示：

取消一个执行中的查询将导致建立另一个到后端的连接；因此，如果所有的连接都在使用，则查询无法被取消。如果你想确保查询可以被取消，设置本值为预期最大连接数的两倍。
PostgreSQL 允许最多 max_connections - superuser_reserved_connections 个非超级用户的并发连接。

归纳起来，max_pool，num_init_children，max_connections 和 superuser_reserved_connections 必须符合以下规则：

max_pool*num_init_children <= (max_connections - superuser_reserved_connections)（不需要取消查询）max_pool*num_init_children*2 <= (max_connections - superuser_reserved_connections)（需要取消查询）

本参数必须在服务器启动前设置。

child_life_time

pgpool-II 子进程的生命周期，单位为秒。如果子进程空闲了这么多秒，它将被终止，一个新的子进程将被创建。这个参数是用于应对内存泄露和其他不可预料错误的一个措施。默认值为 300（5 分钟）。0 将禁用本功能。注意它不影响尚未接受任何连接的进程。如果改变了这个值，你需要重新加载 pgpool.conf 以使变动生效。

child_max_connections

当 pgpool-II 子进程处理这么多个客户端连接后，它将被终止。这个参数在繁忙到 child_life_time 和 connection_life_time 永远不会触发的服务器上有效。如果你改变了这个值，需要重新加载 pgpool.conf 以使变动生效。

client_idle_limit

当一个客户端在执行最后一条查询后如果空闲到了 client_idle_limit 秒数，到这个客户端的连接将被断开。这在避免 pgpool 子进程被懒客户端占用或者探测断开的客户端和 pgpool 之间的 TCP/IP 连接非常有用。如果你改变了这个值，需要重新加载 pgpool.conf 以使变动生效。

enable_pool_hba

如果为 true，则使用 pgpool_hba.conf 来进行客户端认证。参考设置用于客户端认证的 pool_hba.conf。

如果你改变了这个值，需要重新加载 pgpool.conf 以使变动生效。

authentication_timeout

指定 pgpool 认证超时的时长。0 指禁用超时，默认值为 60。如果你改变了这个值，需要重新加载 pgpool.conf 以使变动生效。

日志

log_destination

pgpool-II 支持多种记录服务器消息的方式，包括 stderr 和 syslog。默认为记录到 stderr。

注：要使用 syslog 作为 log_destination 的选项，你将需要更改你系统的 syslog 守护进程的配置。pgpool-II 可以记录到 syslog 设备 LOCAL0 到 LOCAL7（参考 syslog_facility），但是大部分平台的默认的 syslog 配置将忽略这些消息。你需要添加如下一些内容

local0.*    /var/log/pgpool.log

到 syslog 守护进程的配置文件以使它生效。

print_timestamp

如果本值被设置为 true，则将在日志中添加时间戳。默认值为 true。如果你改变了这个值，需要重新加载 pgpool.conf 以使变动生效。

log_connections

如果为 true，进入的连接将被打印到日志中。如果你改变了这个值，需要重新加载 pgpool.conf 以使变动生效。

log_hostname

如果为 true，ps 命令将显示客户端的主机名而不是 IP 地址。而且，如果 log_connections 被开启，也会将主机名写入日志。如果你改变了这个值，需要重新加载 pgpool.conf 以使变动生效。

log_statement

当设置为 true 时生成 SQL 日志消息。这类似于 PostgreSQL 中的 log_statement 参数。即使调试选项没有在启动的时候传递到 pgpool-II，它也会产生日志。

log_per_node_statement V2.3 -

类似于 log_statement，除了它是针对每个 DB 节点产生日志外。例如它对于确定复制是否正常运行非常有用。如果你改变了这个值，需要重新加载 pgpool.conf 以使变动生效。

syslog_facility V3.1 -

当记录日志到 syslog 被启用，本参数确定被使用的 syslog“设备”。你可以使用 LOCAL0, LOCAL1, LOCAL2, LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7；默认为 LOCAL0。还请参考你系统的 syslog 守护进程的文档。

syslog_ident V3.1 -

当记录日志到 syslog 被启用，本参数确定用于标记 syslog 中 pgpool-II 消息的程序名。默认为“pgpool”。

debug_level V3.0 -

调试消息详细程度级别。0 表示没有消息。大于 1 表示更详细的消息。默认值为 0。

文件位置

logdir: 保存日志文件的目录。pgpool_status 将被写入这个目录。
pid_file_name: 到包含 pgpool-II 进程 ID 的文件的完整路径名。默认为 '/var/run/pgpool/pgpool.pid'。需要重启 pgpool-II 以使改动生效。

连接池

connection_cache: 如果本值被设置为 true，则缓存到 PostgreSQL 的连接。默认为 true。需要重启 pgpool-II 以使改动生效。

健康检查

health_check_timeout: pgpool-II 定期尝试连接到后台以检测服务器是否在服务器或网络上有问题。这种错误检测过程被称为“健康检查”。如果检测到错误，则 pgpool-II 会尝试进行故障恢复或者退化操作。本参数用于避免健康检查在例如网线断开等情况下等待很长时间。超时值的单位为秒。默认值为 20。0 禁用超时（一直等待到 TCP/IP 超时）。健康检查需要额外的到后端程序的连接，所以 postgresql.conf 中的 max_connections 需要加一。如果你改变了这个值，需要重新加载 pgpool.conf 以使变动生效。
health_check_period: 本参数指出健康检查的间隔，单位为秒。默认值为 0，代表禁用健康检查。如果你改变了这个值，需要重新加载 pgpool.conf 以使变动生效。
health_check_user: 用于执行健康检查的用户。用户必须存在于 PostgreSQL 后台中。如果你改变了这个值，需要重新加载 pgpool.conf 以使变动生效。
health_check_password V3.1 -: 用于执行健康检查的用户的密码。如果你改变了这个值，需要重新加载 pgpool.conf 以使变动生效。
health_check_max_retries V3.2 -: 在执行失效故障切换前尝试的最大失效健康检查次数。这个参数对于网络不稳定的时，健康检查失败但主节点依旧正常的情况下非常有效。默认值为 0，也就是不重试。如果你想启用 health_check_max_retries，建议你禁用 fail_over_on_backend_error。如果你改变了 health_check_max_retries，需要重新加载 pgpool.conf。
health_check_retry_delay V3.2 -: 失效健康检查重试的间隔时间（单位为秒）（health_check_max_retries > 0 时有效）。如果为 0 则立即重试（不延迟）。如果你改变了 health_check_retry_delay，需要重新加载 pgpool.conf。

故障切换和恢复

failover_command

本参数指定当一个节点断开连接时执行的命令。pgpool-II 使用后台对应的信息代替以下的特别字符。

特殊字符描述

%d 断开连接的节点的后台 ID。

%h 断开连接的节点的主机名。

%p 断开连接的节点的端口号。

%D 断开连接的节点的数据库实例所在目录。

%M 旧的主节点 ID。

%m 新的主节点 ID。

%H 新的主节点主机名。

%P 旧的第一节点 ID。

%% '%' 字符

如果你改变了这个值，需要重新加载 pgpool.conf 以使变动生效。

当进行故障切换时，pgpool 杀掉它的所有子进程，这将顺序终止所有的到 pgpool 的会话。然后，pgpool 调用 failover_command 并等待它完成。然后，pgpool 启动新的子进程并再次开始从客户端接受连接。

failback_command

本参数指定当一个节点连接时执行的命令。pgpool-II 使用后台对应的信息代替以下的特别字符。

特殊字符描述

%d 新连接上的节点的后台 ID。

%h 新连接上的节点的主机名。

%p 新连接上的节点的端口号。

%D 新连接上的节点的数据库实例所在目录。

%M 旧的主节点 ID。

%m 新的主节点 ID。

%H 新的主节点主机名。

%P 旧的第一节点 ID。

%% '%' 字符

如果你改变了这个值，需要重新加载 pgpool.conf 以使变动生效。

follow_master_command V3.1 -

本参数指定一个在主备流复制模式中发生主节点故障恢复后执行的命令。pgpool-II 使用后台对应的信息代替以下的特别字符。

特殊字符描述

%d 断开连接的节点的后台 ID。

%h 断开连接的节点的主机名。

%p 断开连接的节点的端口号。

%D 断开连接的节点的数据库实例所在目录。

%M 旧的主节点 ID。

%m 新的主节点 ID。

%H 新的主节点主机名。

%P 旧的第一节点 ID。

%% '%' 字符

如果你改变了这个值，需要重新加载 pgpool.conf 以使变动生效。

如果 follow_master_commnd 不为空，当一个主备流复制中的主节点的故障切换完成，pgpool 退化所有的除新的主节点外的所有节点并启动一个新的子进程，再次准备好接受客户端的连接。在这之后，pgpool 针对每个退化的节点运行‘follow_master_command’指定的命令。通常，这个命令应该用于调用例如 pcp_recovery_node 命令来从新的主节点恢复备节点。

fail_over_on_backend_error V2.3 -

如果为 true，当往后台进程的通信中写入数据时发生错误，pgpool-II 将触发故障处理过程。这和 pgpool-II 2.2.x 甚至以前版本的行为一样。如果设置为 false，则 pgpool 将报告错误并断开该连接。请注意如果设置为 true，当连接到一个后台进程失败或者 pgpool 探测到 postmaster 由于管理原因关闭，pgpool 也会执行故障恢复过程。如果你改变了这个值，需要重新加载 pgpool.conf 以使变动生效。

负载均衡模式

ignore_leading_white_space: 在负载均衡模式中 pgpool-II 忽略 SQL 查询语句前面的空白字符。如果使用类似于 DBI/DBD:Pg 一类的在用户的查询前增加空白的 API 中非常有用。如果你改变了这个值，需要重新加载 pgpool.conf 以使变动生效。

后端（PostgreSQL 服务器）

backend_hostname

指出连接到 PostgreSQL 后台程序的地址。它用于 pgpool-II 与服务器通信。如果你改变了这个值，需要重新加载 pgpool.conf 以使变动生效。

对于 TCP/IP 通信，本参数可以是一个主机名或者 IP 地址。如果它是从斜线开始的，它指出是通过 UNIX 域套接字通信，而不是 TCP/IP 协议；它的值为存储套接字文件所在的目录。如果 backend_host 为空，则它的默认行为是通过 /tmp 中的 UNIX 域套接字连接。

可以通过在本参数名的末尾添加一个数字来指定多个后台程序（例如backend_hostname0）。这个数字对应为“数据库节点 ID”，是从 0 开始的正整数。被设置数据库节点 ID 为 0 的后台程序后台程序将被叫做“主数据库”。当定义了多个后台程序时，即使主数据库当机后依然能继续（某些模式下不行）。在这种情况下，存活的最小的数据库节点编号的数据库将被变成新的主数据库。

请注意有编号为 0 的节点在流复制中没有其他意义。但是，你需要注意数据库节点是不是“主节点”。请参考流复制获得更多细节。

如果你只计划使用一台 PostgreSQL 服务器，可以通过 backend_hostname0 指定。

可以通过配置本参数后重新加载配置文件添加新的节点。但是，对已有的值无法更新，所以这种情况下你必须重启 pgpool-II。

backend_port

指定后台程序的端口号。可以通过在本参数名的末尾添加一个数字来指定多个后台程序（例如backend_port0）。如果你只计划使用一台 PostgreSQL 服务器，可以通过 backend_port0 指定。

可以通过配置本参数后重新加载配置文件添加新的后台端口。但是，对已有的值无法更新，所以这种情况下你必须重启 pgpool-II。

backend_weight

指定后台程序的负载均衡权重。可以通过在本参数名的末尾添加一个数字来指定多个后台程序（例如backend_weight0）。如果你只计划使用一台 PostgreSQL 服务器，可以通过 backend_weight0 指定。

在原始模式中，请将本值设置为 1。

可以通过配置本参数后重新加载配置文件添加新的负载均衡权重。但是，对已有的值无法更新，所以这种情况下你必须重启 pgpool-II。

在 pgpool-II 2.2.6/2.3 或者更新的版本中，你可以通过重新加载配置文件来改变本值。但这只对新连接的客户会话生效。这在主备模式中可以避免任何执行一些管理工作的查询被发送到备用节点上。

backend_data_directory

指定后台的数据库实例的目录。可以通过在本参数名的末尾添加一个数字来指定多个后台程序（例如backend_data_directory0）。如果你不打算使用在线恢复，你可以不设置本参数。

可以通过配置本参数后重新加载配置文件添加新的后台的数据库实例目录。但是，对已有的值无法更新，所以这种情况下你必须重启 pgpool-II。

backend_flag V3.1 -

控制大量的后台程序的行为。可以通过在本参数名的末尾添加一个数字来指定多个后台程序（例如backend_flag0）

当前支持以下的内容。多个标志可以通过“|”来分隔。

ALLOW_TO_FAILOVER	允许故障切换或者从后台程序断开。本值为默认值。指定本值后，不能同时指定 DISALLOW_TO_FAILOVER。
DISALLOW_TO_FAILOVER	不允许故障切换或者从后台程序断开。本值在你使用 HA（高可用性）软件例如 Heartbeat 或者 Packmaker 来保护后台程序时非常有用。本值为默认值。指定本值后，不能同时指定 DISALLOW_TO_FAILOVER。

SSL

ssl V2.3 -

如果设置为 ture，则启用了到前端程序和后端程序的连接的 ssl 支持。注意为了能与前端程序进行 SSL 连接，必须设置 ssl_key 和 ssl_cert。

SSL 默认被关闭。就像在 pgpool-II 的安装小节所说的，注意必须在编译时配置 OpenSSL 支持才能打开 SSL 支持。

如果修改了 SSL 相关的设置，pgpool-II 守护进程必须重启。

ssl_key V2.3 -

对于进入的连接使用的私钥文件所在路径。

本选项没有默认值，如果本值不设置，则对于进入的连接将禁用 SSL。

ssl_cert V2.3 -

对于进入的连接使用的公共 x509 证书文件所在的路径。

本选项没有默认值，如果本值不设置，则对于进入的连接将禁用 SSL。

其他

relcache_expire V3.1 -

关系缓存的生命周期。0（默认值）表示没有缓冲区过期。关系缓存用于缓存用来获取包含表结构信息或一个表是不是一个临时表等大量信息的相关的 PostgreSQL 系统 catalog 的查询结果。缓存位于 pgpool 子进程的本地，并被保存到它的生命结束。如果某些人使用了 ALTER TABLE 修改了表结构或其他类似内容，关系缓存不再一致。为了这个目的，relcache_expire 控制缓存的生命周期。

relcache_size V3.2 -

relcache 的条目数。默认为 256。如果你频繁看到以下信息，请增加此数量。

"pool_search_relcache: cache replacement happened"

check_temp_table V3.2 -

如果为 on，在 SELECT 语句中启用临时表检查。这会在启动查询前查询主节点上的系统对象，因此增加了主节点上的负载。如果你确定你的系统不会使用临时表，并且你想降低对主节点的访问，弄可以将它设置为 off。默认为 on。

生成 SSL 证书

证书处理不在本文档讨论范围。postgresql.org 的 Secure TCP/IP Connections with SSL 页面指出了一些用来生成自签名证书的示例命令。

在原始模式中的故障切换

如果定义了多个服务器，可以在原始模式中进行故障切换。pgpool-II 在普通操作中通常访问 backend_hostname0 指定的后台程序。如果 backend_hostname0 因为某些原因不能正常工作，pgpool-II 尝试访问 backend_hostname1 指定的后台程序。如果它也不能正常工作，pgpool-II 尝试访问 backend_hostname2，3 等等。

连接池模式

在连接池模式中，所有在原始模式中的功能以及连接池功能都可以使用。要启用本模式，设置原始模式的配置参数以及以下的参数。

max_pool

在 pgpool-II 子进程中缓存的最大连接数。当有新的连接使用相同的用户名连接到相同的数据库，pgpool-II 将重用缓存的连接。如果不是，则 pgpool-II 建立一个新的连接到 PostgreSQL。如果缓存的连接数达到了 max_pool，则最老的连接将被抛弃，并使用这个槽位来保存新的连接。默认值为 4。请小心通过 pgpool-II 进程到后台的连接数可能达到 num_init_children * max_pool 个。需要重启 pgpool-II 以使改动生效。

connection_life_time

缓存的连接的过期时长，单位为秒。过期的缓存连接将被关闭。默认值为 0，表示缓存的连接将不被关闭。

reset_query_list

指定在推出一个会话时发送到后台程序的 SQL 命令。多个命令可以通过“;”隔开。默认为以下的设置但你可以根据你的需求改变。

reset_query_list = 'ABORT; DISCARD ALL'

不同版本的 PostgreSQL 需要使用不同的命令。以下为推荐的设置。

PostgreSQL 版本	reset_query_list 的值
7.1 或更老的版本	ABORT
7.2 到 8.2	ABORT; RESET ALL; SET SESSION AUTHORIZATION DEFAULT
8.3 或更新的版本	ABORT; DISCARD ALL

在 7.4 或更新的版本中，当不是在一个事务块中的时候，“ABORT”将不会被发出。

修改本参数后需要重新加载 pgpool.conf 以使改变生效。

连接池模式中的故障切换

连接池模式中的故障切换和原始模式的相同。

返回顶部

复制模式

本模式在后台程序间启用了数据复制。以下配置参数必须在设置以上参数之外另外设置。

replication_mode

设置为 true 以启用复制模式。默认值为 false。

load_balance_mode

当设置为 true 时，SELECT 查询将被分发到每个后台程序上用于负载均衡。默认值为 false。本参数必须在服务器启动前设置。

replication_stop_on_mismatch

当设置为 true 时，当不同的后台程序返回不同的包类型时，则和其他后台程序差别最大的后台程序将被退化。一个典型的用例为一个事务中的 SELECT 语句，在 replicate_select 设置为 true 的情况下，一个 SELECT 语句从不同的后台程序中返回不同的行数。非 SELECT 语句也可能触发这种情况。例如，一个后台程序执行 UPDATE 成功但其他的失败。注意 pgpool 不会检查 SELECT 返回的记录的内容。如果设置为 false，则会话被终止但后台程序不被退化。默认值为 false。

failover_if_affected_tuples_mismatch V3.0 -

当设置为 true 时，在执行 INSERT/UPDATE/DELETE 后不同的后台程序返回不同的生效记录数，则和其他后台程序差别最大的后台程序将被退化。如果设置为 false，则会话被终止但后台程序不被退化。默认值为 false。

white_function_list V3.0 -

指定一系列用逗号隔开的不会更新数据库的函数名。在复制模式中，不在本列表中指定的函数将即不会被负载均衡，也不会被复制。在主备模式中，这些 SELECT 语句只被发送到主节点。

你可以使用正则表达式来匹配函数名，例如你通过前缀“get_”或“select_”来作为你只读函数的开头：

white_function_list = 'get_.*,select_.*'

black_function_list V3.0 -

指定一系列用逗号隔开的会更新数据库的函数名。在复制模式中，在本列表中指定的函数将即不会被负载均衡，也不会被复制。在主备模式中，这些 SELECT 语句只被发送到主节点。

你可以使用正则表达式来匹配函数名，例如你通过前缀“set_”、“update_”、“delete_”或“insert_”来作为你只读函数的开头：

black_function_list = 'nextval,setval,set_.*,update_.*,delete_.*,insert_.*'

以上两项不能同时配置。

在 pgpool-II 3.0 之前，nextval() 和 setval() 是已知的会写入数据库的函数。你可以通使用 white_function_list 好 balck_function_list 来做到：

white_function_list = ''black_function_list ='nextval,setval,lastval,currval'

注意我们在 nextval 和 setval 后面追加了 lastval 和 currval。虽然 lastval() 和 currval() 不是会写入的函数，但添加 lastval() 和 currval() 可以避免这些函数被无意地被负载均衡到其他的数据库节点而导致错误。添加到 black_function_list 将避免它们被负载均衡。

replicate_select

当设置为 true，pgpool-II 在复制模式中将复制 SELECT 语句。如果为 false，则 pgpool-II 只发送它们到主数据库。默认为 false。

如果 SELECT 查询是在一个显式的事务块中，replicate_select 和 load_balance_mode 将影响复制的工作模式。以下为具体的细节。

SELECT 在一个事务块中	Y	Y	Y	N	N	N	Y	N
replicate_select 为 true	Y	Y	N	N	Y	Y	N	N
load_balance_mode 为 true	Y	N	N	N	Y	N	Y	Y
结果(R: 负载均衡, M: 只发送到主节点, L: 负载均衡)	R	R	M	M	R	R	M	L

insert_lock

如果在包含 SERIAL 类型的表中做复制，SERIAL 列的值在不同后台间可能不同。这个问题可以通过显式的锁表解决（当然，事务的并发性将被严重退化）。为了达到这个目的，必须做以下的改变：

INSERT INTO ...

改变为

      BEGIN;
      LOCK TABLE ...
INSERT INTO ...
      COMMIT;

当 insert_lock 为 true 时，pgpool-II 自动在每次执行 INSERT 时添加以上的查询（如果已经在事务中，它只是简单地添加 LOCK TABLE ...）。

pgpool-II 2.2 或更高的版本中，可以自动探测是否表拥有 SERIAL 类型的列，所以如果没有 SERIAL 类型的列，则将不会锁表。

pgpool-II 3.0 系列直到 3.0.4 为止针对串行的关系使用一个行锁，而不是表锁。这使在 VACUUM（包括 autovacuum）时的锁冲突最小。但这会导致另一个问题。如果发生了嵌套事务，对串行的关系使用行所会导致 PostgreSQL 的内部错误（确切地说，保存事务状态的 pg_clog 会发生访问错误）。为了避免这个问题，PostgreSQL 核心开发者决定禁止对串行的关系加锁，当然这也会让 pgpool-II 无法工作（"修复" 后的 PostgreSQL 版本为 9.0.5, 8.4.9, 8.3.16 和 8.2.22）。

由于新版的 PostgreSQL 不允许对串行的关系加锁，pgpool-II 3.0.5 或更新的版本针对 pgpool_catalog.insert_lock 使用行锁。所以需要预先在通过 pgpool-II 访问的数据库中建立 insert_lock 表。详细内容请参考建立 insert_lock 表。如果不存在 insert_lock 表，pgpool-II 将锁定插入的目标表。这种行为和 pgpool-II 2.2 和 2.3 系列相同。如果你希望使用与旧版本兼容的 insert_lock，你可以在配置脚本中指定锁定模式。详细内容请参考 configure。

你也许需要更好（针对每个事务）的控制手段：

设置 insert_lock 为 true，并添加 /*NO INSERT LOCK*/ 代码到你不想要表锁的 INSERT 语句的开始位置。
设置 insert_lock 为 false，并添加 /*INSERT LOCK*/ 到你需要表锁的 INSERT 语句的开始位置。

默认值为 false。如果 insert_lock 被启用，则（通过 pgpool-II 运行的）PostgreSQL 8.0 的事务、权限、规则和 alter_table 的回归测试会失败。原因是 pgpool-II 会尝试 LOCK 这些规则测试的 VIEW，并产生以下的错误消息：

! ERROR: current transaction is aborted, commands ignored until
      end of transaction block

例如，事务测试尝试 INSERT 到一个不存在的表，而 pgpool-II 导致 PostgreSQL 在这之前请求锁。事务将被终止，而之后的 INSERT 语句会产生以上的错误消息。

recovery_user

本参数指定一个用于在线恢复的 PostgreSQL 用户名。改变本参数不需要重启。

recovery_password

本参数指定一个用于在线恢复的 PostgreSQL 密码。改变本参数不需要重启。

recovery_1st_stage_command

本参数指定一个在在线恢复第一阶段在主（Primary）PostgreSQL 服务器上运行的命令。处于安全原因，本命令必须被放置在数据库实例目录中。例如，如果 recovery_1st_stage_command = 'sync-command'，那么 pgpool-II 将执行 $PGDATA/sync-command。

recovery_1st_stage_command 将接受以下 3 个参数：

到主（Primary）数据库实例的路径
需要恢复的 PostgreSQL 主机名
需要恢复的数据库实例路径

注意 pgpool-II 在执行 recovery_1st_stage_command 时接收连接和查询。在本阶段中，你可以查询和更新数据。

改变本参数不需要重启。

recovery_2nd_stage_command

本参数指定一个在在线恢复第二阶段在主（Primary）PostgreSQL 服务器上运行的命令。处于安全原因，本命令必须被放置在数据库实例目录中。例如，如果 recovery_2st_stage_command = 'sync-command'，那么 pgpool-II 将执行 $PGDATA/sync-command。

recovery_2nd_stage_command 将接受以下 3 个参数：

到主（Primary）数据库实例的路径
需要恢复的 PostgreSQL 主机名
需要恢复的数据库实例路径

注意 pgpool-II 在运行 recovery_2nd_stage_command 时 不接收 连接和查询。因此如果一个客户端长时间持有一个连接，则恢复命令不会被执行。pgpool-II 等待所有的客户端关闭它们的连接。这个命令只在没有任何客户端连接到 pgpool-II 时才执行。

改变本参数不需要重启。

recovery_timeout

pgpool 在第二阶段不接受新的连接。如果一个客户端在恢复过程中连接到 pgpool，它必须等待到恢复结束。

本参数指定恢复超时的时间，单位为秒。如果到达了本超时值，则 pgpool 取消在线恢复并接受连接。0 表示不等待。

改变本参数不需要重启。

client_idle_limit_in_recovery V2.2 -

类似于 client_idle_limit 但是只在恢复的第二阶段生效。从执行最后一个查询后空闲到 client_idle_limit_in_recovery 秒的客户端将被断开连接。这对避免 pgpool 的恢复被懒客户端扰乱或者客户机和 pgpool 之间的 TCP/IP 连接被意外断开（例如网线断开）非常有用。如果设置为 -1，则立即断开客户端连接。client_idle_limit_in_recovery 的默认值为 0，表示本功能不启用。

如果你的客户端非常繁忙，则无论你将 client_idle_limit_in_recovery 设置为多少 pgpool-II 都无法进入恢复的第二阶段。在这种情况下，你可以设置 client_idle_limit_in_recovery 为 -1 因而 pgpool-II 在进入第二阶段前立即断开这些繁忙的客户端的连接。

如果你改变了 client_idle_limit_in_recovery 你需要重新加载 pgpool.conf。

lobj_lock_table V2.2 -

本参数指定一个表名用于大对象的复制控制。如果它被指定，pgpool 将锁定由 lobj_lock_table 指定的表并通过查找 pg_largeobject 系统 catalog 生产一个大对象 id，并调用 lo_create 来建立这个大对象。这个过程保证 pgpool 在复制模式中在所有的数据库节点中获得相同的大对象 id。注意 PostgreSQL 8.0 或者更老的版本没有 lo_create，因此本功能将无法工作。

对 libpq 的 lo_creat() 函数的调用将触发本功能。通过 Java API（JDBC 驱动），PHP API（pg_lo_create，或者 PHP 库中类似的 API 例如 PDO）进行的大对象创建，以及其他各种编程语言中相同的 API 使用相同的协议，因此也应该能够运行。

以下的大对象建立操作将无法运行：

libpq 中的 lo_create
任何语言中使用 lo_create 的任何 API
后台程序的 lo_import 函数
SELECT lo_creat

lobj_lock_table 存储在哪个 schema 并不重要，但是这个表必须对任何用户都可以写入。以下为如何建立这样一个表的示例：

CREATE TABLE public.my_lock_table ();
GRANT ALL ON public.my_lock_table TO PUBLIC;

lobj_lock_table 指定的表必须被预先建立。如果你在 template1 中建立这个表，之后建立的任何数据库都将有这个表。

如果 lobj_lock_table 为空字符串('')，这个功能被禁用（大对象的复制将无法工作）。lobj_lock_table is 的默认值为''。

负载均衡的条件

需要对一个查询使用负载均衡，需要满足以下的所有条件：

PostgreSQL 7.4 或更高版本
查询必须不是在一个显式的事务中（例如，不在 BEGIN ~ END 块中）
不能是 SELECT nextval 或者 SELECT setval
不能是 SELECT INTO
不能是 SELECT FOR UPDATE 或者 FOR SHARE
以 "SELECT" 开始或者为 COPY TO STDOUT, EXPLAIN, EXPLAIN ANALYZE SELECT... 其中一个，ignore_leading_white_space = true 将忽略开头的空格.

注意你可以通过在 SELECT 语句之前插入任意的注释来禁止负载均衡：

/*REPLICATION*/ SELECT ...

请参考replicate_select。也可以参考flow chart。

注：JDBC 驱动有自动提交的选项。如果自动提交为 false，则 JDBC 驱动将自己发送 "BEGIN" 和 "COMMIT"。因此 pgpool-II 无法做任何负载均衡。你需要调用 setAutoCommit(true) 来启用自动提交。

复制模式中的故障切换

pgpool-II 退化一个死掉的后台并继续提供服务。只要最少还有一个后台还或者，服务就可以继续。

复制模式中的特有错误

在复制模式中，如果 pgpool 发现 INSERT，UPDATE 和 DELETE 生效的行数不同，如果 failover_if_affected_tuples_mismatch 被设置为 false，则 pgpool 将发送错误的 SQL 语句到所有的数据库节点来取消当前当前事务（如果为 false 则发生退化）。在这种情况下，你将在客户端终端中看到以下错误信息：

=# UPDATE t SET a = a + 1;
   ERROR: pgpool detected difference of the number of update tuples Possible last query was: "update t1 set i = 1;"
   HINT: check data consistency between master and other db node

你将在 PostgreSQL 的日志中看到更新的行数（在本例中，数据库节点 0 更新了 0 行而数据库节点 1 更新了 1 行）。

2010-07-22 13:23:25 LOG:   pid 5490: SimpleForwardToFrontend: Number of affected tuples are: 0 1
2010-07-22 13:23:25 LOG:   pid 5490: ReadyForQuery: Degenerate backends: 1
2010-07-22 13:23:25 LOG:   pid 5490: ReadyForQuery: Number of affected tuples are: 0 1

返回顶部

主 / 备模式

本模式用于使用其他负责完成实际的数据复制的主 / 备复制软件（类似于 Slong-I 和基于流复制）来连接 pgpool-II。数据库节点的信息（如果你需要在线恢复功能，backend_hostname、backend_port、backend_weight、backend_flag 和 backend_data_directory）必须被设置，和复制模式中的方法相同。另外，还需要设置 master_slave_mode 和 load_balance_mode 为 true。pgpool-II 将发送需要复制的查询到主数据库，并在必要时将其他的查询将被负载均衡。不能被负载均衡而发送到主数据库的查询当然也是受负载均衡逻辑控制的。

在主 / 备模式中，对于临时表的 DDL 和 DML 操作只能在主节点上被执行。SELECT 也可以被强制在主节点上执行，但这需要你在 SELECT 语句前添加一个 /*NO LOAD BALANCE*/ 注释。

在主 / 备模式中，replication_mode 必须被设置为 false，并且 master_slave_mode 为 true。

主 / 备模式有一个“master_slave_sub mode”。默认值为 'slony'，用于 Slony-I。你也可以设置它为 'stream'，它在你想使用 PostgreSQL 内置的复制系统（基于流复制）时被设置。用于 Slony-I 子模式的示例配置文件为 pgpool.conf.sample-master-slave，用于基于流复制的子模式的示例文件为 sub-module is pgpool.conf.sample-stream。

修改以上任何参数都需要重新启动 pgpool-II。

在主 / 备模式中，你可以通过设置 white_function_list 和 black_function_list 来控制负载均衡。参考 white_function_list 获得详细信息。

返回顶部

流复制 V3.1 -

就像以上规定的，pgpool-II 可以与 PostgreSQL 9.0 带来的基于流复制协同工作。要使用它，启用“master_slave_mode”并设置“master_slave_sub_mode”为“stream”。pgpool-II 认为基于流复制启用了热备，也就是说备库是以只读方式打开的。以下参数可以用于本模式：

delay_threshold V3.0 -

指定能够容忍的备机上相对于主服务器上的 WAL 的复制延迟，单位为字节。如果延迟到达了 delay_threshold，pgpool-II 不再发送 SELECT 查询到备机。所有的东西都被发送到主服务器，即使启用了负载均衡模式，直到备机追赶上来。如果 delay_threshold 为 0 或者流复制检查被禁用，则延迟检查不被执行。这个检查在每“sr_check_period”周期执行一次。delay_threshold 的默认值为 0。

要使对本参数的改动生效，你需要重新加载 pgpool.conf。

sr_check_period V3.1 -

本参数指出基于流复制的延迟检查的间隔，单位为秒。默认为 0，表示禁用这个检查。

如果你修改了 sr_check_period，需要重新加载 pgpool.conf 以使变动生效。

sr_check_user V3.1 -

执行基于流复制检查的用户名。用户必须存在于所有的 PostgreSQL 后端上，否则，检查将出错。注意即使 sr_check_period 为 0，sr_check_user 和 sr_check_password 也会被使用。要识别主服务器，pgpool-II 发送函数调用请求到每个后端。sr_check_user 和 sr_check_password 用于这个会话。

如果你修改了 sr_check_user，需要重新加载 pgpool.conf 以使变动生效。

sr_check_password V3.1 -

指出如何记录复制延迟。如果指定 'none'，则不写入日志。如果为 'always'，在每次执行健康检查时记录延迟。如果 'if_over_threshold' 被指定，只有当延迟到达 delay_threshold 时记录日志。log_standby_delay 的默认值为 'none'。

要使对本参数的改动生效，你需要重新加载 pgpool.conf。

log_standby_delay V3.1 -

指出如何记录复制延迟。如果指定 'none'，则不写入日志。如果为 'always'，在每次执行健康检查时记录延迟。如果 'if_over_threshold' 被指定，只有当延迟到达 delay_threshold 时记录日志。log_standby_delay 的默认值为 'none'。要使对本参数的改动生效，你需要重新加载 pgpool.conf。

你也可以使用“show pool_status”命令监控复制延迟。列名为“standby_delay#”（其中 '#' 需要用数据库节点编号代替）。

流复制下的故障切换

在使用流复制的主 / 备模式中，如果主节点或者备节点失效，pgpool-II 可以被设置为触发一个故障切换。节点可以被自动断开而不需要进行更多设置。当进行流复制的时候，备节点检查一个“触发文件”的存在，一旦发现它，则备节点停止持续的恢复并进入读写模式。通过使用这种功能，我们可以使备数据库在主节点失效的时候进行替换。

警告：如果你计划使用多个备节点，我们建议设置一个 delay_threshold 值来避免任何查询由于查询被发送到其他备节点而导致获取旧数据。

如果第二个备节点在第一个备节点已经发生替换的时候替换主节点，你会从第二备节点获取错误的数据。我们不推荐计划使用这种配置。

以下例举了如何设置一个故障切换的配置。

将一个故障切换脚本放置到某个地方（例如 /usr/local/pgsql/bin）并给它执行权限。

$ cd /usr/loca/pgsql/bin
$ cat failover_stream.sh
#! /bin/sh
# Failover command for streaming replication.
# This script assumes that DB node 0 is primary, and 1 is standby.
# 
# If standby goes down, do nothing. If primary goes down, create a
# trigger file so that standby takes over primary node.
#
# Arguments: $1: failed node id. $2: new master hostname. $3: path to
# trigger file.

failed_node=$1
new_master=$2
trigger_file=$3

# Do nothing if standby goes down.
if [$failed_node = 1]; then
	exit 0;
fi

# Create the trigger file.
/usr/bin/ssh -T $new_master /bin/touch $trigger_file

exit 0;

chmod 755 failover_stream.sh

在 pgpool.conf 中设置 failover_commmand。

failover_command = '/usr/local/src/pgsql/9.0-beta/bin/failover_stream.sh %d %H /tmp/trigger_file0'

在备节点中设置 recovery.conf。一个 recovery.conf 示例可以在 PostgreSQL 安装目录中找到。它的名字为 "share/recovery.conf.sample"。拷贝 recovery.conf.sample 为 recovery.conf 到数据库节点目录并编辑它。
```
standby_mode = 'on'
primary_conninfo = 'host=name of primary_host user=postgres'
trigger_file = '/tmp/trigger_file0'
```
设置主节点上的 postgresql.conf。以下仅仅是一个示例。你需要根据你自己的环境做调整。
```
wal_level = hot_standby
max_wal_senders = 1
```
设置主节点上的 pg_hba.conf。以下仅仅是一个示例。你需要根据你自己的环境做调整。
```
host	replication	postgres		192.168.0.10/32		trust
```

启动首要 PostgreSQL 节点和第二 PostgreSQL 节点来初始化基于流复制。如果主节点失效，备节点将自动启动为普通 PostgreSQL 并准备好接受写查询。

流复制

当使用流复制和热备的时候，确定哪个查询可以被发送到主节点或备节点或者不能被发送到备节点非常重要。pgpool-II 的流复制模式可以很好的处理这种情况。在本章，我们将解释 pgpool-II 如何做到这一点的。

我们通过检查查询来辨别哪个查询应该被发送到哪个节点。

这些查询只允许被发送到主节点
- INSERT, UPDATE, DELETE, COPY FROM, TRUNCATE, CREATE, DROP, ALTER, COMMENT
- SELECT ... FOR SHARE | UPDATE
- 在事务隔离级别为 SERIALIZABLE 的 SELECT
- 比 ROW EXCLUSIVE MODE 更严厉的 LOCK 命令
- 一些事务相关命令：
  - BEGIN READ WRITE, START TRANSACTION READ WRITE
  - SET TRANSACTION READ WRITE, SET SESSION CHARACTERISTICS AS TRANSACTION READ WRITE
  - SET transaction_read_only = off
- 两步提交命令：PREPARE TRANSACTION, COMMIT PREPARED, ROLLBACK PREPARED
- LISTEN, UNLISTEN, NOTIFY
- VACUUM
- 一些序列生成器操作函数（nextval 和 setval）
- 大对象建立命令
这些查询可以被发送到主节点和备节点。如果启用了负载均衡，这些查询可以被发送到备节点。但是，如果设置了 delay_threshold 且复制延迟大于这个值，则查询被发送到主节点。
- SELECT not listed above
- COPY TO
- DECLARE, FETCH, CLOSE
- SHOW
以下查询被同时发送到主节点和备节点
- SET
- DISCARD
- DEALLOCATE ALL

在一个显式的事务中：

启动事务的命令例如 BEGIN 只被发送到主节点。
接下来的 SELECT 和一些可以被发送到主节点或备节点的其他查询会在事务中执行或者在备节点中执行。
无法在备节点中执行的命令例如 INSERT 被发送到主节点。在这些命令之后的命令，即使是 SELECT 也被发送到主节点。这是因为这些 SELECT 语句可能需要立即查看 INSERT 的结果。这种行为一直持续到事务关闭或者终止。

在扩展协议中，在负载均衡模式中在分析查询时，有可能探测是否查询可以被发送到备节点。规则和非扩展协议下相同。例如，INSERT 被发送到主节点。接下来的 bind，describe 和 execute 也将被发送到主节点。

[注：如果对 SELECT 语句的分析由于负载均衡被发送到备节点，然后一个 DML 语句，例如一个 INSERT，被发送到 pgpool-II，那么，被分析的 SELECT 必须在主节点上执行。因此，我们会在主节点上重新分析这个 SELECT 语句。]

最后，pgpool-II 的分析认为有错误的查询将被发送到主节点。

流复制中的在线恢复

在流复制的主 / 备模式中，可以执行在线恢复。在在线恢复过程中，首要务器扮演了主服务器的角色并恢复到指定的备服务器。因此恢复过程需要首要服务器启动并运行。如果第一服务器失效且没有备用服务器被提升，你需要停止 pgpool-II 和所有的 PostgreSQL 服务器并手动恢复它们。

设置 recovery_user。通常为 "postgres"。
```
recovery_user = 'postgres'
```
设置登录到数据库的 recover_user 的 recovery_password。
```
recovery_password = 't-ishii'
```
设置 recovery_1st_stage_command。这个阶段的这个脚本用来执行一个首要数据库的备份并还原它到备用节点。将此脚本放置在首要数据库示例的目录中并给它可执行权限。这里有一个用于配置了一个主节点和一个备节点的示例脚本 (basebackup.sh)。你需要设置 ssh 让 recovery_user 可以从首要节点登录到备用节点而不需要提供密码。
```
recovery_1st_stage_command = 'basebackup.sh'
```
让 recovery_2nd_stage_command 保留为空。
```
recovery_2nd_stage_command = ''
```

在每个数据库节点中安装必须的执行在线恢复的 C 和 SQL 函数。

# cd pgpool-II-x.x.x/sql/pgpool-recovery
# make
# make install
# psql -f pgpool-recovery.sql template1

在完成在线恢复后，pgpool-II 将在备节点启动 PostgreSQL。在每个数据库节点中安装用于本用途的脚本。示例脚本包含在源码的“sample”目录中。这个脚本使用了 ssh。你需要允许 recover_user 从首要节点登录到备用节点而不需要输入密码。

以上未全部内容。现在你可以使用 pcp_recovery_node（作为备用节点的步骤）或者点击 pgpoolAdmin 的“恢复”按钮来执行在线恢复了。如果出现问题，请检查 pgpool-II 的日子，首要服务器的日志和备用服务器的日志。

作为参考，以下为恢复过程的步骤。

Pgpool-II 使用 user = recovery_user, password = recovery_password 连接到首要服务器的 template1 数据库。
首要服务器执行 pgpool_recovery 函数。
pgpool_recovery 函数执行 recovery_1st_stage_command。注意 PostgreSQL 在数据库实例的当前目录中执行函数。因此，recovery_1st_stage_command 在数据库实例的目录中执行。
首要服务器执行 pgpool_remote_start 函数。本函数执行一个在数据库实例路径中名为“pgpool_remote_start”的脚本，它通过 ssh 在备用服务器上执行 pg_ctl 命令来进行恢复。pg_ctl 将在后台启动 postmaster。所以我们需要确保备用节点上的 postmaster 真正启动了。
pgpool-II 尝试使用 user = recovery_user 和 password = recovery_password 连接到备用 PostgreSQL。如果可能，连接到的数据库为“postgres”。否则，使用“template1”。pgpool-II 尝试 recovery_timeout 秒。如果成功，进行下一步。
如果 failback_command 不为空，pgpool-II 父进程执行这个脚本。
在 failback_command 完成后，pgpool-II 重新启动所有的子进程。

返回顶部

并行模式

本模式实现了查询的并行执行。表可以被分割，数据分布在每个节点中。而且，复制和负载均衡功能也可以同时使用。在并行模式中，pgpool.conf 中的 replication_mode 和 load_balance_mode 被设置为 ture，master_slave 被设置为 false，parallel_mode 被设置为 false。当你改变这些参数后，需要重启 pgpool-II。

配置 System DB

如果想使用并行模式，System DB 需要被正确配置。System DB 包含存储在一个表中的，用于选择被分区的数据将被发送到的恰当后端程序的规则。System DB 不一定要和 pgpool-II 在同一台主机上。System DB 的配置由 pgpool.conf 完成。

system_db_hostname

System DB 所在的主机名。给出空字符串 ('') 表示 SystemDB 和 pgpool-II 在同一台主机，且将通过 UNIX 域套接字访问。

system_db_port

System DB 使用的端口号

system_dbname

分区规则和其他的信息将被定义到这里指定的数据库中。默认值为：'pgpool'。

system_db_schema

分区规则和其他的信息将被定义到这里指定的模式中。默认值为：'pgpool_catalog'。

system_db_user

连接到 System DB 的用户名。

system_db_password

连接到 System DB 的密码，如果不需要密码，则设置为空字符串('')。

ssl_ca_cert

到达用于校验后台服务器的 PEM 格式的包含一个或者多个 CA 根证书的文件的路径。这类似于 OpenSSL 的 verify(1) 命令的 -CAfile 选项。

默认值为未设置，也就是不进行认证。如果本选项未设置但是 ssl_ca_cert_dir被设置了，则认证过程依旧会发生。

ssl_ca_cert_dir

到达包含用于校验后台服务器的 PEM 格式的 CA 证书的目录的路径。这类似于 OpenSSL 的 verify(1) 命令的 -CApath 选项。

默认值为未设置，也就是不进行认证。如果本选项未设置但是 ssl_ca_cert 被设置了，则认证过程依旧会发生。

初始化 System DB 的配置

首先，需要建立 pgpool.conf 文件中指定的数据库和模式。可以在 $prefix/share/system_db.sql 找到一个示例脚本。如果你指定了不同的数据库名和模式，在脚本中相应地修改它们。

psql -f $prefix/share/system_db.sql pgpool

注册一条分区规则

用于数据分区的规则必须被注册到 pgpool_catalog.dist_def 表中。

CREATE TABLE pgpool_catalog.dist_def(
dbname TEXT,                                              -- database name
schema_name TEXT,                                         -- schema name
table_name TEXT,                                          -- table name
col_name TEXT NOT NULL CHECK (col_name = ANY (col_list)), -- partitioning key column name
col_list TEXT[] NOT NULL,                                 -- names of table attributes
type_list TEXT[] NOT NULL,                                -- types of table attributes
dist_def_func TEXT NOT NULL,                              -- name of the partitioning rule function
PRIMARY KEY (dbname,schema_name,table_name)
);

注册一条复制规则

未被分发的表必须被复制. 当一个查询对一个分发表和另外一个表进行连接时，pgpool-II 从 pgpool_catalog.replicate_def 表获取复制信息。一个表只能被复制或被分发。

CREATE TABLE pgpool_catalog.replicate_def(
	dbname TEXT,	    --database name
	schema_name TEXT,	--schema name 
	table_name TEXT,	--table name
	col_list TEXT[] NOT NULL,	-- names of table attributes
	type_list TEXT[] NOT NULL,	-- types of table attributes
	PRIMARY KEY (dbname,schema_name,table_name)
);

对 pgbench 表的分区示例

在这个示例中，accounts 表被分区，branches 和 tellers 表被复制。accounts 表和 branches 表通过 bid 进行连接。branches 表注册到复制表中，若这三个表（accounts, branches 和 tellers）将被连接的话，有必要也为 tellers 表注册一条复制规则。

INSERT INTO pgpool_catalog.dist_def VALUES (
	'pgpool',
	'public',
	'accounts',
	'aid',
	ARRAY['aid','bid','abalance','filler'],
	ARRAY['integer','integer','integer','character(84)'],
	'pgpool_catalog.dist_def_accounts'
);

INSERT INTO pgpool_catalog.replicate_def VALUES (
	'pgpool',
	'public',
	'branches',
	ARRAY['bid','bbalance','filler'],
	ARRAY['integer','integer','character(84)']
);

分区规则函数（此处是 pgpool_catalog.dist_def_accounts）需要一个值作为分区的关键字列，并返回相应的 DB 节点 ID。注意节点 ID 必须从 0 开始，下面是为 pgbench 写的函数示例。

CREATE OR REPLACE FUNCTION pgpool_catalog.dist_def_accounts (val ANYELEMENT) RETURNS INTEGER AS '
SELECT CASE WHEN $1 >= 1 and $1 <= 30000 THEN 0
WHEN $1 > 30000 and $1 <= 60000 THEN 1
ELSE 2

返回顶部

设置用于客户端认证 (HBA) 的 pool_hba.conf

和 PostgreSQL 中使用的 pg_hba.conf 文件类似，pgpool-II 使用一个称之为 "pool_hba.conf" 的配置文件来支持类似的客户端认证功能。

当安装 pgpool 的时候，pool_hba.conf.sample 文件将被安装在 "/usr/local/etc" 目录下，该位置也是配置文件的默认目录。拷贝 pool_hba.conf.sample 为 pool_hba.conf，如果必要的话并修改它。默认的情况下，pool_hba 认证被开启，详见 "6. 设置 pgpool.conf"。

pool_hba.conf 文件的格式和 PostgreSQL 的 pg_hba.conf 的格式遵循的非常相近。

local      DATABASE  USER  METHOD  [OPTION]
    host       DATABASE  USER  CIDR-ADDRESS  METHOD  [OPTION]

查看 "pool_hba.conf.sample" 文件获取每个字段详细的解释。

下面是 pool_hba 的一些限制。

"hostssl" 连接类型不被支持

尽管 "hostssl" 不能被使用，pgpool-II 2.3 或更高版本支持 SSL，详见SSL。

DATABASE 字段使用的 "samegroup" 不被支持

尽管 pgpool 并不知道后端服务器的用户的任何信息，但是将通过 pool_hba.conf 中的 DATABASE 字段项对数据库名进行简单的检查。

USER 字段使用的 group 名字后面跟个 "+" 不被支持

这与上面介绍的 "samegroup" 原因相同，将通过 pool_hba.conf 中 USER 字段项对用户名进行简单的检查。

为 IP address/mask 使用的 IPv6 不被支持

pgpool 当前不支持 IPv6.

METHOD 字段仅仅支持 "trust", "reject", "md5" 和 "pam"

再次，这与上面介绍的 "samegroup" 原因相同, pgpool 不能够访问 user/password 信息。

要使用 md5 认证，你需要在 "pool_passwd" 中注册你的名字和密码。详见认证 / 访问控制。

注意本节描述的所有认证发生在客户端和 pgpool-II 之间；客户端仍然需要继续通过 PostgreSQL 的认证过程。pool_hba 并不关心客户端提供的用户名 / 数据库名（例如 psql -U testuser testdb）是否真实存在于后端服务器中。pool_hba 仅仅关心是否在 pool_hba.conf 中存在匹配。

PAM 认证使用 pgpool 运行的主机上的用户信息来获得支持。若让 pgpool 支持 PAM，需要在 configure 时指定 "--with-pam" 选项。

configure --with-pam

若启用 PAM 认证，你需要为 pgpool 在系统的 PAM 配置目录 (通常是在 "/etc/pam.d") 中创建一个 service-configuration 文件。一个 service-configuration 的示例文件被安装为安装目录下的 "share/pgpool.pam"。

设置 Query cache 方法 - V3.1 (已废弃)

注意：这个（基于磁盘的）查询缓存功能将在不久后被移除。清使用基于内存的查询缓存代替。

Query cache 可以在 pgpool-II 的所有模式中使用。在 pgpool.conf 中启用它如下：

enable_query_cache = true

你还需要在 System DB 中创建下面的表：

CREATE TABLE pgpool_catalog.query_cache (
  hash TEXT,
  query TEXT,
  value bytea,
  dbname TEXT,
  create_time TIMESTAMP WITH TIME ZONE,
  PRIMARY KEY(hash, dbname)
);

然而，如果你不使用 "pgpool_catalog" 的话，你可能需要修改该语句中的 schema。

注意：当前的查询缓存的实现方法为在数据库中建立缓存数据。因此启用查询缓存可能会导致达不到最高的性能。即使相关的表被更新了，查询缓存的内容不会更新。你需要从缓存的表中删除缓存的数据或者通过 -c（删除缓存）参数重启 pgpool-II。

基于内存的查询缓存 V3.2 -

你可以在任何模式中使用基于内存的查询缓存。它不同于以上的查询缓存，因为基于内存的查询缓存会快很多，因为缓存存储于内存中。另外，如果缓存事小了，你不需要重启 pgpool-II 因为相关的表已经得到更新了。

基于内存的缓存保存 SELECT 语句（以及它绑定的参数，如果 SELECT 是一个扩展的查询）以及对应的数据。如果是相同的 SELECT 语句，则直接返回缓存的值。因为不再有 SQL 分析或者到 PostgreSQL 的调用，实际上它会非常快。

其他方面，它会比较慢，因为它增加了一些负载用于缓存。另外，当一个表被更新，pgpool 自动删除相关的表的缓存。因此，在有很多更新的系统中，性能会降低。如果 cache_hit_ratio 低于 70%，建议你关闭基于内存的缓存。

限制

基于内存的查询缓存通过监视 UPDATE，INSERT，ALTER TABLE 一类的查询语句来自动删除缓存的数据。但 pgpool-II 无法发现通过触发器、外键和 DROP TABLE CASCADE 产生的非显式的更新。你可以通过配置 memqcache_expire 让 pgpool 在固定时间周期内自动删除缓存来避免这个问题，你也可以通过配置 black_memqcache_table_list 来让 pgpool 的基于内存的缓存忽略指定的表。
如果你使用 pgpool-II 的多个实例来使用共享内存进行缓存，可能出现一个 pgpool 发现表被更新了因而删除了缓存，但另一个依旧使用旧的缓存。对于这种情况，使用 memcached 是一个更好的策略。

启用基于内存的查询缓存

要启用基于内存的查询缓存，设置以下选项为 on（默认为 off）。

memory_cache_enabled = on

选择缓存策略

你可以选择一个缓存策略：共享内存或者 memcached（不能同时使用）。使用共享内存的查询缓存很快且简单，因为你不需要安装和配置 memcached，但缓存的最大数量限制于共享内存。使用 memcached 的查询缓存需要更多的负载用于访问网络，但你可以任意设置你需要的大小。

可以通过 memqcache_method 指定内存缓存的行为。可以是“shmem”或者“memcached”。默认为 shmem。

memqcache_method = 'shmem'

基于内存缓存被禁用的情况

并非所有的 SELECT 和 WITH 语句可以被缓存。在包括以下列表的一些情况，为了保证数据库和缓存的一致性，缓存被避免了。

SELECT 包含以下表的 black_memqcache_table_list
SELECT FOR SHARE / UPDATE
SELECT 包含 un-immutable 函数
SELECT 包含 TEMP TABLE
SELECT 包含系统对象
SELECT 包含 VIEW 和不记录日志的表。但如果表在 white_memqcache_table_list 中，结果还是会被缓存的。
SELECT 包含 VIEW
SELECT 在一个被终止的显示事务中
SELECT 结果超出 memqcache_maxcache

缓存不被使用的情况

存在一些情况，及时匹配的查询缓存存在，pgpool 也不返回结果。

如果一个更新擦做在一个显式的事务中执行，在事务中，pgpool 不使用查询缓存。
匹配的查询是由其他用户（因为安全原因）生成的。
匹配的查询由于 memqcache_expire 设置而需要被删除。

配置

以下参数可以同时用于 shmem 和 memcached。

memqcache_expire V3.2 -

查询缓存的生命周期，默认为 0。0 表示没有缓存超时，而且缓存被启用直到表被更新。本参数和 memqcache_auto_cache_invalidation 是相交的。

memqcache_auto_cache_invalidation V3.2 -

如果为 on，则在表被更新的时候自动删除相关的缓存。如果为 off，则不删除缓存。默认为 on。本参数和 memqcache_expire 相交。

memqcache_maxcache V3.2 -

如果 SELECT 结果集的大小超出了 memqcache_maxcache 字节，则不缓存且显示以下消息：

2012-05-02 15:08:17 LOG:   pid 13756: pool_add_temp_query_cache: data size exceeds memqcache_maxcache. current:4095 requested:111 memq_maxcache:4096

要避免这个问题，你需要将 memqcache_maxcache 设置得大一些。但如果你使用共享内存作为缓存策略，它必须小于 memqcache_cache_block_size。如果是 memchached，她必须小于 slab 的大小（默认为 1 MB）。

white_memqcache_table_list V3.2 -

指定一个以逗号分隔的表名的列表，用于使 SELECT 的结果被缓存，也可以是视图或者不写日志的表。可以使用正则表达式。

同时存在于 white_memqcache_table_list 和 black_memqcache_table_list 的表和视图将被缓存。

black_memqcache_table_list V3.2 -

指定一个以逗号分隔的表名的列表，用于使 SELECT 的结果不被缓存，也可以是视图或者不写日志的表。可以使用正则表达式。

memqcache_oiddir V3.2 -

用于 SELECT 的存储表的 OID 的目录的完整路径。在 memqcache_oiddir 下有使用数据库 oid 命名的目录，每个目录之下是在 SELECT 中使用的以表的 oid 命名的文件。在文件中，存储了查询缓存。它们是用于删除缓存的关键。

在 memqcache_oiddir 下的目录和文件不会被删除，即使 pgpool-II 重启。如果你使用 "pgpool -C" 启动 pgpool，则 pgpool 使用旧的 oid 映射。

监控缓存

这里讲述如何监控查询缓存。要知道一个 SELECT 的结果是不是从查询缓存获得，需要启用 log_per_node_statement。

2012-05-01 15:42:09 LOG:   pid 20181: query result fetched from cache. statement: select * from t1;

pool_status 命令显示缓存的命中率。

memqcache_stats_start_time           | Tue May  1 15:41:59 2012 | Start time of query cache stats
memqcache_no_cache_hits              | 80471                    | Number of SELECTs not hitting query cache
memqcache_cache_hits                 | 36717                    | Number of SELECTs hitting query cache

在本例中，你可以通过以下方法计算：

(memqcache_cache_hits) / (memqcache_no_cache_hits+memqcache_cache_hits) = 36717 / (36717 + 80471) = 31.3%

show pool_cache 也显示相同的结果。

配置使用共享内存

以下为用于共享内存缓存策略的参数。

memqcache_total_size V3.2 -: 指定用于缓存的共享内存的大小，单位为字节。
memqcache_max_num_cache V3.2 -: 制定缓存的项目数。这用于定义缓存管理空间的大小。（你需要它来协助 memqcache_total_size 参数）。可以使用以下方法计算缓存管理空间的大小：memqcache_max_num_cache * 48 字节。如果数量太小，则注册缓存的时候会报错。但如果太大则浪费空间。
memqcache_cache_block_size V3.2 -: 如果缓存存储是共享内存，pgpool 使用内存除以 memqcache_cache_block_size。SELECT 的结果被放入块中。但是因为 SELECT 的结果不能被放入多个块中，它无法缓存大于 memqcache_cache_block_size 的结果。memqcache_cache_block_size 必须大于或等于 512。

配置使用 memcached

以下为用于 memcached 缓存策略的参数。

memqcache_memcached_host V3.2 -: 指定 memcached 工作的主机的主机名或 IP 地址。如果和 pgpool-II 在同一台机器，设置为 'localhost'。
memqcache_memcached_port V3.2 -: 指定 memcached 的端口。默认为 11211。

memcached 安装

要使用 memcached 作为缓存策略，pgpool-II 需要配合 memcached 和其客户端 libmemcached 使用。通过 rpm 安装很简单。这里讲解如何使用源码安装。

可以在以下位置获得 memcached 的源码：memcached development page

configure

在解压源码包后，执行配置脚本。

./configure

make

make
make install

libmemcached 安装

Libmemcached 是 memcached 的客户端库。你需要在安装 memcached 后安装 libmemcached。

可以在以下位置获得 libmemcached 的源码：libmemcached development page

configure

在解压源码包后，执行配置脚本。

./configure

如果你不想使用默认值，一些可选项为：

--with-memcached=path
安装 Memcached 的顶层目录。

make

make
make install

特殊字符	描述
%d	断开连接的节点的后台 ID。
%h	断开连接的节点的主机名。
%p	断开连接的节点的端口号。
%D	断开连接的节点的数据库实例所在目录。
%M	旧的主节点 ID。
%m	新的主节点 ID。
%H	新的主节点主机名。
%P	旧的第一节点 ID。
%%	'%' 字符

特殊字符	描述
%d	新连接上的节点的后台 ID。
%h	新连接上的节点的主机名。
%p	新连接上的节点的端口号。
%D	新连接上的节点的数据库实例所在目录。
%M	旧的主节点 ID。
%m	新的主节点 ID。
%H	新的主节点主机名。
%P	旧的第一节点 ID。
%%	'%' 字符

pgpool配置文件详解

连接

池

日志

文件位置

连接池

健康检查

故障切换和恢复

负载均衡模式

后端（PostgreSQL 服务器）

SSL

其他

生成 SSL 证书

在原始模式中的故障切换

连接池模式

复制模式

负载均衡的条件

主 / 备模式

流复制 V3.1 -

流复制下的故障切换

流复制

流复制中的在线恢复

并行模式

配置 System DB

初始化 System DB 的配置

注册一条分区规则

注册一条复制规则

对 pgbench 表的分区示例

设置用于客户端认证 (HBA) 的 pool_hba.conf

设置 Query cache 方法 - V3.1 (已废弃)

基于内存的查询缓存 V3.2 -

限制

启用基于内存的查询缓存

选择缓存策略

基于内存缓存被禁用的情况

缓存不被使用的情况

配置

监控缓存

配置使用共享内存

配置使用 memcached

memcached 安装

libmemcached 安装

Gin-vue-admin 多数据库支持

在Gin框架使用session