prestogres 0.1.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (393) hide show
  1. data/.gitignore +4 -0
  2. data/Gemfile +2 -0
  3. data/Gemfile.lock +20 -0
  4. data/LICENSE +202 -0
  5. data/NOTICE +22 -0
  6. data/README.md +217 -0
  7. data/Rakefile +13 -0
  8. data/VERSION +1 -0
  9. data/bin/prestogres +254 -0
  10. data/config/pcp.conf.sample +28 -0
  11. data/config/pgpool.conf +678 -0
  12. data/config/pool_hba.conf +84 -0
  13. data/config/pool_passwd +0 -0
  14. data/config/postgresql.conf +2 -0
  15. data/ext/.gitignore +6 -0
  16. data/ext/depend +26 -0
  17. data/ext/extconf.rb +4 -0
  18. data/ext/prestogres_config.c +12 -0
  19. data/pgpool2/.gitignore +36 -0
  20. data/pgpool2/AUTHORS +4 -0
  21. data/pgpool2/COPYING +12 -0
  22. data/pgpool2/ChangeLog +1 -0
  23. data/pgpool2/INSTALL +1 -0
  24. data/pgpool2/Makefile.am +159 -0
  25. data/pgpool2/Makefile.in +1187 -0
  26. data/pgpool2/NEWS +4960 -0
  27. data/pgpool2/README +1 -0
  28. data/pgpool2/README.euc_jp +1 -0
  29. data/pgpool2/README.online-recovery +62 -0
  30. data/pgpool2/TODO +103 -0
  31. data/pgpool2/ac_func_accept_argtypes.m4 +85 -0
  32. data/pgpool2/aclocal.m4 +1088 -0
  33. data/pgpool2/c-compiler.m4 +134 -0
  34. data/pgpool2/c-library.m4 +325 -0
  35. data/pgpool2/child.c +2097 -0
  36. data/pgpool2/config.guess +1532 -0
  37. data/pgpool2/config.h.in +332 -0
  38. data/pgpool2/config.sub +1640 -0
  39. data/pgpool2/configure +15752 -0
  40. data/pgpool2/configure.in +392 -0
  41. data/pgpool2/depcomp +522 -0
  42. data/pgpool2/doc/basebackup.sh +17 -0
  43. data/pgpool2/doc/pgpool-de.html +4220 -0
  44. data/pgpool2/doc/pgpool-en.html +5738 -0
  45. data/pgpool2/doc/pgpool-fr.html +4118 -0
  46. data/pgpool2/doc/pgpool-ja.css +198 -0
  47. data/pgpool2/doc/pgpool-ja.html +11279 -0
  48. data/pgpool2/doc/pgpool-zh_cn.html +4445 -0
  49. data/pgpool2/doc/pgpool.css +280 -0
  50. data/pgpool2/doc/pgpool_remote_start +13 -0
  51. data/pgpool2/doc/recovery.conf.sample +117 -0
  52. data/pgpool2/doc/tutorial-en.html +707 -0
  53. data/pgpool2/doc/tutorial-ja.html +422 -0
  54. data/pgpool2/doc/tutorial-memqcache-en.html +325 -0
  55. data/pgpool2/doc/tutorial-memqcache-ja.html +370 -0
  56. data/pgpool2/doc/tutorial-memqcache-zh_cn.html +322 -0
  57. data/pgpool2/doc/tutorial-watchdog-en.html +306 -0
  58. data/pgpool2/doc/tutorial-watchdog-ja.html +343 -0
  59. data/pgpool2/doc/tutorial-watchdog-zh_cn.html +301 -0
  60. data/pgpool2/doc/tutorial-zh_cn.html +537 -0
  61. data/pgpool2/doc/watchdog.png +0 -0
  62. data/pgpool2/doc/wd-en.html +236 -0
  63. data/pgpool2/doc/wd-en.jpg +0 -0
  64. data/pgpool2/doc/wd-ja.html +219 -0
  65. data/pgpool2/doc/wd-ja.jpg +0 -0
  66. data/pgpool2/doc/wd-zh_cn.html +201 -0
  67. data/pgpool2/doc/where_to_send_queries.odg +0 -0
  68. data/pgpool2/doc/where_to_send_queries.pdf +0 -0
  69. data/pgpool2/general.m4 +166 -0
  70. data/pgpool2/getopt_long.c +200 -0
  71. data/pgpool2/getopt_long.h +44 -0
  72. data/pgpool2/install-sh +251 -0
  73. data/pgpool2/ltmain.sh +8406 -0
  74. data/pgpool2/m4/libtool.m4 +7360 -0
  75. data/pgpool2/m4/ltoptions.m4 +368 -0
  76. data/pgpool2/m4/ltsugar.m4 +123 -0
  77. data/pgpool2/m4/ltversion.m4 +23 -0
  78. data/pgpool2/m4/lt~obsolete.m4 +92 -0
  79. data/pgpool2/main.c +2971 -0
  80. data/pgpool2/md5.c +444 -0
  81. data/pgpool2/md5.h +28 -0
  82. data/pgpool2/missing +360 -0
  83. data/pgpool2/mkinstalldirs +40 -0
  84. data/pgpool2/parser/Makefile.am +50 -0
  85. data/pgpool2/parser/Makefile.in +559 -0
  86. data/pgpool2/parser/copyfuncs.c +3310 -0
  87. data/pgpool2/parser/gram.c +39100 -0
  88. data/pgpool2/parser/gram.h +940 -0
  89. data/pgpool2/parser/gram.y +13408 -0
  90. data/pgpool2/parser/gramparse.h +74 -0
  91. data/pgpool2/parser/keywords.c +32 -0
  92. data/pgpool2/parser/keywords.h +39 -0
  93. data/pgpool2/parser/kwlist.h +425 -0
  94. data/pgpool2/parser/kwlookup.c +88 -0
  95. data/pgpool2/parser/list.c +1156 -0
  96. data/pgpool2/parser/makefuncs.c +518 -0
  97. data/pgpool2/parser/makefuncs.h +83 -0
  98. data/pgpool2/parser/memnodes.h +79 -0
  99. data/pgpool2/parser/nodes.c +29 -0
  100. data/pgpool2/parser/nodes.h +609 -0
  101. data/pgpool2/parser/outfuncs.c +5790 -0
  102. data/pgpool2/parser/parsenodes.h +2615 -0
  103. data/pgpool2/parser/parser.c +262 -0
  104. data/pgpool2/parser/parser.h +46 -0
  105. data/pgpool2/parser/pg_class.h +158 -0
  106. data/pgpool2/parser/pg_config_manual.h +273 -0
  107. data/pgpool2/parser/pg_list.h +352 -0
  108. data/pgpool2/parser/pg_trigger.h +147 -0
  109. data/pgpool2/parser/pg_wchar.h +492 -0
  110. data/pgpool2/parser/pool_memory.c +342 -0
  111. data/pgpool2/parser/pool_memory.h +77 -0
  112. data/pgpool2/parser/pool_parser.h +222 -0
  113. data/pgpool2/parser/pool_string.c +121 -0
  114. data/pgpool2/parser/pool_string.h +37 -0
  115. data/pgpool2/parser/primnodes.h +1280 -0
  116. data/pgpool2/parser/scan.c +4094 -0
  117. data/pgpool2/parser/scan.l +1451 -0
  118. data/pgpool2/parser/scanner.h +120 -0
  119. data/pgpool2/parser/scansup.c +221 -0
  120. data/pgpool2/parser/scansup.h +28 -0
  121. data/pgpool2/parser/snprintf.c +1102 -0
  122. data/pgpool2/parser/stringinfo.c +294 -0
  123. data/pgpool2/parser/stringinfo.h +178 -0
  124. data/pgpool2/parser/value.c +78 -0
  125. data/pgpool2/parser/value.h +62 -0
  126. data/pgpool2/parser/wchar.c +2048 -0
  127. data/pgpool2/pcp.conf.sample +28 -0
  128. data/pgpool2/pcp/Makefile.am +40 -0
  129. data/pgpool2/pcp/Makefile.in +771 -0
  130. data/pgpool2/pcp/libpcp_ext.h +250 -0
  131. data/pgpool2/pcp/md5.c +444 -0
  132. data/pgpool2/pcp/md5.h +28 -0
  133. data/pgpool2/pcp/pcp.c +1652 -0
  134. data/pgpool2/pcp/pcp.h +61 -0
  135. data/pgpool2/pcp/pcp_attach_node.c +172 -0
  136. data/pgpool2/pcp/pcp_detach_node.c +185 -0
  137. data/pgpool2/pcp/pcp_error.c +87 -0
  138. data/pgpool2/pcp/pcp_node_count.c +160 -0
  139. data/pgpool2/pcp/pcp_node_info.c +198 -0
  140. data/pgpool2/pcp/pcp_pool_status.c +166 -0
  141. data/pgpool2/pcp/pcp_proc_count.c +166 -0
  142. data/pgpool2/pcp/pcp_proc_info.c +261 -0
  143. data/pgpool2/pcp/pcp_promote_node.c +185 -0
  144. data/pgpool2/pcp/pcp_recovery_node.c +172 -0
  145. data/pgpool2/pcp/pcp_stop_pgpool.c +179 -0
  146. data/pgpool2/pcp/pcp_stream.c +385 -0
  147. data/pgpool2/pcp/pcp_stream.h +52 -0
  148. data/pgpool2/pcp/pcp_systemdb_info.c +194 -0
  149. data/pgpool2/pcp/pcp_watchdog_info.c +211 -0
  150. data/pgpool2/pcp_child.c +1493 -0
  151. data/pgpool2/pg_md5.c +305 -0
  152. data/pgpool2/pgpool.8.in +121 -0
  153. data/pgpool2/pgpool.conf +553 -0
  154. data/pgpool2/pgpool.conf.sample +666 -0
  155. data/pgpool2/pgpool.conf.sample-master-slave +665 -0
  156. data/pgpool2/pgpool.conf.sample-replication +664 -0
  157. data/pgpool2/pgpool.conf.sample-stream +664 -0
  158. data/pgpool2/pgpool.spec +264 -0
  159. data/pgpool2/pgpool_adm/TODO +7 -0
  160. data/pgpool2/pgpool_adm/pgpool_adm--1.0.sql +85 -0
  161. data/pgpool2/pgpool_adm/pgpool_adm.c +558 -0
  162. data/pgpool2/pgpool_adm/pgpool_adm.control +5 -0
  163. data/pgpool2/pgpool_adm/pgpool_adm.h +46 -0
  164. data/pgpool2/pgpool_adm/pgpool_adm.sql.in +85 -0
  165. data/pgpool2/pool.h +655 -0
  166. data/pgpool2/pool_auth.c +1390 -0
  167. data/pgpool2/pool_config.c +5007 -0
  168. data/pgpool2/pool_config.h +284 -0
  169. data/pgpool2/pool_config.l +3281 -0
  170. data/pgpool2/pool_config_md5.c +29 -0
  171. data/pgpool2/pool_connection_pool.c +812 -0
  172. data/pgpool2/pool_error.c +242 -0
  173. data/pgpool2/pool_globals.c +27 -0
  174. data/pgpool2/pool_hba.c +1723 -0
  175. data/pgpool2/pool_hba.conf.sample +67 -0
  176. data/pgpool2/pool_ip.c +567 -0
  177. data/pgpool2/pool_ip.h +65 -0
  178. data/pgpool2/pool_ipc.h +38 -0
  179. data/pgpool2/pool_lobj.c +242 -0
  180. data/pgpool2/pool_lobj.h +32 -0
  181. data/pgpool2/pool_memqcache.c +3818 -0
  182. data/pgpool2/pool_memqcache.h +268 -0
  183. data/pgpool2/pool_params.c +163 -0
  184. data/pgpool2/pool_passwd.c +249 -0
  185. data/pgpool2/pool_passwd.h +41 -0
  186. data/pgpool2/pool_path.c +193 -0
  187. data/pgpool2/pool_path.h +81 -0
  188. data/pgpool2/pool_process_context.c +247 -0
  189. data/pgpool2/pool_process_context.h +62 -0
  190. data/pgpool2/pool_process_query.c +5001 -0
  191. data/pgpool2/pool_process_reporting.c +1671 -0
  192. data/pgpool2/pool_process_reporting.h +44 -0
  193. data/pgpool2/pool_proto2.c +671 -0
  194. data/pgpool2/pool_proto_modules.c +3524 -0
  195. data/pgpool2/pool_proto_modules.h +185 -0
  196. data/pgpool2/pool_query_cache.c +1020 -0
  197. data/pgpool2/pool_query_context.c +1871 -0
  198. data/pgpool2/pool_query_context.h +105 -0
  199. data/pgpool2/pool_relcache.c +284 -0
  200. data/pgpool2/pool_relcache.h +78 -0
  201. data/pgpool2/pool_rewrite_outfuncs.c +9060 -0
  202. data/pgpool2/pool_rewrite_query.c +715 -0
  203. data/pgpool2/pool_rewrite_query.h +192 -0
  204. data/pgpool2/pool_select_walker.c +1150 -0
  205. data/pgpool2/pool_select_walker.h +68 -0
  206. data/pgpool2/pool_sema.c +161 -0
  207. data/pgpool2/pool_session_context.c +952 -0
  208. data/pgpool2/pool_session_context.h +203 -0
  209. data/pgpool2/pool_shmem.c +185 -0
  210. data/pgpool2/pool_signal.c +158 -0
  211. data/pgpool2/pool_signal.h +61 -0
  212. data/pgpool2/pool_ssl.c +339 -0
  213. data/pgpool2/pool_stream.c +962 -0
  214. data/pgpool2/pool_stream.h +61 -0
  215. data/pgpool2/pool_system.c +659 -0
  216. data/pgpool2/pool_timestamp.c +1215 -0
  217. data/pgpool2/pool_timestamp.h +38 -0
  218. data/pgpool2/pool_type.h +171 -0
  219. data/pgpool2/pool_worker_child.c +384 -0
  220. data/pgpool2/ps_status.c +404 -0
  221. data/pgpool2/recovery.c +435 -0
  222. data/pgpool2/redhat/pgpool.conf.sample.patch +52 -0
  223. data/pgpool2/redhat/pgpool.init +201 -0
  224. data/pgpool2/redhat/pgpool.sysconfig +7 -0
  225. data/pgpool2/redhat/rpm_installer/basebackup-replication.sh +53 -0
  226. data/pgpool2/redhat/rpm_installer/basebackup-stream.sh +55 -0
  227. data/pgpool2/redhat/rpm_installer/config_for_script +17 -0
  228. data/pgpool2/redhat/rpm_installer/failover.sh +64 -0
  229. data/pgpool2/redhat/rpm_installer/getsources.sh +141 -0
  230. data/pgpool2/redhat/rpm_installer/install.sh +1363 -0
  231. data/pgpool2/redhat/rpm_installer/pgpool_recovery_pitr +47 -0
  232. data/pgpool2/redhat/rpm_installer/pgpool_remote_start +15 -0
  233. data/pgpool2/redhat/rpm_installer/recovery.conf +4 -0
  234. data/pgpool2/redhat/rpm_installer/uninstall.sh +57 -0
  235. data/pgpool2/sample/dist_def_pgbench.sql +73 -0
  236. data/pgpool2/sample/pgpool.pam +3 -0
  237. data/pgpool2/sample/pgpool_recovery +20 -0
  238. data/pgpool2/sample/pgpool_recovery_pitr +19 -0
  239. data/pgpool2/sample/pgpool_remote_start +13 -0
  240. data/pgpool2/sample/replicate_def_pgbench.sql +18 -0
  241. data/pgpool2/sql/insert_lock.sql +15 -0
  242. data/pgpool2/sql/pgpool-recovery/pgpool-recovery.c +280 -0
  243. data/pgpool2/sql/pgpool-recovery/pgpool-recovery.sql.in +19 -0
  244. data/pgpool2/sql/pgpool-recovery/pgpool_recovery--1.0.sql +24 -0
  245. data/pgpool2/sql/pgpool-recovery/pgpool_recovery.control +5 -0
  246. data/pgpool2/sql/pgpool-recovery/uninstall_pgpool-recovery.sql +3 -0
  247. data/pgpool2/sql/pgpool-regclass/pgpool-regclass.c +206 -0
  248. data/pgpool2/sql/pgpool-regclass/pgpool-regclass.sql.in +4 -0
  249. data/pgpool2/sql/pgpool-regclass/pgpool_regclass--1.0.sql +7 -0
  250. data/pgpool2/sql/pgpool-regclass/pgpool_regclass.control +5 -0
  251. data/pgpool2/sql/pgpool-regclass/uninstall_pgpool-regclass.sql +1 -0
  252. data/pgpool2/sql/system_db.sql +38 -0
  253. data/pgpool2/strlcpy.c +85 -0
  254. data/pgpool2/test/C/test_extended.c +98 -0
  255. data/pgpool2/test/jdbc/.cvsignore +2 -0
  256. data/pgpool2/test/jdbc/AutoCommitTest.java +45 -0
  257. data/pgpool2/test/jdbc/BatchTest.java +55 -0
  258. data/pgpool2/test/jdbc/ColumnTest.java +60 -0
  259. data/pgpool2/test/jdbc/CreateTempTableTest.java +48 -0
  260. data/pgpool2/test/jdbc/InsertTest.java +34 -0
  261. data/pgpool2/test/jdbc/LockTest.java +36 -0
  262. data/pgpool2/test/jdbc/PgpoolTest.java +75 -0
  263. data/pgpool2/test/jdbc/README.euc_jp +73 -0
  264. data/pgpool2/test/jdbc/RunTest.java +83 -0
  265. data/pgpool2/test/jdbc/SelectTest.java +37 -0
  266. data/pgpool2/test/jdbc/UpdateTest.java +32 -0
  267. data/pgpool2/test/jdbc/expected/CreateTempTable +1 -0
  268. data/pgpool2/test/jdbc/expected/autocommit +10 -0
  269. data/pgpool2/test/jdbc/expected/batch +1 -0
  270. data/pgpool2/test/jdbc/expected/column +100 -0
  271. data/pgpool2/test/jdbc/expected/insert +1 -0
  272. data/pgpool2/test/jdbc/expected/lock +100 -0
  273. data/pgpool2/test/jdbc/expected/select +2 -0
  274. data/pgpool2/test/jdbc/expected/update +1 -0
  275. data/pgpool2/test/jdbc/pgpool.properties +7 -0
  276. data/pgpool2/test/jdbc/prepare.sql +54 -0
  277. data/pgpool2/test/jdbc/run.sh +6 -0
  278. data/pgpool2/test/parser/.cvsignore +6 -0
  279. data/pgpool2/test/parser/README +32 -0
  280. data/pgpool2/test/parser/expected/copy.out +17 -0
  281. data/pgpool2/test/parser/expected/create.out +64 -0
  282. data/pgpool2/test/parser/expected/cursor.out +37 -0
  283. data/pgpool2/test/parser/expected/delete.out +10 -0
  284. data/pgpool2/test/parser/expected/drop.out +12 -0
  285. data/pgpool2/test/parser/expected/insert.out +13 -0
  286. data/pgpool2/test/parser/expected/misc.out +28 -0
  287. data/pgpool2/test/parser/expected/prepare.out +4 -0
  288. data/pgpool2/test/parser/expected/privileges.out +31 -0
  289. data/pgpool2/test/parser/expected/scanner.out +30 -0
  290. data/pgpool2/test/parser/expected/select.out +89 -0
  291. data/pgpool2/test/parser/expected/transaction.out +38 -0
  292. data/pgpool2/test/parser/expected/update.out +11 -0
  293. data/pgpool2/test/parser/expected/v84.out +37 -0
  294. data/pgpool2/test/parser/expected/v90.out +25 -0
  295. data/pgpool2/test/parser/expected/var.out +22 -0
  296. data/pgpool2/test/parser/input/alter.sql +2 -0
  297. data/pgpool2/test/parser/input/copy.sql +17 -0
  298. data/pgpool2/test/parser/input/create.sql +64 -0
  299. data/pgpool2/test/parser/input/cursor.sql +37 -0
  300. data/pgpool2/test/parser/input/delete.sql +10 -0
  301. data/pgpool2/test/parser/input/drop.sql +12 -0
  302. data/pgpool2/test/parser/input/insert.sql +13 -0
  303. data/pgpool2/test/parser/input/misc.sql +28 -0
  304. data/pgpool2/test/parser/input/prepare.sql +4 -0
  305. data/pgpool2/test/parser/input/privileges.sql +31 -0
  306. data/pgpool2/test/parser/input/scanner.sql +34 -0
  307. data/pgpool2/test/parser/input/select.sql +89 -0
  308. data/pgpool2/test/parser/input/transaction.sql +38 -0
  309. data/pgpool2/test/parser/input/update.sql +11 -0
  310. data/pgpool2/test/parser/input/v84.sql +37 -0
  311. data/pgpool2/test/parser/input/v90.sql +38 -0
  312. data/pgpool2/test/parser/input/var.sql +22 -0
  313. data/pgpool2/test/parser/main.c +96 -0
  314. data/pgpool2/test/parser/parse_schedule +16 -0
  315. data/pgpool2/test/parser/pool.h +13 -0
  316. data/pgpool2/test/parser/run-test +62 -0
  317. data/pgpool2/test/pdo-test/README.euc_jp +58 -0
  318. data/pgpool2/test/pdo-test/SQLlist/test1.sql +3 -0
  319. data/pgpool2/test/pdo-test/SQLlist/test2.sql +3 -0
  320. data/pgpool2/test/pdo-test/collections.inc +11 -0
  321. data/pgpool2/test/pdo-test/def.inc +7 -0
  322. data/pgpool2/test/pdo-test/log.txt +0 -0
  323. data/pgpool2/test/pdo-test/mod/database.inc +36 -0
  324. data/pgpool2/test/pdo-test/mod/def.inc +0 -0
  325. data/pgpool2/test/pdo-test/mod/errorhandler.inc +27 -0
  326. data/pgpool2/test/pdo-test/pdotest.php +11 -0
  327. data/pgpool2/test/pdo-test/regsql.inc +56 -0
  328. data/pgpool2/test/pgpool_setup +898 -0
  329. data/pgpool2/test/regression/README +39 -0
  330. data/pgpool2/test/regression/clean.sh +21 -0
  331. data/pgpool2/test/regression/libs.sh +16 -0
  332. data/pgpool2/test/regression/regress.sh +166 -0
  333. data/pgpool2/test/regression/tests/001.load_balance/test.sh +128 -0
  334. data/pgpool2/test/regression/tests/002.native_replication/PgTester.java +47 -0
  335. data/pgpool2/test/regression/tests/002.native_replication/create.sql +6 -0
  336. data/pgpool2/test/regression/tests/002.native_replication/test.sh +71 -0
  337. data/pgpool2/test/regression/tests/003.failover/expected.r +6 -0
  338. data/pgpool2/test/regression/tests/003.failover/expected.s +6 -0
  339. data/pgpool2/test/regression/tests/003.failover/test.sh +45 -0
  340. data/pgpool2/test/regression/tests/004.watchdog/master.conf +12 -0
  341. data/pgpool2/test/regression/tests/004.watchdog/standby.conf +19 -0
  342. data/pgpool2/test/regression/tests/004.watchdog/test.sh +52 -0
  343. data/pgpool2/test/regression/tests/050.bug58/test.sh +50 -0
  344. data/pgpool2/test/regression/tests/051.bug60/bug.sql +12 -0
  345. data/pgpool2/test/regression/tests/051.bug60/database-clean.sql +6 -0
  346. data/pgpool2/test/regression/tests/051.bug60/database-setup.sql +28 -0
  347. data/pgpool2/test/regression/tests/051.bug60/test.sh +79 -0
  348. data/pgpool2/test/regression/tests/052.do_query/test.sh +44 -0
  349. data/pgpool2/test/regression/tests/053.insert_lock_hangs/test.sh +81 -0
  350. data/pgpool2/test/regression/tests/054.postgres_fdw/test.sh +67 -0
  351. data/pgpool2/test/regression/tests/055.backend_all_down/test.sh +52 -0
  352. data/pgpool2/test/regression/tests/056.bug63/jdbctest2.java +66 -0
  353. data/pgpool2/test/regression/tests/056.bug63/test.sh +47 -0
  354. data/pgpool2/test/regression/tests/057.bug61/test.sh +40 -0
  355. data/pgpool2/test/regression/tests/058.bug68/jdbctest3.java +45 -0
  356. data/pgpool2/test/regression/tests/058.bug68/test.sh +47 -0
  357. data/pgpool2/test/timestamp/expected/insert.out +16 -0
  358. data/pgpool2/test/timestamp/expected/misc.out +3 -0
  359. data/pgpool2/test/timestamp/expected/update.out +6 -0
  360. data/pgpool2/test/timestamp/input/insert.sql +16 -0
  361. data/pgpool2/test/timestamp/input/misc.sql +3 -0
  362. data/pgpool2/test/timestamp/input/update.sql +6 -0
  363. data/pgpool2/test/timestamp/main.c +129 -0
  364. data/pgpool2/test/timestamp/parse_schedule +3 -0
  365. data/pgpool2/test/timestamp/run-test +69 -0
  366. data/pgpool2/version.h +1 -0
  367. data/pgpool2/watchdog/Makefile.am +17 -0
  368. data/pgpool2/watchdog/Makefile.in +505 -0
  369. data/pgpool2/watchdog/test/stab.c +266 -0
  370. data/pgpool2/watchdog/test/test.c +85 -0
  371. data/pgpool2/watchdog/test/wd_child_t.c +87 -0
  372. data/pgpool2/watchdog/test/wd_lifecheck_t.c +87 -0
  373. data/pgpool2/watchdog/test/wd_packet_t.c +87 -0
  374. data/pgpool2/watchdog/test/wd_ping_t.c +20 -0
  375. data/pgpool2/watchdog/watchdog.c +408 -0
  376. data/pgpool2/watchdog/watchdog.h +209 -0
  377. data/pgpool2/watchdog/wd_child.c +444 -0
  378. data/pgpool2/watchdog/wd_ext.h +123 -0
  379. data/pgpool2/watchdog/wd_heartbeat.c +577 -0
  380. data/pgpool2/watchdog/wd_if.c +216 -0
  381. data/pgpool2/watchdog/wd_init.c +126 -0
  382. data/pgpool2/watchdog/wd_interlock.c +347 -0
  383. data/pgpool2/watchdog/wd_lifecheck.c +512 -0
  384. data/pgpool2/watchdog/wd_list.c +429 -0
  385. data/pgpool2/watchdog/wd_packet.c +1159 -0
  386. data/pgpool2/watchdog/wd_ping.c +330 -0
  387. data/pgpool2/ylwrap +223 -0
  388. data/pgsql/presto_client.py +346 -0
  389. data/pgsql/prestogres.py +156 -0
  390. data/pgsql/setup_functions.sql +21 -0
  391. data/pgsql/setup_language.sql +3 -0
  392. data/prestogres.gemspec +23 -0
  393. metadata +496 -0
@@ -0,0 +1,17 @@
1
+ #! /bin/sh
2
+ # Recovery script for streaming replication.
3
+ # This script assumes that DB node 0 is primary, and 1 is standby.
4
+ #
5
+ datadir=$1
6
+ desthost=$2
7
+ destdir=$3
8
+
9
+ psql -c "SELECT pg_start_backup('Streaming Replication', true)" postgres
10
+
11
+ rsync -C -a --delete -e ssh --exclude postgresql.conf --exclude postmaster.pid \
12
+ --exclude postmaster.opts --exclude pg_log --exclude pg_xlog \
13
+ --exclude recovery.conf $datadir/ $desthost:$destdir/
14
+
15
+ ssh -T $desthost mv $destdir/recovery.done $destdir/recovery.conf
16
+
17
+ psql -c "SELECT pg_stop_backup()" postgres
@@ -0,0 +1,4220 @@
1
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
+ <html>
3
+ <head>
4
+ <meta http-equiv="content-type" content="text/html; charset=UTF-8">
5
+ <link rel="stylesheet" href="./pgpool.css" type="text/css">
6
+ <title>pgpool-II Benutzerhandbuch</title>
7
+ </head>
8
+
9
+ <!-- hhmts start -->
10
+ Last modified: Wed, 24 Aug 2011 10:38:20 +0200
11
+ <!-- hhmts end -->
12
+
13
+
14
+ <!-- translated from pgpool-en.html revision 1.86 -->
15
+
16
+ <body bgcolor="#ffffff">
17
+ <a name="top"></a>
18
+ <table border="0" cellpadding="2" cellspacing="1">
19
+ <tr>
20
+
21
+ <td colspan="2" valign="top"><div class="header_text">Willkommen auf der pgpool-II Website</div></td>
22
+ </tr>
23
+ <tr>
24
+ <td valign="top" style="border-right:1px dotted #cccccc;">
25
+ <br />
26
+
27
+ <div id="navcontainer">
28
+ <ul id="navlist">
29
+ <li id="active"><a href="#Whatis" id="current">Was ist pgpool-II?</a></li>
30
+ <li><a href="#platform">Systemanforderungen</a></li>
31
+ <li><a href="#install">Installation von pgpool-II</a></li>
32
+ <li><a href="#config">Konfiguration von pgpool-II</a></li>
33
+ <li><a href="#common">Allgemeine Konfiguration</a></li>
34
+ <li><a href="#connection_pool_mode">Connection-Pool Modus</a></li>
35
+ <li><a href="#replication_mode">Replikations Modus</a></li>
36
+ <li><a href="#master_slave_mode">Master-Slave Modus</a></li>
37
+ <li><a href="#start">Starten und Stoppen von pgpool-II</a></li>
38
+ <li><a href="#reload">pgpool-II Konfiguration neu laden</a></li>
39
+ <li><a href="#show-commands">SHOW Kommandos</a></li>
40
+ <li><a href="#online-recovery">Online Recovery</a></li>
41
+ <li><a href="#troubleshooting">Fehlerbehebung</a></li>
42
+ <li><a href="#restriction">Beschränkungen</a></li>
43
+ <li><a href="#reference">Referenzen</a></li>
44
+ <li><a href="#internal">Interna</a></li>
45
+ </ul>
46
+ </div>
47
+ <br />
48
+
49
+ <div class="header_small" align="center">
50
+
51
+ [<a href="pgpool-ja.html">Japanese page</a>] </div><div class="header_small" align="center">
52
+
53
+ [<a href="pgpool-en.html">English page</a>] </div> </td>
54
+ <td valign="top" style="border-left:1px dotted #cccccc;">
55
+
56
+
57
+
58
+
59
+ <h1>Was ist pgpool-II?<a name="whatis"></a></h1>
60
+
61
+ <p>pgpool-II ist eine Middleware die sich zwischen den PostgreSQL-
62
+ Server und deren Clients schaltet. Es bietet folgende Funktionen:</p>
63
+
64
+ <p>
65
+ <ul>
66
+
67
+ <li>Connection Pooling</li>
68
+ <p>pgpool-II verwaltet die Verbindungen zum PostgreSQL-Server und
69
+ hält bestehende Verbindungen aufrecht, um diese wiederverwenden zu
70
+ können. Einem Client, der eine Verbindung mit den selben
71
+ Eigenschaften (z.B. Benutzername, Datenbank, Protokollversion)
72
+ anfordert, kann so eine bereits bestehende Verbindung zugewiesen
73
+ werden. Dies reduziert den Overhead und verbessert den
74
+ Gesammtdurchsatz des Systems.</p>
75
+
76
+ <li>Replikation</li>
77
+ <p>pgpool-II kann mehrere PostgreSQL-Server Verwalten. Die
78
+ Replikationsfunktion erlaubt es ein Echtzeit-Backup auf 2 oder mehr
79
+ PostgreSQL-Knoten zu erstellen, so dass auch bei einem Ausfall eines
80
+ Knotens ein unterbrechungsfreier Betrieb gewährleistet werden
81
+ kann.</p>
82
+
83
+ <li>Lastverteilung</li>
84
+ <p>Bei einer replizierten Datenbank (sowohl im Replikations- wie
85
+ auch im Master/Slave Modus) wird eine Abfrage mit SELECT auf allen
86
+ Knoten dasselbe Resultat liefern. pgpool-II nutzt dies und verteilt
87
+ solche lesenden Anfragen gleichmässig auf die verfügbaren Knoten, um
88
+ den Durchsatz des gesammten Systems zu steigern. Im Idealfall skaliert
89
+ die Leistung für lesenden Zugriff proportional zur Anzahl der
90
+ verwalteten PostgreSQL-Knoten. Lastverteilung funktioniert also am
91
+ Besten mit vielen gleichzeitigen Nutzern, die meistens nur-lesende
92
+ Transaktionen ausführen.
93
+ </p>
94
+
95
+ <li>Verwaltung vieler gleichzeitiger Verbindungen</li>
96
+ <p>Bei PostgreSQL wird eine Beschränkung für die maximal
97
+ gleichzeitig möglichen Verbindungen konfiguriert. Sobald diese Grenze
98
+ erreicht ist, werden neue Verbindungen mit einem Fehler abgelehnt. Das
99
+ Anheben dieser Beschränkung führt zu erhöhtem Resourcenverbrauch und
100
+ verringert damit insgesammt die Systemleistung. Auch Pgpool-II hat
101
+ eine konfigurierbare Obergrenze für gleichzeitige Verbindungen,
102
+ weitere Verbindungen werden aber in eine Warteschlange gesetzt und
103
+ später, anstatt dass ein Fehler zurückgeliefert wird.
104
+
105
+ <li>Parallele-Abfragen (Parallel Querying)</li>
106
+ <p>Daten können beim Parallel Querying auf mehrere Server
107
+ aufgeteilt werden, so dass Anfragen auf mehreren Knoten parallel
108
+ ausgeführt werden können, um kürzere Antwortzeiten zu erreichen.
109
+ Parallele Abfragen sind gut geeignet für Suchanfragen auf grosse
110
+ Datenmengen.
111
+ </p>
112
+
113
+ </ul>
114
+ </p>
115
+
116
+ <p>pgpool-II spricht das Front- und Backend-Protokoll von PostgreSQL
117
+ und leitet Packete zwischen dem Backend und dem Frontend weiter.
118
+ Deshalb kann eine Datenbankanwendung (Frontend) pgpool-II genau wie
119
+ einen echten PostgreSQL-Server ansprechen. Umgekehrt ist pgpool-II für
120
+ den Server (Backend) einfach einer von vielen Nutzern. Weil pgpool-II
121
+ sowohl für den Server wie auch für den Client transparent ist, können
122
+ bestehende Datenbankanwendungen zusammen mit pgpool-II genutzt werden,
123
+ meist ohne Anpassungen an deren Quellcode.</p>
124
+
125
+ <p>
126
+ <strong>Es gibt einige Einschränkungen in der Verwendung von SQL via
127
+ pgpool-II. Siehe <a href="#restriction">Einschränkungen</a> für mehr
128
+ Informationen.</strong>
129
+ </p>
130
+
131
+ <h1>Systemanforderungen<a name="platform"></a></h1>
132
+
133
+ <p>pgpool-II läuft unter Linux, Solaris, FreeBSD sowie den
134
+ allermeisten UNIX-artigen Betriebssystemen. Windows wird nicht
135
+ unterstüzt. Alle Versionen von PostgreSQL ab 6.4 sind kompatibel zu
136
+ pgpool-II, für parallele Abfragen wird allerdings mindestens
137
+ PostgreSQL 7.4 vorausgesetzt.</p>
138
+
139
+ <p>Bei der Verwendung von PostgreSQL 7.3 und älter sind weitere
140
+ Funktionen nur eingeschränkt verfügbar, diese sollten aber sowieso
141
+ nicht mehr genutzt werden.</p>
142
+
143
+ <p>Auf allen PostgreSQL-Knoten sollte dieselbe Major-Version von
144
+ PostgreSQL verwendet werden. Desweiteren ist zu beachten, dass auch
145
+ die Architektur und das Betriebssystem identisch sein müssen, um
146
+ online recovery verwenden zu können.</p>
147
+
148
+ <h1>Installation von pgpool-II<a name="install"></a></h1>
149
+
150
+ <p>pgpool-II ist auf folgender Website
151
+ erhältlich: <a href="http://pgfoundry.org/projects/pgpool/">pgpool
152
+ Development page</a>. Installationsfertige Pakete stellen auch
153
+ verschiedene Distributitonen durch deren Paketverwaltung zur
154
+ Verfügung, z.B. CentOS, RedHat Enterprise Linux, Fedora und
155
+ Debian.</p>
156
+
157
+ <p>Der Quellcode von pgpool-II ist ebenfalls hier erhältlich:
158
+ <a href="http://pgfoundry.org/projects/pgpool/">pgpool development page</a>
159
+ </p>
160
+
161
+ <p>Zur Installation von pgpool-II aus dem Quellcode ist gcc (ab 2.9)
162
+ und GNU make erforderlich. Auch die libpq Bibliothek von PostgreSQL
163
+ inklusive Header-Dateien wird benötigt, die entsprechenden Packete
164
+ müssen also installiert sein, um pgpool-II kompilieren zu können. Zur
165
+ Unterstützung von SSL Verbindungen ist zusätzlich OpenSSL und dessen
166
+ Header Dateien nötig.</p>
167
+
168
+ <dl>
169
+ <dt>configure</dt>
170
+ <dd>
171
+ <p>
172
+ Nach dem Entpacken des Quellcodes ist folgendes Skript auszuführen:
173
+ <pre>
174
+ ./configure
175
+ </pre>
176
+
177
+ Folgende Optionen sind zusätzlich möglich:
178
+
179
+ <ul>
180
+ <li><code>--prefix=path</code><br/> pgpool-II wird unter diesem
181
+ Verzeichnis installiert. Standardeinstellung
182
+ ist: <code>/usr/local</code></li>
183
+ <li><code>--with-pgsql=path</code><br/> Das Verzeichnis worunter
184
+ PostgreSQLs Bibliotheken installiert wurden. Standardmässig wird
185
+ dieses mit <code>pg_config</code> automatisch ermittelt.</li>
186
+ <li><code>--with-openssl</code><br/>
187
+ Verlinkt pgpool-II mit OpenSSL, in der Voreinstellung deaktiviert.</li>
188
+ <li><code>--enable-sequence-lock</code><br/>
189
+ Nutzt den zu pgpool-II 3.0 (bis 3.0.4) kompatiblen insert_lock.
190
+ Damit sperrt (LOCK) pgpool-II die Sequenzrelation. PostgreSQL ab
191
+ Version 8.2 (veröffentlicht im Juni 2011) ist inkompatibel zu
192
+ dieser Variante.</li>
193
+ <li><code>--enable-table-lock</code> <br/>
194
+ Nutzt den zu pgpool-II 2.2 und 2.3 kompatiblen insert_lock.
195
+ Pgpool-II sperrt (LOCK) damit die Zieltabelle des INSERTs. Diese
196
+ Variante ist veraltet, da sie Konflikte mit VACUUM
197
+ verursacht.</li>
198
+ </ul>
199
+ </p>
200
+ </dd>
201
+
202
+ <dt>make</dt>
203
+ <dd>
204
+ <p>
205
+ <pre>
206
+ make
207
+ make install
208
+ </pre>
209
+ installiert pgpool-II. (Unter Solaris oder FreeBSD ist make mit gmake zu ersetzen)
210
+ </p>
211
+ </dd>
212
+
213
+ <dt>Installation von pgpool_regclass</dt>
214
+ <dd>
215
+ <p>
216
+ Bei der Nutzung von PostgreSQL 8.0 oder höher ist die Installation von
217
+ pgpool_regclass auf allen Knoten, die von pgpool-II genutzt werden
218
+ sollen sehr empfehlenswert. Deren Funktionen werden von pgpool-II
219
+ intern genutzt, um Duplikate bei Tabellennamen in verschiededen Schema
220
+ verhindern zu können.
221
+ </p>
222
+ <p>
223
+ <pre>
224
+ cd pgpool-II-x.x.x/sql/pgpool-regclass
225
+ make
226
+ make install
227
+ psql -f pgpool-regclass.sql template1
228
+ </pre>
229
+ </p>
230
+ <p>
231
+ Das Skript pgpool-regclass.sql sollte auf jeder mit pgpool-II
232
+ verwendeten Datenbank ausgeführt werden.
233
+
234
+ Bei der Installation in template1 wird pgpool-regclass beim Erstellen
235
+ einer neuen Datenbank automatisch kopiert. Für Datenbanken, die nach
236
+ der Ausführung von "psql -f pgpool-regclass.sql template1" generiert
237
+ werden ist also keine weitere Aktion erforderlich.
238
+ </p>
239
+
240
+
241
+ <dt>Creating insert_lock table</dt>
242
+ <dd>
243
+ <p>
244
+ If you use insert_lock in replication mode, creating pgpool_catalog.insert_lock
245
+ table for mutual exclusion is strongly recommended.
246
+ Without this, insert_lock works so far. However in that case pgpool-II locks
247
+ against the insert target table. This behavior is same as pgpool-II 2.2 and 2.3
248
+ series. The table lock conflicts with VACUUM. So INSERT processing may be thereby
249
+ kept waiting for a long time.
250
+ </p>
251
+ <p>
252
+ <pre>
253
+ cd pgpool-II-x.x.x/sql
254
+ psql -f insert_lock.sql template1
255
+ </pre>
256
+ </p>
257
+ <p>
258
+ Executing insert_lock.sql should be performed on every databases accessed
259
+ with pgpool-II.
260
+ You do not need to do this for a database created after the execution of
261
+ &quot;psql -f insert_lock.sql template1&quot;, as this template database will be
262
+ cloned to create new databases.
263
+ </p>
264
+
265
+ </dl>
266
+
267
+ <p>
268
+ Installing is done. If you are using Solaris or FreeBSD, you need to replace "make" with "gmake" in the above description because those operating systems requires GNU make.
269
+ </p>
270
+
271
+ <h1>Konfiguration von pgpool-II<a name="config"></a></h1>
272
+
273
+ <p>Beispielhafte Konfigurationsdateien für pgpool-II werden
274
+ standardmässig unter <code>/usr/local/etc/pgpool.conf</code>
275
+ und <code>/usr/local/etc/pcp.conf</code> installiert.
276
+
277
+ pgpool-II bietet mehrere Funktionsmodi. Jeder hat leicht
278
+ unterschiedliche Funktionen, die an- oder ausgeschaltet und teils mit
279
+ spezifischen Parametern angepasst werden können.</p>
280
+
281
+ <table border>
282
+
283
+ <tr>
284
+ <th>Function/Mode</th>
285
+ <th>Basis Modus (*3)</th>
286
+ <th>Replikations Modus</th>
287
+ <th>Master-Slave Modus</th>
288
+ <th>Parallel Query Modus</th>
289
+ </tr>
290
+
291
+ <tr>
292
+ <td>Connection Pool</td>
293
+ <td align="center">X</td>
294
+ <td align="center">O</td>
295
+ <td align="center">O</td>
296
+ <td align="center">O</td>
297
+ </tr>
298
+
299
+ <tr>
300
+ <td>Replikation</td>
301
+ <td align="center">X</td>
302
+ <td align="center">O</td>
303
+ <td align="center">X</td>
304
+ <td align="center">(*1)</td>
305
+ </tr>
306
+
307
+ <tr>
308
+ <td>Lastverteilung</td>
309
+ <td align="center">X</td>
310
+ <td align="center">O</td>
311
+ <td align="center">O</td>
312
+ <td align="center">(*1)</td>
313
+ </tr>
314
+
315
+ <tr>
316
+ <td>Failover</td>
317
+ <td align="center">O</td>
318
+ <td align="center">O</td>
319
+ <td align="center">O</td>
320
+ <td align="center">X</td>
321
+ </tr>
322
+
323
+ <tr>
324
+ <td>Online Recovery</td>
325
+ <td align="center">X</td>
326
+ <td align="center">0</td>
327
+ <td align="center">(*2)</td>
328
+ <td align="center">X</td>
329
+ </tr>
330
+
331
+ <tr>
332
+ <td>Parallel Query</td>
333
+ <td align="center">X</td>
334
+ <td align="center">X</td>
335
+ <td align="center">X</td>
336
+ <td align="center">O</td>
337
+ </tr>
338
+
339
+ <tr>
340
+ <td>Mindestzahl Server</td>
341
+ <td align="center">1 oder mehr</td>
342
+ <td align="center">2 oder mehr</td>
343
+ <td align="center">2 oder mehr</td>
344
+ <td align="center">2 oder mehr</td>
345
+ </tr>
346
+
347
+ <tr>
348
+ <td>System DB erforderlich?</td>
349
+ <td align="center">no</td>
350
+ <td align="center">no</td>
351
+ <td align="center">no</td>
352
+ <td align="center">yes</td>
353
+ </tr>
354
+
355
+ </table>
356
+
357
+ <p>
358
+ <ul>
359
+ <li> O heisst verfügbar, X heisst nicht möglich
360
+ <li>(*1) Der Parallel Query Modus erfordert eine aktivierte
361
+ Replikation oder Lastverteilung, weder Replikation noch
362
+ Lastverteilung können jedoch für parallele Abfragen auf verteilten
363
+ Tabellen genutzt werden.
364
+ <li>(*2) Online Recovery kann zusammen nur zusammen mit Streaming
365
+ Replication genutzt werden.
366
+ <li>(*3) Anwendungen verbinden sich via pgpool-II mit der PostgreSQL
367
+ Datenbank. Dieser Modus ermöglicht Connection Pooling und damit mehr
368
+ parallele Verbindungen von anwendungsseite her, oder auch einfaches
369
+ Failover bei mehreren Servern.
370
+ </ul>
371
+ </p>
372
+
373
+ <h2>Konfiguration mit <code>pcp.conf</code></h2>
374
+
375
+ <p>pgpool-II bietet eine Schnittstelle zur Kontrolle, die es dem
376
+ Administrator ermöglicht, den Status von pgpool-II abzufragen sowie
377
+ ggf. einzelne pgpool-II Prozesse zu beenden. Die
378
+ Datei <code>pcp.conf</code> enthält den Benutzernamen sowie das
379
+ Passwort zur Authentifizierung bei dieser Schnittstelle. Alle
380
+ Betriebsmodi erfordern entsprechenden Einstellungen in der
381
+ Datei <code>pcp.conf</code>. Die
382
+ Beispieldatei <code>$prefix/etc/pcp.conf.sample</code> wird während
383
+ der Installation von pgpool-II angelegt. Bitte benennen Sie diese
384
+ Datei in <code>pcp.conf</code> um und fügen Sie ihren Benutzername und
385
+ ein Passwort hinzu.
386
+ </p>
387
+
388
+ <pre>
389
+ cp $prefix/etc/pcp.conf.sample $prefix/etc/pcp.conf
390
+ </pre>
391
+
392
+ <p>
393
+ Weitere Beispielkonfigurationen sind für jeden Modus verfügbar.
394
+ </p>
395
+ <p>
396
+ <table border>
397
+ <tr>
398
+ <th>Modus</th>
399
+ <th>Beispieldatei</th>
400
+ </tr>
401
+
402
+ <tr>
403
+ <td>Replikations Modus</td>
404
+ <td>pgpool.conf.sample-replication</td>
405
+ </tr>
406
+
407
+ <tr>
408
+ <td>Master/Slave Modus (Slony-I)</td>
409
+ <td>pgpool.conf.sample-master-slave</td>
410
+ </tr>
411
+
412
+ <tr>
413
+ <td>Master/Slave Modus (Streaming replication)</td>
414
+ <td>pgpool.conf.sample-stream</td>
415
+ </tr>
416
+ </table>
417
+
418
+ <p>
419
+ Leerzeilen wie auch Zeilen, die mit "<code>#</code>" beginnen werden
420
+ als Kommentare behandelt und ignoriert. Der Benutzername und das
421
+ zugehörige Passwort müssen auf einer Zeile stehen und folgendes Format
422
+ befolgen:
423
+ </p>
424
+ <pre>
425
+ Nutzername:[md5 hash des Passwortes]
426
+ </pre>
427
+ <p>
428
+ Der <code>[md5 hash des Passwortes]</code> kann mit Hilfe des
429
+ Programs <code>$prefix/bin/pg_md5</code> ermittelt werden.
430
+ </p>
431
+
432
+ <pre>
433
+ pg_md5 -p
434
+ password: &lt;your password&gt;
435
+ </pre>
436
+ <p>
437
+ oder:
438
+ </p>
439
+ <pre>
440
+ ./pg_md5 foo
441
+ acbd18db4cc2f85cedef654fccc4a4d8
442
+ </pre>
443
+ <p>
444
+ Die Datei <code>pcp.conf</code> muss für den Nutzer der pgpool-II ausführt lesbar sein.</p>
445
+
446
+ <h2>Konfiguration mit <code>pgpool.conf</code></h2>
447
+
448
+ <p>Wie bereits beschrieben erfordert jeder Betriebsmodus seine eigenen
449
+ Konfigurationsparameter in <code>pgpool.conf</code>. Auch dafür legt
450
+ pgpool-II während der Installation eine Beispieldatei an. Kopieren Sie
451
+ die Beispieldatei von <code>$prefix/etc/pgpool.conf.sample</code>
452
+ in <code>pgpool.conf</code> um und bearbeiten Sie dessen Inhalt.
453
+
454
+ <pre>
455
+ cp $prefix/etc/pgpool.conf.sample $prefix/etc/pgpool.conf
456
+ </pre>
457
+ <p>
458
+ Leerzeilen wie auch Zeilen, die mit "<code>#</code>" beginnen werden
459
+ als Kommentare behandelt und ignoriert.</p>
460
+ </p>
461
+ <h3><a name="common"></a>Allgemeine Konfiguration</h3>
462
+
463
+ <dl>
464
+ <dt><a name="LISTEN_ADDRESS"></a>listen_addresses</dt>
465
+ <dd>
466
+ <p>Gibt den Hostnamen oder die IP Adresse an, über welche
467
+ pgpool-II TCP/IP Verbindungen annehmen soll. <code>'*'</code>
468
+ steht für alle Interfaces. <code>''</code> blockiert TCP/IP
469
+ Verbindungen. Standardwert
470
+ ist <code>'localhost'</code>. Verbindungen via UNIX Domain
471
+ Sockets werde immer akzeptiert. Dieser Parameter kann nur beim
472
+ Serverstart gesetzt werden.</p>
473
+ </dd>
474
+
475
+ <dt><a name="PORT"></a>port</dt>
476
+ <dd>
477
+ <p>Die Portnummer die pgpool-II nutzen soll, um Verbindungen zu
478
+ akzeptieren. Standardwert ist 9999. Dieser Parameter kann nur
479
+ beim Serverstart gesetzt werden.</p>
480
+ </dd>
481
+
482
+ <dt><a name="SOCKET_DIR"></a>socket_dir</dt>
483
+ <dd>
484
+ <p>Das Verzeichnis in welchem das UNIX Domain Socket für
485
+ pgpool-II angelegt werden soll. Standardwert
486
+ ist <code>'/tmp'</code>. Bitte bedenken Sie, dass dieses
487
+ Verzeichnis durch Cron Jobs regelmässig gelöscht werden
488
+ könnte. Es wird deshalb empfohlen, das Socket unter einem
489
+ anderen Verzeichnis, wie z.B. <code>'/var/run'</code>
490
+ anzulegen. Dieser Parameter kann nur beim Serverstart gesetzt
491
+ werden.</p>
492
+ </dd>
493
+
494
+ <dt><a name="PCP_PORT"></a>pcp_port</dt>
495
+ <dd>
496
+ <p>Die Portnummer auf welcher der PCP Prozess Verbindungen
497
+ annehmen soll. Standardwert ist 9998. Dieser Parameter kann nur
498
+ beim Serverstart gesetzt werden.</p>
499
+ </dd>
500
+
501
+ <dt><a name="PCP_SOCKET_DIR"></a>pcp_socket_dir</dt>
502
+ <dd>
503
+ <p>Das Verzeichnis in welchem das UNIX Domain Socket für den PCP
504
+ Prozess angelegt werden soll. Standardwert
505
+ ist <code>'/tmp'</code>. Bitte bedenken Sie, dass dieses
506
+ Verzeichnis durch Cron Jobs regelmässig gelöscht werden
507
+ könnte. Es wird deshalb empfohlen, das Socket unter einem
508
+ anderen Verzeichnis, wie z.B. <code>'/var/run'</code>
509
+ anzulegen. Dieser Parameter kann nur beim Serverstart gesetzt
510
+ werden.</p>
511
+ </dd>
512
+
513
+ <dt><a name="BACKEND_SOCKET_DIR"></a>backend_socket_dir</dt>
514
+ <dd>
515
+ <font color="red"><em>VERALTET</em><br> Dieser Parameter ist
516
+ veraltet und sollte nicht mehr verwendet werden. Nutzen Sie
517
+ stattdessen backend_hostname.
518
+ </font>
519
+ <p>Das Verzeichnis in welchem PostgreSQL sein UNIX Domain Socket
520
+ anlegt. Standardeinstellung war <code>'/tmp'</code>. Dieser
521
+ Parameter kann nur beim Serverstart gesetzt werden.</p>
522
+ </dd>
523
+
524
+ <dt><a name="PCP_TIMEOUT"></a>pcp_timeout</dt>
525
+ <dd>
526
+ <p>Das Timeout für PCP Verbindungen in Sekunden. Sollte ein
527
+ Nutzer innert dieser Frist nicht Antworten, so schliesst der PCP
528
+ Prozess die Verbindung. Standardwert ist 10 Sekunden. 0
529
+ deaktiviert diese Funktion. Kann durch erneutes Laden der
530
+ Konfiguration verändert werden.</p>
531
+ </dd>
532
+
533
+ <dt><a name="NUM_INIT_CHILDREN"></a>num_init_children</dt>
534
+ <dd>
535
+ <p>Anzahl der pgpool-II Serverprozesse, die bereit gehalten
536
+ werden sollen (prefork). Standardwert ist 32. num_init_children
537
+ ist auch die Obergrenze für die Anzahl gleichzeitiger
538
+ Verbindungen von Anwendungen zu pgpool-II. Sollten mehr als
539
+ num_init_children Anwendungen versuchen eine Verbindung zu
540
+ pgpool-II aufzubauen, so werden diese blockiert (nicht
541
+ abgewiesen), bis eine bestehende Verbindung zu einem pgpool-II
542
+ Prozess freigegeben wird. Maximal 2 * num_init_children
543
+ Verbindungsanfragen werden gepuffert. Die Anzahl Verbindungen
544
+ zu jeder Instanz von PostgreSQL ist ungefähr
545
+ max_pool*num_init_children</p>
546
+
547
+ <p>Weitere Tipps zum obigen Parameter:</p>
548
+ <p>
549
+ <ul>
550
+ <li>Das Abbrechen einer Transaktion erfordert eine weitere,
551
+ separate Verbindung zum Backend (PostgreSQL Server). Deshalb
552
+ können Transaktionen nicht abgebrochen werden, solange alle
553
+ Prozesse beschäftigt sind. Um sicher zu gehen, dass
554
+ Transaktionen abgebrochen werden können, ist dieser Parameter
555
+ auf den doppelten Wert der zu erwartenden Anzahl
556
+ gleichzeitiger Verbindungen zu setzen.</li>
557
+
558
+ <li>Bedenken Sie auch, dass PostgreSQL nur bis zu
559
+ (max_connections - superuser_reserved_connections)
560
+ gleichzeitige Verbindungen von einfachen Nutzern erlaubt
561
+ (nicht Superuser).</li>
562
+ </ul>
563
+ </p>
564
+ <p>Die Parameter max_pool, num_init_children, max_connections
565
+ und superuser_reserved_connections sollten folgende Bedingungen
566
+ erfüllen:
567
+ </p>
568
+ <p>
569
+ <pre>
570
+ max_pool*num_init_children <= (max_connections - superuser_reserved_connections) (kein Abbrechen von Transaktionen)
571
+ max_pool*num_init_children*2 <= (max_connections - superuser_reserved_connections) (Abbrechen von Transaktionen erfordert)
572
+ </pre>
573
+ <p>Dieser Parameter kann nur beim Serverstart gesetzt werden.</p>
574
+ </dd>
575
+
576
+ <dt><a name="CHILD_LIFE_TIME"></a>child_life_time</dt>
577
+ <dd>
578
+ <p>Die Lebensdauer eines pgpool-II Prozesses in Sekunden. Ein
579
+ Kindprozess, der für über diese Dauer hinaus im Leerlauf bleibt,
580
+ wird beendet um einen neuen Kindprozess zu starten. Dieser
581
+ Parameter ermöglicht eine einfache Massnahme gegen Lecks im
582
+ Speicher (Memory Leaks) und ähnlichen Ressourcen. Der
583
+ Standardwert ist 300 (5 Minuten). 0 staltet diese Funktion
584
+ ab. Diese Funktion wird nicht auch Kindprozesse angewandt, die
585
+ bisher noch keine Verbindung akzeptiert haben. Kann durch
586
+ erneutes Laden der Konfiguration verändert werden.
587
+ </p>
588
+ </dd>
589
+
590
+ <dt><a name="CHILD_MAX_CONNECTIONS"></a>child_max_connections</dt>
591
+ <dd>
592
+ <p>Anzahl Verbindungen, nach denen ein pgpool-II Kindprozess
593
+ beendet wird. Dieser Parameter ist nützlich bei so grosser Last,
594
+ dass weder child_life_time noch connection_life_time je
595
+ greiffen. Diese Option kann also ebenfalls hilfreich sein um
596
+ Überlastung der PostgreSQL server vorzubeugen. Sie kann durch
597
+ erneutes Laden der Konfiguration verändert werden.
598
+ </p>
599
+ </dd>
600
+
601
+ <dt><a name="CLIENT_IDLE_LIMIT"></a>client_idle_limit
602
+ <dd>
603
+ <p>Die Verbindung zum Nutzer von pgpool-II wird nach
604
+ client_idle_limit Sekunden des Leerlaufes seit der letzten Anfrage
605
+ getrennt. Dies verhindert, dass ein Kindprozess über längere Zeit
606
+ blockiert wird, obwohl der Nutzer die TCP/IP Verbindung zu pgpool-II
607
+ schon beendet hat. Der Standardwert für diesen Parameter ist 0, was
608
+ diese Funktion deaktiviert. Dieser Parameter wird in der zweiten
609
+ Phase von Online Recovery ignoriert. Kann durch erneutes Laden der
610
+ Konfiguration verändert werden.</p>
611
+
612
+ <dt><a name="AUTHENTICATION_TIMEOUT"></a>authentication_timeout
613
+ <dd>
614
+ <p>Spezifiziert eine Zeitbeschränkung für die Authentifizierung. Der
615
+ Standardwert ist 60. Kann durch erneutes Laden der Konfiguration
616
+ verändert werden.</p>
617
+
618
+ <dt><a name="LOGDIR"></a>logdir</dt>
619
+ <dd>
620
+ <p>Die Datei pgpool_status wird in dieses Verzeichnis
621
+ geschrieben.</p>
622
+ </dd>
623
+
624
+ <dt><a name="LOG_DESTINATION"></a>log_destination</dt>
625
+ <dd>
626
+ <p>pgpool-II unterstützt mehrere Methoden für das Logging von
627
+ Servermeldungen, unter anderem stderr und syslog. Standardmässig
628
+ wird nach stderr geschrieben.
629
+ </p>
630
+ <p>Achtung: die Konfiguration des syslog Daemons muss angepasst
631
+ werden, damit das Logging via syslog funktioniert. pgpool-II
632
+ kann die Syslog-Prioritäten von LOCAL0 bis LOCAL7 nutzen (siehe
633
+ syslog_facility), mit Standardeinstellungen werden die meisten
634
+ Platformen solche Meldungen jedoch ignorieren. Eine Zeile wie
635
+ die folgende muss zur Konfiguration des Syslog-Services zugefügt
636
+ werden:
637
+ </p>
638
+ <pre>
639
+ local0.* /var/log/pgpool.log
640
+ </pre>
641
+ </dd>
642
+
643
+ <dt><a name="SYSLOG_FACILITY"></a>syslog_facility</dt>
644
+ <dd>
645
+ <p>Ist das Logging via Syslog erwünscht, so gibt dieser
646
+ Parameter die von pgpool-II zu nutzende Priorität ("facility")
647
+ an. Mögliche Werte sind: LOCAL0, LOCAL1, LOCAL2, LOCAL3, LOCAL4,
648
+ LOCAL5, LOCAL6, LOCAL7; Standardwert ist LOCAL0. Lesen Sie bitte
649
+ auch die Dokumentation zu ihrem Syslog-Service.
650
+ </p>
651
+ </dd>
652
+
653
+ <dt><a name="SYSLOG_IDENT"></a>syslog_ident</dt>
654
+ <dd>
655
+ <p>Ist das Logging via Syslog erwünscht, so gibt dieser
656
+ Parameter den Programmnamen an, den pgpool-II zur Identifikation
657
+ nutzen soll. Standardwert ist <code>'pgpool'</code>.
658
+ </p>
659
+ </dd>
660
+
661
+ <dt><a name="PID_FILE_NAME"></a>pid_file_name</dt>
662
+ <dd>
663
+ <p>Voller Pfad zur Datei, in welche pgpool die Prozess-Id
664
+ schreiben soll. Standardwert
665
+ ist <code>'/var/run/pgpool/pgpool.pid'</code>. Ein Neustart von
666
+ pgpool ist erforderlich, um diesen Parameter zu ändern.
667
+ </p>
668
+ </dd>
669
+
670
+ <dt><a name="PRINT_TIMESTAMP"></a>print_timestamp</dt>
671
+ <dd>
672
+ <p>Ob pgpool-II zu jedem Log-Eintrag einen Zeitstempel schreiben
673
+ soll. Standardwert ist 'true' (ja). Kann durch erneutes Laden
674
+ der Konfiguration verändert werden.
675
+ </p>
676
+ </dd>
677
+
678
+ <dt><a name="CONNECTION_CACHE"></a>connection_cache</dt>
679
+ <dd>
680
+ <p>Ob pgpool-II Verbindungen im Cache behalten
681
+ soll. Standardwert ist 'true' (ja). Ein Neustart ist
682
+ erforderlich, damit eine Änderung dieser Option wirksam wird.
683
+ </p>
684
+ </dd>
685
+
686
+ <dt><a name="HEALTH_CHECK_TIMEOUT"></a>health_check_timeout</dt>
687
+ <dd>
688
+ <p>pgpool-II prüft regelmässig die Verbindungen zu den
689
+ PostgreSQL-Backends, um Fehler auf den Datenbankservern oder im
690
+ Netzwerk entdecken zu können (Verbindungsprüfung). Wird ein
691
+ Fehler entdeckt, so versucht pgpool-II auf einen anderen Server
692
+ zu wechseln ("failover") oder fährt im degenerierten Modus fort.
693
+
694
+ Dieser Parameter verhindert zu lange Wartezeiten für diese
695
+ Prüfroutine in Fällen wie einem abgezogenen Netzkabel. Das
696
+ Zeitlimit wird in Sekunden angegeben. Der Standardwert ist
697
+ 20. Der Wert 0 deaktiviert diese Funktion (wodurch pgpool-II bis
698
+ zum Timeout der TCP/IP Verbindung wartet).
699
+
700
+ Diese Verbindungsprüfung erfordert eine zusätzliche Verbindung
701
+ zu jedem PostgreSQL-Knoten, weshalb <code>max_connections</code>
702
+ in <code>postgresql.conf</code> entsprechend angepasst werden
703
+ sollte.
704
+
705
+ Kann durch erneutes Laden der Konfiguration verändert werden.
706
+ </p>
707
+ </dd>
708
+
709
+ <dt><a name="HEALTH_CHECK_PERIOD"></a>health_check_period</dt>
710
+ <dd>
711
+ <p>Gibt das Interval zwischen den Verbindungsprüfungen in
712
+ Sekunden an. Standardwert ist 0, was die Verbindungsprüfung
713
+ deaktiviert. Kann durch erneutes Laden der Konfiguration
714
+ verändert werden.
715
+ </p>
716
+ </dd>
717
+
718
+ <dt><a name="HEALTH_CHECK_USER"></a>health_check_user</dt>
719
+ <dd>
720
+ <p>Der Benutzername mit welchem die Verbindungsprüfung
721
+ vorgenommen wird. Dieser Benutzer muss auf allen
722
+ PostgreSQL-Knoten existieren, anderenfalls schlägt die
723
+ Verbindungsprüfung fehl. Kann durch erneutes Laden der
724
+ Konfiguration verändert werden.
725
+ </p>
726
+ </dd>
727
+
728
+ <dt><a name="HEALTH_CHECK_PASSWORD"></a>health_check_password</dt>
729
+ <dd>
730
+ <p>Das Passwort zum Nutzer mit welchem die Verbindungsprüfung
731
+ vorgenommen wird. Kann durch erneutes Laden der Konfiguration
732
+ verändert werden.
733
+ </p>
734
+ </dd>
735
+
736
+ <dt><a name="FAILOVER_COMMAND"></a>failover_command
737
+ <dd>
738
+ <p>
739
+ Spezifiziert einen Befehl, der ausgeführt wird, wenn ein Knoten vom
740
+ Cluster getrennt wird. pgpool-II ersetzt die folgenden Spezialzeichen:
741
+ </p>
742
+
743
+ <blockquote>
744
+ <table border>
745
+ <tr><td>Spezialzeichen</td><td>Beschreibung</td></tr>
746
+ <tr><td>%d</td><td>Backend ID des getrennten Knotens</td></tr>
747
+ <tr><td>%h</td><td>Hostname des getrennten Knotens</td></tr>
748
+ <tr><td>%p</td><td>Portnummer des getrennten Knotens</td></tr>
749
+ <tr><td>%D</td><td>Database Cluster Verzeichnis des getrennten Knotens</td></tr>
750
+ <tr><td>%M</td><td>Id des bisherigen Master-Knotens</td></tr>
751
+ <tr><td>%m</td><td>Id des neuen Master-Knotens</td></tr>
752
+ <tr><td>%H</td><td>Hostname des neuen Master-Knotens</td></tr>
753
+ <tr><td>%P</td><td>Id des bisherigen primären Knotens</td></tr>
754
+ <tr><td>%%</td><td>'%'-Zeichen</td></tr>
755
+ </table>
756
+ </blockquote>
757
+ <p>
758
+ Kann durch erneutes Laden der Konfiguration verändert werden.
759
+ </p>
760
+
761
+ <p>
762
+ Bei einem Failover beendet pgpool-II alle Kindprozesse, was in Folge
763
+ auch alle aktiven Sitzungen von Nutzern von pgpool-II beendet. Danach
764
+ startet pgpool das Kommando in <code>failover_command</code> und
765
+ wartet auf dessen vollständige Abarbeitung. Erst dann startet
766
+ pgpool-II wieder neue Kindprozesse und ist damit wieder bereit
767
+ Verbindungen von Nutzern zu akzeptieren.
768
+ </p>
769
+
770
+ <dt><a name="FAILBACK_COMMAND"></a>failback_command
771
+ <dd>
772
+ <p>
773
+ Spezifiziert einen Befehl, der ausgeführt wird, wenn ein Knoten zum
774
+ Cluster hinzugefügt wird. pgpool-II ersetzt die folgenden
775
+ Spezialzeichen:
776
+ </p>
777
+ <blockquote>
778
+ <table border>
779
+ <tr><td>Spezialzeichen</td><td>Beschreibung</td></tr>
780
+ <tr><td>%d</td><td>Backend ID des hinzugefügten Knotens</td></tr>
781
+ <tr><td>%h</td><td>Hostname des hinzugefügten Knotens</td></tr>
782
+ <tr><td>%p</td><td>Portnummer des hinzugefügten Knotens</td></tr>
783
+ <tr><td>%D</td><td>Database Cluster Verzeichnis des hinzugefügten Knotens</td></tr>
784
+ <tr><td>%M</td><td>Id des bisherigen Master-Knotens</td></tr>
785
+ <tr><td>%m</td><td>Id des neuen Master-Knotens</td></tr>
786
+ <tr><td>%H</td><td>Hostname des neuen Master-Knotens</td></tr>
787
+ <tr><td>%P</td><td>Id des bisherigen primären Knotens</td></tr>
788
+ <tr><td>%%</td><td>'%'-Zeichen</td></tr>
789
+ </table>
790
+ </blockquote>
791
+ <p>
792
+ Kann durch erneutes Laden der Konfiguration verändert werden.
793
+ </p>
794
+
795
+ <dt><a name="FOLLOW_MASTER_COMMAND"></a>follow_master_command</dt>
796
+ <dd>
797
+ <p>
798
+ Spezifiziert einen Befehl, der im Master/Slave Betrieb mit Streaming
799
+ Replication ausgeführt wird, wenn der Master ausfällt. Pgpool-II
800
+ ersetzt die folgenden Spezialzeichen:
801
+ </p>
802
+
803
+ <blockquote>
804
+ <table border>
805
+ <tr><td>Spezialzeichen</td><td>Beschreibung</td></tr>
806
+ <tr><td>%d</td><td>Backend ID des ausgefallenen Knotens.</td></tr>
807
+ <tr><td>%h</td><td>Hostname des ausgefallenen Knotens.</td></tr>
808
+ <tr><td>%p</td><td>Portnummer des ausgefallenen Knotens.</td></tr>
809
+ <tr><td>%D</td><td>Database Cluster Verzeichnis des ausgefallenen Knotens.</td></tr>
810
+ <tr><td>%M</td><td>Id des bisherigen Master-Knotens.</td></tr>
811
+ <tr><td>%m</td><td>Id des neuen Master-Knotens.</td></tr>
812
+ <tr><td>%H</td><td>Hostname des neuen Master-Knotens.</td></tr>
813
+ <tr><td>%P</td><td>Id des bisherign primären Knotens.</td></tr>
814
+ <tr><td>%%</td><td>'%'-Zeichen</td></tr>
815
+ </table>
816
+ </blockquote>
817
+ <p>
818
+ Kann durch erneutes Laden der Konfiguration verändert werden.
819
+ </p>
820
+
821
+ <p>
822
+ If follow_master_command is not empty, when a master failover is
823
+ completed in master/slave streaming replication, pgpool degenerate all
824
+ nodes excepted the new master and starts new child processes to be
825
+ ready again to accept connections from clients. After this, pgpool run
826
+ the command set into the 'follow_master_command' for each degenerated
827
+ nodes. Typically the command should be used to recover the slave from
828
+ the new master by call the pcp_recovery_node command for example.
829
+ </p>
830
+
831
+ <dt><a name="FAIL_OVER_ON_BACKEND_ERROR"></a>fail_over_on_backend_error</dt>
832
+ <dd>
833
+ <p>
834
+ Wenn auf 'true' gesetzt, so wird pgpool-II bei einem Fehler beim
835
+ Senden zu einem PostgreSQL-Knoten die Failover-Prozedur starten. Dies
836
+ entspricht dem Verhalten von pgpool-II 2.2.x und früher. Ist dieser
837
+ Parameter auf 'false' gesetzt, wird empfohlen die Verbindungsprüfung
838
+ (health check) einzuschalten.
839
+
840
+ Beim Dektivieren dieser Funktion ist zu bedenken, dass pgpool-II
841
+ trotzdem bei einem Fehler während des Verbindungsaufbaus zu einem
842
+ PostgreSQL-Knoten die Failover-Prozedur startet, z.B. auch im Falle
843
+ eines 'Administrative Shutdown' von PostgreSQL. Kann durch erneutes
844
+ Laden der Konfiguration verändert werden.
845
+ </p>
846
+ </dd>
847
+
848
+ <dt><a name="IGNORE_LEADING_WHITE_SPACE"></a>ignore_leading_white_space</dt>
849
+ <dd>
850
+ <p>Im Lastverteilungs-Modus ignoriert pgpool-II anführende
851
+ Leerzeichen vor einer SQL Abfrage. Dies ist speziell im
852
+ Zusammenhang mit APIs wie DBI/DBD:Pg nützlich, welche
853
+ Leerzeichen hinzufügen. Kann durch erneutes Laden der
854
+ Konfiguration verändert werden.
855
+ </p>
856
+ </dd>
857
+
858
+ <dt><a name="LOG_STATEMENT"></a>log_statement</dt>
859
+ <dd>
860
+ <p>Wenn auf 'true' gesetzt, so schreibt pgpool-II Log-Einträge
861
+ für SQL Abfragen, sehr ähnlich zum log_statement Parameter in
862
+ PostgreSQL selbst. Log-Einträge werden auch geschrieben, wenn
863
+ die debug Option von pgpool-II nicht aktiviert wurde. Kann durch
864
+ erneutes Laden der Konfiguration verändert werden.
865
+ </p>
866
+ </dd>
867
+
868
+ <dt><a name="LOG_PER_NODE_STATEMENT"></a>log_per_node_statement</dt>
869
+ <dd>
870
+ <p>Ähnlich wie der obige log_statement Parameter, schreibt aber
871
+ Log-Einträge für jeden Datenbank-Knoten separat. Dies kann
872
+ z.B. verwendet werden, um zu prüfen, ob die Daten korrekt
873
+ repliziert werden. Kann durch erneutes Laden der Konfiguration
874
+ verändert werden.</p>
875
+ </dd>
876
+
877
+ <dt><a name="LOG_HOSTNAME"></a>log_hostname</dt>
878
+ <dd>
879
+ <p>Ist dieser Parameter auf 'true' gesetzt, so zeigt das 'ps'
880
+ Kommando im Status den Hostnamen des aktuellen Clients, statt
881
+ dessen IP Adresse. Ist log_connections aktiviert, so schreibt
882
+ pgpool-II auch dort den Hostnamen. Kann durch erneutes Laden der
883
+ Konfiguration verändert werden.</p>
884
+ </dd>
885
+
886
+ <dt><a name="LOG_CONNECTIONS"></a>log_connections</dt>
887
+ <dd>
888
+ <p>Ist dieser Parameter auf 'true' gesetzt, so werden alle
889
+ einkommenden Verbindungen im Log registriert. Kann durch
890
+ erneutes Laden der Konfiguration verändert werden.
891
+ </p>
892
+ </dd>
893
+
894
+ <dt><a name="ENABLE_POOL_HBA"></a>enable_pool_hba</dt>
895
+ <dd>
896
+ <p>Gibt an, ob <code>pool_hba.conf</code> zur Authentifizierung
897
+ genutzt werden soll. Siehe <a href="#hba">Aufsetzen von
898
+ pool_hba.conf zur Authentifizierung</a>. Kann durch erneutes
899
+ Laden der Konfiguration verändert werden.</p>
900
+ </p>
901
+ </dd>
902
+
903
+ <dt><a name="BACKEND_HOSTNAME"></a>backend_hostname</dt>
904
+ <dd>
905
+ <p>Spezifiziert wie pgpool-II zum PostgreSQL-Server verbinden
906
+ soll. Dieser Parameter kann nur beim Start von pgpool-II gesetzt
907
+ werden.
908
+ </p>
909
+ <p>
910
+ Bei der Kommunikation via TCP/IP ist ein Hostnamen oder eine IP
911
+ Adresse anzugeben. Für die Verwendung von UNIX Domain Sockets
912
+ ist der Pfad des Verzeichnisses zur Socket-Datei anzugeben,
913
+ welcher zwingend mit einem Schrägstrich ('<code>/</code>')
914
+ beginnen muss. Der Standardwert ist leer (<code>''</code>) und
915
+ veranlasst pgpool-II ein UNIX Domain Socket
916
+ in </code>/tmp</code> zu verwenden.
917
+ </p>
918
+ <p>
919
+ Mehrere PostgreSQL-Server können durch eine zusätzliche Nummer
920
+ am Ende des Parameternamens spezifiziert werden
921
+ (z.B. <code>backend_hostname0</code>). Diese Nummer wird
922
+ "Knoten-Id" genannt und beginnt bei 0. Der Knoten mit der Id 0
923
+ heisst "Master-Db". Sind mehrere Datenbank-Server definiert,
924
+ dann kann pgpool-II in einigen Modi auch weiterarbeiten, falls
925
+ die Master-Db nicht erreichbar ist. In solchen Fällen wird der
926
+ Knoten mit der nachstgrösseren Id zur neuen Master-Db.</p>
927
+
928
+ <p>Achtung: die Id 0 hat keine spezielle Bedeutung im Modus mit
929
+ Streaming Replication. Stattdessen ist darauf zu achten,
930
+ welcher Knoten der primäre ist. Siehe
931
+ <a href="#stream">Streaming Replication</a> für weitere
932
+ Details.</p>
933
+
934
+ <p>Soll nur ein PostgreSQL-Server verwendet werden, dann sollte
935
+ <code>backend_hostname0</code> verwendet werden.</p>
936
+
937
+ <p>Zusätzliche Knoten können mit diesem Parameter durch ein
938
+ erneutes Laden der Konfiguration hinzugefügt werden. Bestehende
939
+ Knoten-Ids können aber nicht geändert werden, dies erfordert
940
+ einen Neustart von pgpool-II.
941
+ </p>
942
+ </dd>
943
+
944
+ <dt><a name="BACKEND_PORT"></a>backend_port</dt>
945
+ <dd>
946
+ <p>Gibt die Portnummer des PosgreSQL-Servers an. Mehrere Ports
947
+ können durch eine zusätzliche Nummer am Ende des Parameternamens
948
+ definiert werden (z.B. <code>backend_port0</code>). Um nur ein
949
+ Backend zu verwenden, ist <code>backend_port0</code> zu
950
+ verwenden.</p>
951
+
952
+ <p>Portnummern für zusätzliche Knoten können mit diesem
953
+ Parameter durch ein erneutes Laden der Konfiguration hinzugefügt
954
+ werden. Jene von bestehenden Knoten können aber nicht während
955
+ der Laufzeit verändert werden, dies erfordert einen Neustart von
956
+ pgpool-II.</p>
957
+ </dd>
958
+
959
+ <dt><a name="BACKEND_WEIGHT"></a>backend_weight</dt>
960
+ <dd>
961
+ <p>Gibt das Verhältnis der Lastverteilung an die Backends
962
+ an. Einzelne Gewichtungen für mehrere Backends können durch eine
963
+ Nummer am Ende des Parameters angegeben werden
964
+ (z.B. <code>backend_weight0</code>). Bei nur einem Knoten
965
+ (z.B. im Basis Modus) empfiehlt sich die Verwendung
966
+ von <code>backend_weight0</code> mit einem Wert von 1.0.</p>
967
+
968
+ <p>Gewichtungen für zusätzliche Knoten können mit diesem
969
+ Parameter durch ein erneutes Laden der Konfiguration hinzugefügt
970
+ werden. Das Ändern bestehender Werte erfordert einen
971
+ Neustart.</p>
972
+
973
+ <p>Seit pgpool-II 2.2.6/2.3 und neuer wird auch das Ändern
974
+ bestehender Werte unterstützt. Ein erneutes Laden der
975
+ Konfiguration beeinflusst alle neuen Verbindungen. Dies ist
976
+ speziell im Master/Slave Modus hilfreich, um zu verhindern, dass
977
+ ein Slave Anfragen kriegt, während auf diesem administrative
978
+ Arbeiten getätigt werden.</p>
979
+ </dd>
980
+
981
+ <dt><a name="BACKEND_DATA_DIRECTORY"></a>backend_data_directory</dt>
982
+ <dd>
983
+ <p>Gibt das PGDATA Verzeichnis der PostgreSQL Server an.
984
+ Mehrere Verzeichnisse können durch eine Nummer hinter dem
985
+ Parameter angegeben werden
986
+ (z.B. <code>backend_data_directory0</code>). Dieser Parameter
987
+ ist nur dann erforderlich, wenn Online Recovery genutzt werden
988
+ soll.</p>
989
+
990
+ <p>Dieser Parameter kann für neu hinzugefügte Knoten durch ein
991
+ erneutes Laden der Konfiguration angegeben werden. Um den Wert
992
+ für bestehende Knoten zu aktualisieren ist allerdings ein
993
+ Neustart von pgpool-II erforderlich.</p>
994
+ </dd>
995
+
996
+ <dt><a name="BACKEND_FLAG"></a>backend_flag</dt>
997
+ <dd>
998
+ <p>Controls various backend behavior.
999
+ Multiple backends can be specified by adding a number
1000
+ at the end of the parameter name
1001
+ (e.g. <code>backend_flag0</code>).
1002
+ </p>
1003
+ <p>
1004
+ Currently followings are allowed.
1005
+ Multiple falgs can be specified by using "|".
1006
+ </p>
1007
+ <dl>
1008
+ <dt>ALLOW_TO_FAILOVER</dt>
1009
+ <dd>
1010
+ Allow to failover or detaching backend.
1011
+ This is the default.
1012
+ You cannot specify with DISALLOW_TO_FAILOVER at a same time.
1013
+ </dd>
1014
+ <dt>DISALLOW_TO_FAILOVER</dt>
1015
+ <dd>
1016
+ Disallow to failover or detaching backend.
1017
+ This is usefull when you protect backend by using HA(High Availability) softwares
1018
+ such as Heartbeat or Pacemaker.
1019
+ You cannot specify with ALLOW_TO_FAILOVER at a same time.
1020
+ </dd>
1021
+ </dl>
1022
+ </dt>
1023
+
1024
+ <dt><a name="SSL">ssl</a></dt>
1025
+ <dd>
1026
+ <p>Wird ssl auf true gesetzt, so nutzt pgpool sowohl für die
1027
+ Front- wie auch die Backend-Verbindung SSL-Verschlüsselung.
1028
+ Auch <code>ssl_key</code> und und <code>ssl_cert</code> müssen
1029
+ gesetzt sein, damit SSL korrekt funktioniert.</p>
1030
+
1031
+ <p>SSL ist per Voreinstellung nicht aktiviert. Unterstützung
1032
+ für OpenSSL muss vor dem Kompilieren gewählt werden, wie im
1033
+ Abschnit zur <a href="#install">Installation</a>
1034
+ beschrieben.</p>
1035
+
1036
+ <p>Der pgpool-II service muss neu gestartet werden, um SSL
1037
+ Einstellungen zu verändern.</p>
1038
+ </dd>
1039
+
1040
+ <dt><a name="SSL_KEY"></a>ssl_key</dt>
1041
+ <dd>
1042
+ <p>Vollständiger Pfad zum privaten Schlüssel (private key) der
1043
+ für eingehende Verbindungen von den Frontends zu nutzen ist.</p>
1044
+
1045
+ <p>Diese Option hat keinen Standardwert. Falls nicht gesetzt
1046
+ wird SSL für eingehende Verbindungen deaktiviert.</p>
1047
+ </dd>
1048
+
1049
+ <dt><a name="SSL_CERT"></a>ssl_cert</dt>
1050
+ <dd>
1051
+ <p>Vollständiger Pfad zum öffentlichen x509 Zertifikat, das für
1052
+ eingehende Verbindungen von den Frontends zu nutzen ist.</p>
1053
+
1054
+ <p>Auch diese Option hat keinen Standardwert. Falls nicht
1055
+ gesetzt, wird SSL für eingehende Verbindungen deaktiviert.</p>
1056
+ </dd>
1057
+
1058
+ <dt><a name="DEBUG_LEVEL"></a>debug_level</dt>
1059
+ <dd>
1060
+ <p>
1061
+
1062
+
1063
+ Debug message verbosity level. 0 means no message, greater than 1
1064
+ means more verbose message. Default value is 0.
1065
+ </p>
1066
+ </dd>
1067
+
1068
+ <dt><a name="RELCACHE_EXPIRE"></a>relcache_expire</dt>
1069
+ <dd>
1070
+ <p>
1071
+ Life time of relation cache in seconds. 0 means no cache
1072
+ expiration(the default).
1073
+ The relation cache is used for cache the query result against PostgreSQL
1074
+ system catalog to obtain various information including table structures
1075
+ or if it's a temporary table or not. The cache is maintained in a pgpool
1076
+ child local memory and being kept as long as it survives.
1077
+ If someone modify the table by using ALTER TABLE or some such, the relcache
1078
+ is not consistent anymore.
1079
+ For this purpose, relcache_expiration controls the life time of the cache.
1080
+ </p>
1081
+ </dd>
1082
+ </dl>
1083
+ </dl>
1084
+
1085
+ <h4>Generating SSL certificates</h4>
1086
+ <p>
1087
+ Certificate handling is outside the scope of this document. The
1088
+ <a href="http://developer.postgresql.org/pgdocs/postgres/ssl-tcp.html">
1089
+ Secure TCP/IP Connections with SSL</a> page at postgresql.org has pointers
1090
+ with sample commands for how to generate self-signed certificates.
1091
+ </p>
1092
+
1093
+ <h4>Failover in the raw Mode</h4>
1094
+
1095
+ <p>Failover can be performed in raw mode if multiple servers are
1096
+ defined. pgpool-II usually accesses the backend specified by
1097
+ <code>backend_hostname0</code> during normal operation. If the
1098
+ backend_hostname0 fails for some reason, pgpool-II tries to access the
1099
+ backend specified by backend_hostname1. If that fails, pgpool-II tries
1100
+ the backend_hostname2, 3 and so on.</p>
1101
+
1102
+ <h3><a name="connection_pool_mode"></a>Connection Pool Mode</h3>
1103
+
1104
+ <p>In connection pool mode, all functions in raw mode and the
1105
+ connection pool function can be used.
1106
+ To enable this mode, you need to turn on "connection_cache".
1107
+ Following parameters take effect to connection pool.</p>
1108
+
1109
+ <dl>
1110
+ <dt><a name="MAX_POOL"></a>max_pool</dt>
1111
+ <dd>
1112
+ <p>The maximum number of cached connections in pgpool-II
1113
+ children processes. pgpool-II reuses the cached connection if an
1114
+ incoming connection is connecting to the same database with the
1115
+ same username. If not, pgpool-II creates a new connection to the
1116
+ backend. If the number of cached connections exceeds max_pool,
1117
+ the oldest connection will be discarded, and uses that slot for
1118
+ the new connection.
1119
+
1120
+ Default value is 4. Please be aware that the number of
1121
+ connections from pgpool-II processes to the backends may reach
1122
+ <code>num_init_children</code> * <code>max_pool</code>.
1123
+ This parameter can only be set at server start. </p>
1124
+ </dd>
1125
+
1126
+ <dt><a name="CONNECTION_LIFE_TIME"></a>connection_life_time</dt>
1127
+ <dd>
1128
+ <p>Cached connections expiration time in seconds. An expired
1129
+ cached connection will be disconnected. Default is 0, which
1130
+ means the cached connections will not be disconnected.</p>
1131
+ </dd>
1132
+
1133
+ <dt><a name="RESET_QUERY_LIST"></a>reset_query_list</dt>
1134
+ <dd>
1135
+ <p>Specifies the SQL commands sent to reset the connection
1136
+ to the backend when exiting a session. Multiple commands can be
1137
+ specified by delimiting each by ";". Default is
1138
+ the following, but can be changed to suit your system.
1139
+
1140
+ <pre>
1141
+ reset_query_list = 'ABORT; DISCARD ALL'
1142
+ </pre>
1143
+
1144
+ <p>
1145
+ Commands differ in each PostgreSQL versions. Here are the recommended settings.
1146
+ </p>
1147
+ <p>
1148
+ <table border>
1149
+ <tr><th>PostgreSQL version</th><th>reset_query_list value</th></tr>
1150
+ <tr><td>7.1 or before</td><td>ABORT</td></tr>
1151
+ <tr><td>7.2 to 8.2</td><td>ABORT; RESET ALL; SET SESSION AUTHORIZATION DEFAULT</td></tr>
1152
+ <tr><td>8.3 or later</td><td>ABORT; DISCARD ALL</td></tr>
1153
+ </table>
1154
+ </p>
1155
+ <ul>
1156
+ <li>"ABORT" is not issued when not in a transaction block for 7.4 or later.
1157
+ </ul>
1158
+
1159
+ <p>
1160
+ You need to reload pgpool.conf upon modification of this directive.
1161
+ </p>
1162
+ </dd>
1163
+ </dl>
1164
+
1165
+ <h4><p>Failover in the Connection Pool Mode</p></h4>
1166
+
1167
+ <p>Failover in the connection pool mode is the same as in the raw mode.</p>
1168
+
1169
+ <h3><a name="replication_mode"></a>Replication Mode</h3>
1170
+
1171
+ <p>This mode enables data replication between the backends. The
1172
+ configuration parameters below must be set in addition to everything above.</p>
1173
+
1174
+ <dl>
1175
+ <dt><a name="REPLICATION_MODE"></a>replication_mode</dt>
1176
+ <dd>
1177
+ <p>Setting to true enables replication mode. Default
1178
+ is false.</p>
1179
+ </dd>
1180
+
1181
+ <dt><a name="LOAD_BALANCE_MODE"></a>load_balance_mode</dt>
1182
+ <dd>
1183
+ <p>When set to true, SELECT queries will be
1184
+ distributed to each backend for load balancing. Default is
1185
+ false.</p>
1186
+ <p>This parameter can only be set at server start. </p>
1187
+ </dd>
1188
+
1189
+ <dt><a name="FAILOVER_IF_AFFECTED_TUPLES_MISMATCH"></a>failover_if_affected_tuples_mismatch</dt>
1190
+ <dd>
1191
+ <p>When set to true, if backends don't return the same number of affected
1192
+ tuples during an INSERT/UPDATE/DELETE,
1193
+ the backends that differ from most frequent result set are degenerated.
1194
+ If the frequencies are same, the group which includes master DB node(a DB node having the youngest node id) is remained and other groups are degenerated.
1195
+ </p>
1196
+ <p>
1197
+ If set to false, the session is terminated and the backends are not
1198
+ degenerated. Default is false.</p>
1199
+ </dd>
1200
+
1201
+ <dt><a name="REPLICATION_STOP_ON_MISMATCH"></a>replication_stop_on_mismatch</dt>
1202
+ <dd>
1203
+ <p>When set to true, if all backends don't return the same packet kind,
1204
+ the backends that differ from most
1205
+ frequent result set are degenerated. A typical use case is a SELECT
1206
+ statement being part of a transaction, replicate_select set to
1207
+ true, and SELECT returning a different number of rows among backends.
1208
+ Non-SELECT statements might trigger this though.
1209
+ For example, a backend succeeded in an UPDATE, while others
1210
+ failed.
1211
+ Note that pgpool does NOT examine the content of records
1212
+ returned by SELECT.
1213
+ If set to false, the session is terminated and the backends are not
1214
+ degenerated. Default is false.</p>
1215
+ </dd>
1216
+
1217
+ <dt><a name="WHITE_FUNCTION_LIST"></a>white_function_list</dt>
1218
+ <dd>
1219
+ <p>
1220
+ Specify a comma separated list of function names that <strong>do not</strong>
1221
+ update the database. SELECTs using functions not specified in this list are
1222
+ neither load balanced, nor replicated if in replication mode.
1223
+ In master slave mode, such SELECTs are sent to master (primary) only.
1224
+ </p>
1225
+ <p>You can use regular expression into the list to match function name, for example if you have prefixed all your read only function with 'get_' or 'select_'
1226
+ </p>
1227
+ <pre>
1228
+ white_function_list = 'get_.*,select_.*'
1229
+ </pre>
1230
+ </dd>
1231
+
1232
+ <dt><a name="BLACK_FUNCTION_LIST"></a>black_function_list
1233
+ <dd>
1234
+ <p>
1235
+ Specify a comma separated list of function names that <strong>do</strong>
1236
+ update the database. SELECTs using functions specified in this list are neither
1237
+ load balanced, nor replicated if in replication mode.
1238
+ In master slave mode, such SELECTs are sent to master(primary) only.
1239
+ </p>
1240
+ <p>You can use regular expression into the list to match function name, for example if you have prefixed all your updating functions with 'set_', 'update_', 'delete_' or 'insert_':
1241
+ </p>
1242
+ <pre>
1243
+ black_function_list = 'nextval,setval,set_.*,update_.*,delete_.*,insert_.*'
1244
+ </pre>
1245
+ <p>
1246
+ Only one of these two lists can be filled in a configuration.
1247
+ </p>
1248
+ <p>
1249
+ Prior to pgpool-II 3.0, nextval() and setval() were known to do
1250
+ writes to the database. You can emulate this by using white_function_list and
1251
+ black_function_list:
1252
+ </p>
1253
+ <p>
1254
+ <pre>
1255
+ white_function_list = ''
1256
+ black_function_list = 'nextval,setval,lastval,currval'
1257
+ </pre>
1258
+ </p>
1259
+ <p>
1260
+ Please note that we have lastval and currval in addition to nextval and setval.
1261
+ Though lastval() and currval() are not writing functions, it is wise to add lastval() and currval() to avoid errors in the case when these functions are accidentaly load balanced to other DB node.
1262
+ Because adding to black_function_list will prevent load balancing.
1263
+ </p>
1264
+ </dd>
1265
+
1266
+ <dt><a name="REPLICATE_SELECT"></a>replicate_select</dt>
1267
+ <dd>
1268
+ <p>When set to true, pgpool-II replicates SELECTs in replication mode. If false,
1269
+ pgpool-II only sends them to the Master DB. Default is false.
1270
+ </p>
1271
+ <p>
1272
+ If a SELECT query is inside an explicit transaction block, replicate_select and
1273
+ load_balance_mode will have an effect on how replication works.
1274
+ Details are shown below.
1275
+ </p>
1276
+
1277
+ <p>
1278
+ <table border>
1279
+
1280
+ <tr>
1281
+ <td>SELECT is inside a transaction block</td>
1282
+ <td>Y</td>
1283
+ <td>Y</td>
1284
+ <td>Y</td>
1285
+ <td>N</td>
1286
+ <td>N</td>
1287
+ <td>N</td>
1288
+ <td>Y</td>
1289
+ <td>N</td>
1290
+ </tr>
1291
+
1292
+ <tr>
1293
+ <td>replicate_select is true</td>
1294
+ <td>Y</td>
1295
+ <td>Y</td>
1296
+ <td>N</td>
1297
+ <td>N</td>
1298
+ <td>Y</td>
1299
+ <td>Y</td>
1300
+ <td>N</td>
1301
+ <td>N</td>
1302
+ </tr>
1303
+
1304
+ <tr>
1305
+ <td>load_balance_mode is true</td>
1306
+ <td>Y</td>
1307
+ <td>N</td>
1308
+ <td>N</td>
1309
+ <td>N</td>
1310
+ <td>Y</td>
1311
+ <td>N</td>
1312
+ <td>Y</td>
1313
+ <td>Y</td>
1314
+ </tr>
1315
+
1316
+ <tr>
1317
+ <td>results(R:replication, M: send only to master, L: load balance)</td>
1318
+ <td>R</td>
1319
+ <td>R</td>
1320
+ <td>M</td>
1321
+ <td>M</td>
1322
+ <td>R</td>
1323
+ <td>R</td>
1324
+ <td>M</td>
1325
+ <td>L</td>
1326
+ </tr>
1327
+ </table>
1328
+ </p>
1329
+ </dd>
1330
+
1331
+ <dt><a name="INSERT_LOCK"></a>insert_lock</dt>
1332
+ <dd>
1333
+ <p>If replicating a table with SERIAL data type, the SERIAL column
1334
+ value may differ between the backends. This problem is avoidable by
1335
+ locking the table explicitly (although, transactions' parallelism will
1336
+ be severely degraded). To achieve this, however, the following change must be
1337
+ made:
1338
+
1339
+ <pre>
1340
+ INSERT INTO ...
1341
+ </pre>
1342
+ <p>
1343
+ to
1344
+ </p>
1345
+ <pre>
1346
+ BEGIN;
1347
+ LOCK TABLE ...
1348
+ INSERT INTO ...
1349
+ COMMIT;
1350
+ </pre>
1351
+
1352
+ <p>When <code>insert_lock</code> is true, pgpool-II
1353
+ automatically adds the above queries each time an INSERT is
1354
+ executed (if already in transaction, it simply adds LOCK TABLE
1355
+ ....).
1356
+ </p>
1357
+ <p>pgpool-II 2.2 or later, it automatically detects whether the table
1358
+ has a SERIAL columns or not, so it will never lock the table if it does
1359
+ not use SERIAL columns.
1360
+ </p>
1361
+ <p>
1362
+ pgpool-II 3.0 series until 3.0.4 uses a row lock against the sequence
1363
+ relation, rather than table lock. This is intended to minimize lock
1364
+ conflict with VACUUM (including autovacuum). However this will lead to
1365
+ another problem. After transaction wraparound happens, row locking
1366
+ against the sequence relation causes PostgreSQL internal error (more
1367
+ precisely, access error on pg_clog, which keeps transaction status).
1368
+ To prevent this, PostgreSQL core developers decided to disallow row
1369
+ locking against sequences and this will break pgpool-II of course (the
1370
+ &quot;fixed&quot; version of PostgreSQL will be released as 9.0.5,
1371
+ 8.4.9, 8.3.16 and 8.2.22).
1372
+ </p>
1373
+ <p>
1374
+ pgpool-II 3.0.5 or later uses a row lock against pgpool_catalog.insert_lock
1375
+ table because new PostgreSQL disallows a row lock against the sequence
1376
+ relation. So creating insert_lock table in all databases which are
1377
+ accessed via pgpool-II beforehand is required. See <a href="#install">
1378
+ Creating insert_lock table</a> for more details. If does not
1379
+ exist insert_lock table, pgpool-II locks the insert target
1380
+ table. This behavior is same as pgpool-II 2.2 and 2.3 series.
1381
+ If you want to use insert_lock which is compatible with older
1382
+ releases, you can specify lock method by configure script. See
1383
+ <a href="#install">configure</a> for more details.
1384
+ </p>
1385
+ <p>
1386
+ You might want to have a finer (per statement) control:
1387
+ </p>
1388
+
1389
+ <ol>
1390
+ <li>set <code>insert_lock</code> to true, and add <code>/*NO
1391
+ INSERT LOCK*/</code> at the beginning of an INSERT
1392
+ statement for which you do not want to acquire the table
1393
+ lock.</li>
1394
+
1395
+ <li>set <code>insert_lock</code> to false, and add
1396
+ <code>/*INSERT LOCK*/</code> at the beginning of an INSERT
1397
+ statement for which you want to acquire the table lock.</li>
1398
+ </ol>
1399
+
1400
+ <p>
1401
+ Default value is false. If <code>insert_lock</code> is enabled,
1402
+ the regression tests for PostgreSQL 8.0 will fail in transactions,
1403
+ privileges, rules, and alter_table. The reason for this is that
1404
+ pgpool-II tries to LOCK the VIEW for the rule test, and will
1405
+ produce the following error message:</p>
1406
+
1407
+ <pre>
1408
+ ! ERROR: current transaction is aborted, commands ignored until
1409
+ end of transaction block
1410
+ </pre>
1411
+
1412
+ <p>For example, the transactions test tries an INSERT into a table
1413
+ which does not exist, and pgpool-II causes PostgreSQL to acquire the
1414
+ lock before that. The transaction will be aborted, and the following
1415
+ INSERT statement produces the above error message.</p>
1416
+
1417
+
1418
+ <dt><a name="RECOVERY_USER"></a>recovery_user</dt>
1419
+ <dd>
1420
+ <p>
1421
+ This parameter specifies a PostgreSQL username for online recovery.
1422
+ It can be changed without restarting.
1423
+ </p>
1424
+
1425
+ <dt><a name="RECOVERY_PASSWORD"></a>recovery_password</dt>
1426
+ <dd>
1427
+ <p>
1428
+ This parameter specifies a PostgreSQL password for online recovery.
1429
+ It can be changed without restarting.
1430
+ </p>
1431
+
1432
+ <dt><a name="RECOVERY_1ST_STAGE_COMMAND"></a>recovery_1st_stage_command</dt>
1433
+ <dd>
1434
+ <p>
1435
+ This parameter specifies a command to be run by master(primary) PostgreSQL server at the first stage of online
1436
+ recovery. The command file must be put in the database cluster directory
1437
+ for security reasons.
1438
+ For example, if recovery_1st_stage_command = 'sync-command', then
1439
+ pgpool-II executes $PGDATA/sync-command.
1440
+ </p>
1441
+ <p>
1442
+ recovery_1st_stage_command will receive 3 parameters as follows:
1443
+ </p>
1444
+ <ol>
1445
+ <li>path to master(primary) database cluster</li>
1446
+ <li>PostgreSQL host name to be recovered</li>
1447
+ <li>path to database cluster to be recovered</li>
1448
+ </ol>
1449
+ </p>
1450
+ <p>
1451
+ Note that pgpool-II <b>accepts</b> connections and queries while
1452
+ recovery_1st_stage command is executed. You can retrieve and update
1453
+ data during this stage.
1454
+ </p>
1455
+ <p>
1456
+ This parameter can be changed without restarting.
1457
+ </p>
1458
+
1459
+ <dt><a name="RECOVERY_2ND_STAGE_COMMAND"></a>recovery_2nd_stage_command</dt>
1460
+ <dd>
1461
+ <p>
1462
+ This parameter specifies a command to be run by master(primary) PostgreSQL server at the second stage of online
1463
+ recovery. The command file must be put in the database cluster directory
1464
+ for security reasons.
1465
+
1466
+ For example, if recovery_2nd_stage_command = 'sync-command', then
1467
+ pgpool-II executes $PGDATA/sync-command.
1468
+ </p>
1469
+ <p>
1470
+ recovery_2nd_stage_command will receive 3 parameters as follows:
1471
+ </p>
1472
+ <ol>
1473
+ <li>path to master(primary) database cluster</li>
1474
+ <li>PostgreSQL host name to be recovered</li>
1475
+ <li>path to database cluster to be recovered</li>
1476
+ </ol>
1477
+ </p>
1478
+ <p>
1479
+ Note that pgpool-II <b>does not accept</b> connections and queries while
1480
+ recovery_2nd_stage_command is running. Thus if a client stays connected for a
1481
+ long time, the recovery command won't be executed. pgpool-II waits until all
1482
+ clients have closed their connections. The command is only executed when no
1483
+ client is connected to pgpool-II anymore.
1484
+ </p>
1485
+ <p>
1486
+ This parameter can be changed without restarting.
1487
+ </p>
1488
+
1489
+ <dt><a name="RECOVERY_TIMEOUT"></a>recovery_timeout</dt>
1490
+ <dd>
1491
+ <p>
1492
+ pgpool does not accept new connections during the second stage. If a client
1493
+ connects to pgpool during recovery processing, it will have to wait for the end
1494
+ of the recovery.
1495
+ </p>
1496
+ <p>
1497
+ This parameter specifies recovery timeout in sec. If this timeout is reached,
1498
+ pgpool cancels online recovery and accepts connections. 0 means no wait.
1499
+ </p>
1500
+ <p>
1501
+ This parameter can be changed without restarting.
1502
+ </p>
1503
+
1504
+ <dt><a name="CLIENT_IDLE_LIMIT_IN_RECOVERY"></a>client_idle_limit_in_recovery</dt>
1505
+ <dd>
1506
+ <p> Similar to client_idle_limit but only takes effect in the second
1507
+ stage of recovery. A client being idle for client_idle_limit_in_recovery
1508
+ seconds since its last query will get disconnected.
1509
+ This is useful for preventing the pgpool recovery from being
1510
+ disturbed by a lazy client or if the TCP/IP connection between the client
1511
+ and pgpool is accidentally down (a cut cable for instance).
1512
+ If set to -1, disconnect the client immediately.
1513
+ The default value for client_idle_limit_in_recovery is 0,
1514
+ which means the feature is turned off.
1515
+ </p>
1516
+ <p>
1517
+ If your clients are very busy, pgpool-II cannot enter the second stage of
1518
+ recovery whatever value of client_idle_limit_in_recovery you may choose. In
1519
+ this case, you can set client_idle_limit_in_recovery to -1 so that pgpool-II
1520
+ immediately disconnects such busy clients before entering the second stage.
1521
+ </p>
1522
+ <p>
1523
+ You need to reload pgpool.conf if you change client_idle_limit_in_recovery.</p>
1524
+
1525
+ <dt><a name="LOBJ_LOCK_TABLE"></a>lobj_lock_table</dt>
1526
+ <dd>
1527
+ <p>
1528
+ This parameter specifies a table name used for large object replication control.
1529
+ If it is specified, pgpool will lock the table specified by
1530
+ lobj_lock_table and generate a large object id by looking into
1531
+ pg_largeobject system catalog and then call lo_create to create the large object.
1532
+ This procedure guarantees that pgpool will get the same large object id in all DB
1533
+ nodes in replication mode. Please note that PostgreSQL 8.0 or older does not
1534
+ have lo_create, thus this feature will not work.
1535
+ </p>
1536
+ <p>
1537
+ A call to the libpq function lo_creat() will trigger this feature. Also
1538
+ large object creation through Java API (JDBC driver), PHP
1539
+ API (pg_lo_create, or similar API in PHP library such as PDO), and this same
1540
+ API in various programming languages are known to use a similar protocol,
1541
+ and thus should work.
1542
+ </p>
1543
+ <p>
1544
+ The following large object create operation will not work:
1545
+ <p>
1546
+ <ul>
1547
+ <li>lo_create of libpq
1548
+ <li>Any API of any language using lo_create
1549
+ <li>lo_import function in backend
1550
+ <li>SELECT lo_creat
1551
+ </ul>
1552
+ </p>
1553
+ <p>
1554
+ It does not matter what schema lobj_lock_table is stored in, but this table
1555
+ should be writable by any user. Here is an example showing how to create such
1556
+ a table:
1557
+ </p>
1558
+ <p>
1559
+ <pre>
1560
+ CREATE TABLE public.my_lock_table ();
1561
+ GRANT ALL ON public.my_lock_table TO PUBLIC;
1562
+ </pre>
1563
+ </p>
1564
+ <p>
1565
+ The table specified by lobj_lock_table must be created beforehand. If
1566
+ you create the table in template1, any database created afterward will
1567
+ have it.
1568
+ </p>
1569
+ <p>
1570
+ If lobj_lock_table has empty string(''), the feature is disabled
1571
+ (thus large object replication will not work). The default value for
1572
+ lobj_lock_table is ''.
1573
+ </p>
1574
+
1575
+ </dl>
1576
+
1577
+ <h4><p>condition for load balancing</p></h4>
1578
+ <p>
1579
+ For a query to be load balanced, all the following requirements
1580
+ must be met:
1581
+ <ul>
1582
+ <li>PostgreSQL version 7.4 or later</li>
1583
+ <li>the query must not be in an explicitly declared
1584
+ transaction (i.e. not in a BEGIN ~ END block)</li>
1585
+ <li>it's not SELECT nextval or SELECT setval
1586
+ <li>it's not SELECT INTO
1587
+ <li>it's not SELECT FOR UPDATE nor FOR SHARE
1588
+ <li>it starts with "SELECT" or one of COPY TO STDOUT, EXPLAIN, EXPLAIN ANALYZE SELECT...
1589
+ ignore_leading_white_space = true will ignore leading white space.
1590
+ </ul>
1591
+ </p>
1592
+ <p>
1593
+ Note that you could suppress load balancing by inserting arbitrary
1594
+ comments just in front of the SELECT query:
1595
+ <pre>
1596
+ /*REPLICATION*/ SELECT ...
1597
+ </pre>
1598
+ </p>
1599
+
1600
+ <p>
1601
+ Please refer to <a href="#replicate_select">replicate_select</a> as well.
1602
+ See also a <a href="where_to_send_queries.pdf">flow chart</a>.
1603
+ </p>
1604
+
1605
+ <p>
1606
+ <font color="red">
1607
+ Note: the JDBC driver has an autocommit option. If autocommit is false, the JDBC
1608
+ driver sends "BEGIN" and "COMMIT" by itself. So pgpool cannot do any load
1609
+ balancing. You need to call setAutoCommit(true) to enable autocommit.
1610
+ </font>
1611
+ </p>
1612
+
1613
+ <h4><p>Failover in Replication Mode</p></h4>
1614
+
1615
+ <p> pgpool-II degenerates a dead backend and continues the
1616
+ service. The service can be continued if there is at least one backend
1617
+ alive.</p>
1618
+
1619
+ <h4><p>Specific errors in replication mode</p></h2>
1620
+ <p>
1621
+ In replication mode, if pgpool finds that the number of affected tuples by INSERT, UPDATE, DELETE are not same, it sends erroneous SQL statement to all DB nodes to abort the transaction if failover_if_affected_tuples_mismatch is set to false
1622
+ (degeneration occurs if it is set to true).
1623
+ In this case you will see following error messages on client terminal:
1624
+ <pre>
1625
+ =# UPDATE t SET a = a + 1;
1626
+ ERROR: pgpool detected difference of the number of update tuples Possible last query was: "update t1 set i = 1;"
1627
+ HINT: check data consistency between master and other db node
1628
+ </pre>
1629
+ You will see number of updated rows in PostgreSQL log(in this case DB node 0 has 0 updated row and DB node 1 has 1 updated row)
1630
+ <pre>
1631
+ 2010-07-22 13:23:25 LOG: pid 5490: SimpleForwardToFrontend: Number of affected tuples are: 0 1
1632
+ 2010-07-22 13:23:25 LOG: pid 5490: ReadyForQuery: Degenerate backends: 1
1633
+ 2010-07-22 13:23:25 LOG: pid 5490: ReadyForQuery: Number of affected tuples are: 0 1
1634
+ </pre>
1635
+ </p>
1636
+
1637
+ <h3><a name="master_slave_mode"></a>Master/Slave Mode</h3>
1638
+
1639
+ <p>This mode is used to couple pgpool-II with another master/slave
1640
+ replication software (like Slony-I and Streaming replication), which is responsible
1641
+ for doing the actual data replication.
1642
+ DB nodes' information (backend_hostname, backend_port,
1643
+ backend_weight, backend_flag and backend_data_directory if you need the
1644
+ online recovery fonctionality) must be set, in the same way as in the replication mode.
1645
+ In addition to that, set
1646
+ <code>master_slave_mode</code> and <code>load_balance_mode</code> to
1647
+ true. pgpool-II will then send queries that need to be replicated to the
1648
+ Master DB, and other queries will be load balanced if possible. Queries sent to
1649
+ Master DB because they cannot be balanced are of course accounted for in the
1650
+ load balancing algorithm.</p>
1651
+
1652
+
1653
+ <p>In master/slave mode, DDL and DML for temporary table can be executed on the
1654
+ master node only.
1655
+ SELECT can be forced to be executed on the master as well, but for this you
1656
+ need to put a /*NO LOAD BALANCE*/ comment before the SELECT statement.</p>
1657
+
1658
+ <p>In the master/slave mode, <code>replication_mode</code> must be set
1659
+ to false, and <code>master_slave_mode</code> to true.</p>
1660
+
1661
+ <p>The master/slave mode has a 'master_slave_sub mode'.
1662
+ The default is 'slony' which is
1663
+ suitable for Slony-I. You can also set it to 'stream', which should be
1664
+ set if you want to work with PostgreSQL's built-in replication system
1665
+ (Streaming Replication).
1666
+ The sample configuration file for the Slony-I sub-mode is
1667
+ pgpool.conf.sample-master-slave and the sample for the streaming replication
1668
+ sub-module is pgpool.conf.sample-stream.
1669
+ </p>
1670
+ <p>
1671
+ Please restart pgpool-II if you change any of the above parameters.
1672
+ </p>
1673
+ <p>
1674
+ You can set white_function_list and black_function_list to control load
1675
+ balancing in master/slave mode.
1676
+ See <a href="#white_function_list">white_function_list</a> for more details.
1677
+ </p>
1678
+
1679
+ <h4><a name="stream">Streaming Replication</h4>
1680
+ <p>
1681
+ As stated above, pgpool-II can work together with Streaming Replication, which
1682
+ is available since PostgreSQL 9.0. To use it, enable 'master_slave' and
1683
+ set 'master_slave_sub_mode' to 'stream'. pgpool-II assumes that Streaming
1684
+ Replication is used with Hot Standby at present, which means that the standby
1685
+ database is open read-only.
1686
+ The following directives can be used with this mode:
1687
+ </p>
1688
+ <p>
1689
+ <ul>
1690
+ <li>delay_threshold
1691
+ <p>
1692
+ Specifies the maximum tolerated replication delay of the standby against the
1693
+ primary server in WAL bytes.
1694
+ If the delay exceeds delay_threshold, pgpool-II does not send SELECT queries to
1695
+ the standby server anymore. Everything is sent to the primary server
1696
+ even if load balance mode is enabled, until the standby has caught-up.
1697
+ If delay_threshold is 0 or sr checking is disabled, the delay
1698
+ checking is not performed. This check is performed every 'sr_check_period'.
1699
+ The default value for delay_threshold is 0.
1700
+ You need to reload pgpool.conf if you change this directive.
1701
+ </p>
1702
+
1703
+ <li>sr_check_period
1704
+ <p>
1705
+ This parameter specifies the interval between the streaming replication
1706
+ delay checks in seconds. Default is 0, which means the check is disabled.
1707
+ You need to reload pgpool.conf if you change sr_check_period.
1708
+ </p>
1709
+
1710
+ <li>sr_check_user</dt>
1711
+ <p>
1712
+ The user name to perform streaming replication check. This user must
1713
+ exist in all the PostgreSQL backends. Otherwise, the check causes
1714
+ an error. Note that sr_check_user and sr_check_password are used
1715
+ even sr_check_period is 0. To identify the primary server,
1716
+ pgpool-II sends function call request to each backend.
1717
+ sr_check_user and sr_check_password are used for this session. You
1718
+ need to reload pgpool.conf if you change sr_check_user.
1719
+ </p>
1720
+
1721
+ <li>sr_check_password</dt>
1722
+ <p>
1723
+ The password of the user to perform streaming replication check.
1724
+ If no password is required, specify empty string('').
1725
+ You need to reload pgpool.conf if you change sr_check_password.
1726
+ </p>
1727
+
1728
+ <li>log_standby_delay
1729
+ <p>
1730
+ Specifies how to log the replication delay.
1731
+ If 'none' is specified, no log is written.
1732
+ If 'always', log the delay every time health checking is performed.
1733
+ If 'if_over_threshold' is specified, the log is written when the delay
1734
+ exceeds delay_threshold.
1735
+ The default value for log_standby_delay is 'none'.
1736
+ You need to reload pgpool.conf if you change this directive.
1737
+ </p>
1738
+ <p>
1739
+ You could monitor the replication delay by using the "show pool_status"
1740
+ command as well.
1741
+ The column name is "standby_delay#"(where '#' should be replaced by DB node id).
1742
+ </p>
1743
+ </ul>
1744
+ </p>
1745
+
1746
+ <h4>Failover with Streaming Replication</h4>
1747
+ <p>
1748
+ In master/slave mode with streaming replication, if the primary or standby
1749
+ node goes down, pgpool-II can be set up to trigger a failover.
1750
+ Nodes can be detached automatically without further setup.
1751
+ While doing streaming replication, the standby node checks for the presence of a
1752
+ "trigger file" and on finding it, the standby stops continuous recovery and goes
1753
+ into read-write mode. By using this, you can have the standby database take over
1754
+ when the primary goes down.
1755
+ </p>
1756
+ <p>
1757
+ <strong>Caution: If you plan to use multiple standby nodes, we recommend
1758
+ to set a delay_threshold to prevent any query directed to other standby
1759
+ nodes from retrieving older data.
1760
+ </p>
1761
+ <p>
1762
+ If a second standby took over primary when the first standby has already
1763
+ taken over too, you would get bogus data from the second standby.
1764
+ We recommend not to plan this kind of configuration.
1765
+ </strong>
1766
+ </p>
1767
+ <p>
1768
+ How to setup a failover configuration is as follows.
1769
+ </p>
1770
+ <p>
1771
+ <ol>
1772
+ <li>Put a failover script somewhere (for example
1773
+ /usr/local/pgsql/bin) and give it execute permission.
1774
+ <pre>
1775
+ $ cd /usr/loca/pgsql/bin
1776
+ $ cat failover_stream.sh
1777
+ #! /bin/sh
1778
+ # Failover command for streaming replication.
1779
+ # This script assumes that DB node 0 is primary, and 1 is standby.
1780
+ #
1781
+ # If standby goes down, do nothing. If primary goes down, create a
1782
+ # trigger file so that standby takes over primary node.
1783
+ #
1784
+ # Arguments: $1: failed node id. $2: new master hostname. $3: path to
1785
+ # trigger file.
1786
+
1787
+ failed_node=$1
1788
+ new_master=$2
1789
+ trigger_file=$3
1790
+
1791
+ # Do nothing if standby goes down.
1792
+ if [ $failed_node = 1 ]; then
1793
+ exit 0;
1794
+ fi
1795
+
1796
+ # Create the trigger file.
1797
+ /usr/bin/ssh -T $new_master /bin/touch $trigger_file
1798
+
1799
+ exit 0;
1800
+
1801
+ chmod 755 failover_stream.sh
1802
+ </pre>
1803
+ <li>Set failover_commmand in pgpool.conf.
1804
+ <pre>
1805
+ failover_command = '/usr/local/src/pgsql/9.0-beta/bin/failover_stream.sh %d %H /tmp/trigger_file0'
1806
+ </pre>
1807
+
1808
+ <li>Set recovery.conf on the standby node.
1809
+ <a href="recovery.conf.sample">A sample recovery.conf</a> can be found
1810
+ under the PostgreSQL installation directory. Its name is
1811
+ "share/recovery.conf.sample".
1812
+ Copy recovery.conf.sample as recovery.conf inside the database cluster
1813
+ directory and edit it.
1814
+ <pre>
1815
+ standby_mode = 'on'
1816
+ primary_conninfo = 'host=name of primary_host user=postgres'
1817
+ trigger_file = '/tmp/trigger_file0'
1818
+ </pre>
1819
+
1820
+ <li>Set postgresql.conf on the primary node.
1821
+ Below is just an example. You will need to tweak it for your environment.
1822
+ <pre>
1823
+ wal_level = hot_standby
1824
+ max_wal_senders = 1
1825
+ </pre>
1826
+
1827
+ <li>Set pg_hba.conf on the primary node.
1828
+ Below is just an example. You will need to tweak it for your environment.
1829
+ <pre>
1830
+ host replication postgres 192.168.0.10/32 trust
1831
+ </pre>
1832
+
1833
+ </ol>
1834
+
1835
+ <p>
1836
+ Start primary and secondary PostgreSQL nodes to initiate Streaming replication.
1837
+ If the primary node goes down, the standby node will automatically start as a
1838
+ normal PostgreSQL and will be ready to accept write queries.
1839
+ </p>
1840
+
1841
+ <h4>Streaming Replication</h4>
1842
+ <p>
1843
+ While using Streaming replication and Hot Standby, it is important to
1844
+ determine which query can be sent to the primary or the standby,
1845
+ and which one should not be sent to the standby.
1846
+ pgpool-II's Streaming Replication mode carefully takes care of this.
1847
+ In this chapter we'll explain how pgpool-II accomplishes this.
1848
+ </p>
1849
+ <p>
1850
+ We distinguish which query should be sent to which node by looking
1851
+ at the query itself.
1852
+ </p>
1853
+ <p>
1854
+ <ul>
1855
+ <li>These queries should be sent to the primary node only
1856
+ <ul>
1857
+ <li>INSERT, UPDATE, DELETE, COPY FROM, TRUNCATE, CREATE, DROP, ALTER, COMMENT
1858
+ <li>SELECT ... FOR SHARE | UPDATE
1859
+ <li>SELECT in transaction isolation level SERIALIZABLE
1860
+ <li>LOCK command more strict than ROW EXCLUSIVE MODE
1861
+ <li>Some transactional commands:
1862
+ <ul>
1863
+ <li>BEGIN READ WRITE, START TRANSACTION READ WRITE
1864
+ <li>SET TRANSACTION READ WRITE, SET SESSION CHARACTERISTICS AS TRANSACTION READ WRITE
1865
+ <li>SET transaction_read_only = off
1866
+ </ul>
1867
+ <li>Two phase commit commands: PREPARE TRANSACTION, COMMIT PREPARED, ROLLBACK PREPARED
1868
+ <li>LISTEN, UNLISTEN, NOTIFY
1869
+ <li>VACUUM
1870
+ <li>Some sequence functions (nextval and setval)
1871
+ <li>Large objects creation commands
1872
+ </ul>
1873
+ <li>These queries can be sent to both the primary node and the standby node.
1874
+ If load balancing is enabled, these types of queries can be sent to the
1875
+ standby node.
1876
+ However, if delay_threshold is set and the replication delay is higher than
1877
+ delay_threshold, queries are sent to the primary node.
1878
+ <ul>
1879
+ <li>SELECT not listed above
1880
+ <li>COPY TO
1881
+ <li>DECLARE, FETCH, CLOSE
1882
+ <li>SHOW
1883
+ </ul>
1884
+ <li>These queries are sent to both the primary node and the standby node
1885
+ <ul>
1886
+ <li>SET
1887
+ <li>DISCARD
1888
+ <li>DEALLOCATE ALL
1889
+ </ul>
1890
+ </ul>
1891
+ </p>
1892
+
1893
+ <p>
1894
+ In an explicit transaction:
1895
+ <ul>
1896
+ <li>Transaction starting commands such as BEGIN are sent to the primary node.
1897
+ <li>Following SELECT and some other queries that can be sent to both
1898
+ primary or standby are executed in the transaction or on
1899
+ the standby node.
1900
+ <li><p>
1901
+ Commands which cannot be executed on the standby such as INSERT are sent
1902
+ to the primary.
1903
+ After one of these commands, even SELECTs are sent to the primary node,
1904
+ This is because these SELECTs might want to see the result of an INSERT
1905
+ immediately. This behavior continues until the transaction closes or aborts.
1906
+ </p>
1907
+ </ul>
1908
+ </p>
1909
+
1910
+ <p>
1911
+ In the extended protocol, it is possible to determine if the query can
1912
+ be sent to standby or not in load balance mode while parsing the query.
1913
+ The rules are the same as for the non extended protocol.
1914
+ For example, INSERTs are sent to the primary node.
1915
+ Following bind, describe and execute will be sent to the primary node as well.
1916
+ </p>
1917
+
1918
+ <p>
1919
+ [Note: If the parse of a SELECT statement is sent to the standby node due to load
1920
+ balancing, and then a DML statement, such as an INSERT, is sent to pgpool-II,
1921
+ then the parsed SELECT will have to be executed on the primary node. Therefore,
1922
+ we re-parse the SELECT on the primary node.]
1923
+ <p>
1924
+ Lastly, queries that pgpool-II's parser thinks to be an error are sent to the
1925
+ primary node.
1926
+ </p>
1927
+
1928
+ <h4>Online recovery with Streaming Replication</h4>
1929
+ <p>
1930
+ In master/slave mode with streaming replication, online recovery can be
1931
+ performed.
1932
+ In the online recovery procedure, primary server acts as a master server and recoveres specified standby server.
1933
+ Thus the recovery procedure requires that the primary server is up and running.
1934
+ If the primary server goes down, and no standby server is promoted, you need to stop
1935
+ pgpool-II and all PostgreSQL servers and recover them manually.
1936
+ </p>
1937
+
1938
+ <p>
1939
+ <ol>
1940
+ <li>Set recovery_user. Usually it's "postgres".
1941
+ <pre>
1942
+ recovery_user = 'postgres'
1943
+ </pre>
1944
+ <li>Set recovery_password for recovery_user to login database.
1945
+ <pre>
1946
+ recovery_password = 't-ishii'
1947
+ </pre>
1948
+
1949
+ <li> Set recovery_1st_stage_command.
1950
+ The script for this stage should perform a base backup of the primary and
1951
+ restore it on the standby node.
1952
+ Place this script inside the primary database cluster directory and give it
1953
+ execute permission.
1954
+ Here is the sample script <a href="basebackup.sh">(basebackup.sh)</a> for
1955
+ a configuration of one primary and one standby.
1956
+ You need to setup ssh so that recovery_user can login from the primary to
1957
+ the standby without being asked for a password.
1958
+ <pre>
1959
+ recovery_1st_stage_command = 'basebackup.sh'
1960
+ </pre>
1961
+ <li>Leave recovery_2nd_stage_command be empty.
1962
+ <pre>
1963
+ recovery_2nd_stage_command = ''
1964
+ </pre>
1965
+
1966
+ <li>Install required C and SQL functions to perform online recovery
1967
+ into each DB nodes.
1968
+ </p>
1969
+
1970
+ <pre>
1971
+ # cd pgpool-II-x.x.x/sql/pgpool-recovery
1972
+ # make
1973
+ # make install
1974
+ # psql -f pgpool-recovery.sql template1
1975
+ </pre>
1976
+
1977
+ <li>After completing online recovery, pgpool-II will start PostgreSQL on
1978
+ the standby node.
1979
+ Install the script for this purpose on each DB nodes.
1980
+ <a href="pgpool_remote_start">Sample script</a> is included in "sample"
1981
+ directory of the source code.
1982
+ This script uses ssh. You need to allow recovery_user to login from the
1983
+ primary node to the standby node without being asked password.
1984
+ </ol>
1985
+ </p>
1986
+
1987
+ <p>
1988
+ That's it.
1989
+ Now you should be able to use pcp_recovery_node (as long as the standby
1990
+ node stops) or push "recovery" button of pgpoolAdmin to perform online recovery.
1991
+ If something goes wrong, please examin pgpool-II log, primary server log and standby server log(s).
1992
+ </p>
1993
+ <p>
1994
+ For your reference, here are the steps taken in the recovery procedure.
1995
+ <ol>
1996
+ <li>Pgpool-II connects to primary server's template1 database as user = recovery_user, password = recovery_password.
1997
+ <li>Primary server executes pgpool_recovery function.
1998
+ <li>pgpool_recovery function executes recovery_1st_stage_command.
1999
+ Note that PostgreSQL executes functions with database cluster as the current directory.
2000
+ Thus recovery_1st_stage_command is executed in the database cluster directory.
2001
+ <li>Primary server executes pgpool_remote_start function.
2002
+ This function executes a script named "pgpool_remote_start" in the database cluster directory, and it executes pg_ctl command on the standby server to be recovered via ssh.
2003
+ pg_ctl will start postmaster in background.
2004
+ So we need to make sure that postmaster on the standby actually starts.
2005
+ <li>pgpool-II tries to connect to the standby PostgreSQL as user = recovery_user and password = recovery_password.
2006
+ The database to be connected is "postgres" if possible. Otherwise "template1" is used.
2007
+ pgpool-II retries for <a href="#RECOVERY_TIMEOUT">recovery_timeout</a> seconds.
2008
+ If success, go to next step.
2009
+ <li>If <a href="#FAILBACK_COMMAND">failback_command</a> is not empty, pgpool-II parent process executes the script.
2010
+ <li>After failback_command finishes, pgpool-II restart all child processes.
2011
+ </ol>
2012
+ </p>
2013
+
2014
+ <h3>Parallel Mode</h3>
2015
+
2016
+ <p>This mode activates parallel execution of queries. Tables can be split, and
2017
+ data distributed to each node. Moreover, the replication and the load balancing
2018
+ features can be used at the same time. In parallel mode, replication_mode and
2019
+ load_balance_mode are set to true in pgpool.conf, master_slave is set to false,
2020
+ and parallel_mode is set to true. When you change this parameter, restart pgpool-II.
2021
+ </p>
2022
+
2023
+ <h4><p>Configuring the System DB</p></h4>
2024
+
2025
+ <p>To use the parallel mode, the System DB must be configured
2026
+ properly. The System DB contains rules, stored in a table, to choose an
2027
+ appropriate backend to send partitioned
2028
+ data to. The System DB does not need to be created on the same host as
2029
+ pgpool-II. The System DB's configuration is done in
2030
+ <code>pgpool.conf</code>.</p>
2031
+
2032
+ <dl>
2033
+ <dt><a name="SYSTEM_DB_HOSTNAME"></a>system_db_hostname</dt>
2034
+ <dd>
2035
+ <p>The hostname where the System DB is. Specifying the
2036
+ empty string ('') means the System DB is on the same host as
2037
+ pgpool-II, and will be accessed via a UNIX domain socket.</p>
2038
+ </dd>
2039
+
2040
+ <dt><a name="SYSTEM_DB_PORT"></a>system_db_port</dt>
2041
+ <dd>
2042
+ <p>The port number for the System DB</p>
2043
+ </dd>
2044
+
2045
+ <dt><a name="SYSTEM_DBNAME"></a>system_dbname</dt>
2046
+ <dd>
2047
+ <p>The partitioning rules and other information will be defined
2048
+ in the database specified here. Default value is:
2049
+ <code>'pgpool'</code>.</p>
2050
+ </dd>
2051
+
2052
+ <dt><a name="SYSTEM_DB_SCHEMA"></a>system_db_schema</dt>
2053
+ <dd>
2054
+ <p>The partitioning rules and other information will be defined
2055
+ in the schema specified here. Default value is:
2056
+ <code>'pgpool_catalog'</code>.</p>
2057
+ </dd>
2058
+
2059
+ <dt><a name="SYSTEM_DB_USER"></a>system_db_user</dt>
2060
+ <dd>
2061
+ <p>The username to connect to the System DB.</p>
2062
+ </dd>
2063
+
2064
+ <dt><a name="SYSTEM_DB_PASSWORD"></a>system_db_password</dt>
2065
+ <dd>
2066
+ <p>The password for the System DB. If no password is necessary,
2067
+ set the empty string ('').</p>
2068
+ </dd>
2069
+
2070
+ <dt><a name="SSL_CA_CERT"></a>ssl_ca_cert</dt>
2071
+ <dd>
2072
+ <p>
2073
+ The path to a PEM format file containing one or more CA root
2074
+ certificates, which can be used to verify the backend server
2075
+ certificate. This is analogous to the <code>-CAfile</code> option
2076
+ of the OpenSSL <code>verify(1)</code> command.
2077
+ </p>
2078
+
2079
+ <p>
2080
+ The default value for this option is unset, so no
2081
+ verification takes place. Verification will still occur if
2082
+ this option is not set but a value has been given for
2083
+ <code>ssl_ca_cert_dir</code>.
2084
+ </p>
2085
+ </dd>
2086
+
2087
+ <dt><a name="SSL_CA_CERT_DIR"></a>ssl_ca_cert_dir</dt>
2088
+ <dd>
2089
+ <p>
2090
+ The path to a directory containing PEM format CA certficate
2091
+ files, which can be used to verify the backend server
2092
+ certificate. This is analogous to the <code>-CApath</code> option
2093
+ of the OpenSSL <code>verify(1)</code> command.
2094
+ </p>
2095
+
2096
+ <p>
2097
+ The default value for this option is unset, so no
2098
+ verification takes place. Verification will still occur if
2099
+ this option is not set but a value has been given for
2100
+ <code>ssl_ca_cert</code>.
2101
+ </p>
2102
+ </dd>
2103
+
2104
+ </dl>
2105
+
2106
+ <h4><p>Initial Configuration of the System DB</p></h4>
2107
+
2108
+ <p>First, create the database and schema specified in the
2109
+ <code>pgpool.conf</code> file. A sample script can be found in
2110
+ <code>$prefix/share/system_db.sql</code>. If you have specified a
2111
+ different database name or schema, change them accordingly in the script.
2112
+
2113
+ <pre>
2114
+ psql -f $prefix/share/system_db.sql pgpool
2115
+ </pre>
2116
+
2117
+ </p>
2118
+
2119
+ <h4><p>Registering a Partitioning Rule</p></h4>
2120
+
2121
+ <p>The rules for data partitioning must be registered into the
2122
+ <code>pgpool_catalog.dist_def</code> table.</p>
2123
+
2124
+ <pre>
2125
+ CREATE TABLE pgpool_catalog.dist_def(
2126
+ dbname TEXT, -- database name
2127
+ schema_name TEXT, -- schema name
2128
+ table_name TEXT, -- table name
2129
+ col_name TEXT NOT NULL CHECK (col_name = ANY (col_list)), -- partitioning key column name
2130
+ col_list TEXT[] NOT NULL, -- names of table attributes
2131
+ type_list TEXT[] NOT NULL, -- types of table attributes
2132
+ dist_def_func TEXT NOT NULL, -- name of the partitioning rule function
2133
+ PRIMARY KEY (dbname,schema_name,table_name)
2134
+ );
2135
+ </pre>
2136
+
2137
+
2138
+ <h4><p>Registering a Replication Rule</p></h4>
2139
+ <p>
2140
+ Tables that are not distributed have to be replicated. When a query joins a
2141
+ distributed table with another table, pgpool gets the replication information
2142
+ from the pgpool_catalog.replicate_def table. A table has to be either replicated
2143
+ or distributed.
2144
+ </p>
2145
+
2146
+ <pre>
2147
+ CREATE TABLE pgpool_catalog.replicate_def(
2148
+ dbname TEXT, --database name
2149
+ schema_name TEXT, --schema name
2150
+ table_name TEXT, --table name
2151
+ col_list TEXT[] NOT NULL, -- names of table attributes
2152
+ type_list TEXT[] NOT NULL, -- types of table attributes
2153
+ PRIMARY KEY (dbname,schema_name,table_name)
2154
+ );
2155
+ </pre>
2156
+
2157
+ <h4><p>Example for partitioning the pgbench tables</p></h4>
2158
+
2159
+ <p>
2160
+ In this example, the accounts table is partitioned, and the branches and tellers
2161
+ table are replicated.
2162
+ The accounts table and the branches table are joined by bid.
2163
+ The branches table is registered into the replication table.
2164
+ If the three tables (accounts, branches, and tellers)
2165
+ are to be joined, it is necessary to register a replication rule for
2166
+ the tellers table too.
2167
+ </p>
2168
+ <pre>
2169
+ INSERT INTO pgpool_catalog.dist_def VALUES (
2170
+ 'pgpool',
2171
+ 'public',
2172
+ 'accounts',
2173
+ 'aid',
2174
+ ARRAY['aid','bid','abalance','filler'],
2175
+ ARRAY['integer','integer','integer','character(84)'],
2176
+ 'pgpool_catalog.dist_def_accounts'
2177
+ );
2178
+
2179
+ INSERT INTO pgpool_catalog.replicate_def VALUES (
2180
+ 'pgpool',
2181
+ 'public',
2182
+ 'branches',
2183
+ ARRAY['bid','bbalance','filler'],
2184
+ ARRAY['integer','integer','character(84)']
2185
+ );
2186
+ </pre>
2187
+
2188
+ <p>The partitioning rule function (here,
2189
+ pgpool_catalog.dist_def_accounts) takes a value for the partitioning
2190
+ key column, and returns the corresponding DB node ID. Note that the node ID
2191
+ must start from 0. Below is an example of this function for pgbench.
2192
+ </p>
2193
+ <pre>
2194
+ CREATE OR REPLACE FUNCTION pgpool_catalog.dist_def_accounts (val ANYELEMENT) RETURNS INTEGER AS '
2195
+ SELECT CASE WHEN $1 >= 1 and $1 <= 30000 THEN 0
2196
+ WHEN $1 > 30000 and $1 <= 60000 THEN 1
2197
+ ELSE 2
2198
+ </pre>
2199
+
2200
+ <h2><a name="hba"></a>Aufsetzen von pool_hba.conf zur Authentifizierung (HBA)</h2>
2201
+ <p>
2202
+ Just like the pg_hba.conf file for PostgreSQL, pgpool supports a similar
2203
+ client authentication function using a configuration file called
2204
+ "pool_hba.conf".
2205
+ </p>
2206
+ <p>
2207
+ When you install pgpool, pool_hba.conf.sample will be installed in
2208
+ "/usr/local/etc", which is the default directory for configuration
2209
+ files. Copy pool_hba.conf.sample as pool_hba.conf and edit it if necessary.
2210
+ By default, pool_hba authentication is enabled. See "6. Setting up
2211
+ pgpool.conf" for more detail.
2212
+ </p>
2213
+ <p>
2214
+ The format of the pool_hba.conf file follows very closely PostgreSQL's
2215
+ pg_hba.conf format.
2216
+ </p>
2217
+ <pre>
2218
+ local DATABASE USER METHOD [OPTION]
2219
+ host DATABASE USER CIDR-ADDRESS METHOD [OPTION]
2220
+ </pre>
2221
+ <p>
2222
+ See "pool_hba.conf.sample" for a detailed explanation of each field.
2223
+ </p>
2224
+ <p>
2225
+ Here are the limitations of pool_hba.
2226
+ <ul>
2227
+ <li>"hostssl" connection type is not supported</li>
2228
+ <p>
2229
+ Though "hostssl" is invalid, pgpool-II 2.3 or later supports SSL.
2230
+ See <a href="#ssl">SSL</a> for more details.
2231
+ </p>
2232
+ <li>"samegroup" for DATABASE field is not supported</li>
2233
+ <p>
2234
+ Since pgpool does not know anything about users in the backend server,
2235
+ the database name is simply checked against entries in the DATABASE
2236
+ field of pool_hba.conf.
2237
+ </p>
2238
+ <li>group names following "+" for USER field is not supported</li>
2239
+ <p>
2240
+ This is for the same reason as for the "samegroup" described above. A
2241
+ user name is simply checked against the entries in the USER field
2242
+ of pool_hba.conf.
2243
+ </p>
2244
+ <li>IPv6 for IP address/mask is not supported</li>
2245
+ <p>
2246
+ pgpool currently does not support IPv6.
2247
+ </p>
2248
+ <li>Only "trust", "reject", "md5" and "pam" for METHOD field are supported</li>
2249
+ <p>
2250
+ Again, this is for the same reason as for the "samegroup" described above.
2251
+ pgpool does not have access to user/password information.
2252
+ </p>
2253
+ <p>
2254
+ To use md5 authentication, you need to register your name and password in
2255
+ "pool_passwd".
2256
+ See <a href="#md5">Authentication / Access Controls</a> for more details.
2257
+ </ul>
2258
+ <p>
2259
+ Note that everything described in this section is about the authentication
2260
+ taking place between a client and pgpool; a client still has to go through
2261
+ the PostgreSQL's authentication process. As far as pool_hba is concerned,
2262
+ it does not matter if a user name and/or database name given by a client
2263
+ (i.e. psql -U testuser testdb) really exists in the backend. pool_hba only
2264
+ cares if a match in the pool_hba.conf is found or not.
2265
+ </p>
2266
+
2267
+ <p>
2268
+ PAM authentication is supported using user information on the host where
2269
+ pgpool is executed. To enable PAM support in pgpool, specify "--with-pam"
2270
+ option to configure:
2271
+ </p>
2272
+ <pre>
2273
+ configure --with-pam
2274
+ </pre>
2275
+ <p>
2276
+ To enable PAM authentication, you need to create a
2277
+ service-configuration file for pgpool in the system's PAM
2278
+ configuration directory (which is usually at "/etc/pam.d"). A sample
2279
+ service-configuration file is installed as "share/pgpool.pam" under
2280
+ the install directory.
2281
+ </p>
2282
+
2283
+ <h2>Setting Query cache method</h2>
2284
+ <p>The Query cache can be used in all modes in pgpool-II.
2285
+ The query cache allow to reuse the SELECT result to boost the performance.
2286
+ Activating it in
2287
+ pgpool.conf is done as follows:</p>
2288
+ <pre>
2289
+ enable_query_cache = true
2290
+ </pre>
2291
+
2292
+ <p>
2293
+ You'll have to create the following table in the System DB too:
2294
+ </p>
2295
+ <pre>
2296
+ CREATE TABLE pgpool_catalog.query_cache (
2297
+ hash TEXT,
2298
+ query TEXT,
2299
+ value bytea,
2300
+ dbname TEXT,
2301
+ create_time TIMESTAMP WITH TIME ZONE,
2302
+ PRIMARY KEY(hash, dbname)
2303
+ );
2304
+ </pre>
2305
+ <p>
2306
+ However, you may have to modify the schema in this statement, if you don't use
2307
+ "pgpool_catalog".
2308
+ </p>
2309
+ <p>
2310
+ <strong>Caution: Current query cache implementation creates cache data on database.
2311
+ Thus enabling query cache may not contribute to boost performance.
2312
+ Contents of query cache is not updated even if the underlying table is get updated.
2313
+ You need to delete the cache data from the cache table or restart pgpool-II with -c (delete cache) option.
2314
+ </strong>
2315
+ </p>
2316
+
2317
+ <h1>Starting/Stopping pgpool-II<a name="start"></a></h1>
2318
+
2319
+ <p>All the backends and the System DB (if necessary) must be started
2320
+ before starting pgpool-II.
2321
+ </p>
2322
+
2323
+ <pre>
2324
+ pgpool [-c][-f config_file][-a hba_file][-F pcp_config_file][-n][-D][-d]
2325
+ </pre>
2326
+ <p>
2327
+ <table>
2328
+ <tr><td>-c<br/>--clear-cache</td><td>deletes query cache</tr>
2329
+ <tr><td>-f config_file<br/>--config-file config-file</td><td>specifies pgpool.conf</tr>
2330
+ <tr><td>-a hba_file<br/>--hba-file hba_file</td><td>specifies pool_hba.conf</tr>
2331
+ <tr><td>-F pcp_config_file<br/>--pcp-password-file</td><td>specifies pcp.conf</tr>
2332
+ <tr><td>-n<br/>--no-daemon</td><td>no daemon mode (terminal is not detached)</tr>
2333
+ <tr><td>-D<br/>--discard-status</td><td>Discard pgpool_status file and do not restore previous status</tr>
2334
+ <tr><td>-d<br/>--debug</td><td>debug mode</tr>
2335
+ </table>
2336
+ There are two ways to stop pgpool-II. One is using a PCP command
2337
+ (described later), the other using a pgpool-II command. Below is an example of the
2338
+ pgpool-II command.
2339
+ </p>
2340
+
2341
+ <pre>
2342
+ pgpool [-f config_file][-F pcp_config_file] [-m {s[mart]|f[ast]|i[mmediate]}] stop
2343
+ </pre>
2344
+ <p>
2345
+ <table>
2346
+ <tr><td><code>-m s[mart]</code><br/><code>--mode s[mart]</code></td>
2347
+ <td>waits for clients to disconnect, and shutdown (default)</td></tr>
2348
+ <tr><td><code>-m f[ast]</code><br/><code>--mode f[ast]</code></td>
2349
+ <td>does not wait for clients; shutdown immediately</td></tr>
2350
+ <tr><td><code>-m i[mmediate]</code><br/><code>--mode i[mmediate]</code></td>
2351
+ <td>the same as <code>'-m f'</code></td></tr> </table>
2352
+ </p>
2353
+ <p>
2354
+ pgpool records backend status into the [logdir]/pgpool_status file. When pgpool
2355
+ restarts, it reads this file and restores the backend status. This will prevent
2356
+ a difference in data among DB nodes which might be caused by following scenario:
2357
+ <ol>
2358
+ <li>A backend suddenly stops and pgpool executes the fail over procedure
2359
+ <li>An update occurs on one of the active DBs through pgpool
2360
+ <li>The administrator decides to stop pgpool
2361
+ <li>Someone decides to restart the stopping DB without notifying the admin
2362
+ <li>The administrator restarts pgpool
2363
+ </ol>
2364
+ </p>
2365
+ <p>
2366
+ If for some reason, for example, the stopped DB has been synced with the
2367
+ active DB by another means, pgpool_status can be removed safely before
2368
+ starting pgpool.
2369
+ </p>
2370
+
2371
+ <h1>Reloading pgpool-II configuration files<a name="reload"></a></h1>
2372
+ <p>pgpool-II can reload configuration files without restarting.
2373
+ </p>
2374
+
2375
+ <pre>
2376
+ pgpool [-c][-f config_file][-a hba_file][-F pcp_config_file] reload
2377
+ </pre>
2378
+ <p>
2379
+ <table>
2380
+ <tr><td>-f config_file<br/>--config-file config-file</td><td>specifies pgpool.conf</tr>
2381
+ <tr><td>-a hba_file<br/>--hba-file hba_file</td><td>specifies pool_hba.conf</tr>
2382
+ <tr><td>-F pcp_config_file<br/>--pcp-password-file</td><td>specifies pcp.conf</tr>
2383
+ </table>
2384
+
2385
+ <p>
2386
+ Please note that some configuration items cannot be changed by
2387
+ reloading. New configuration takes effect after a change for new sessions.
2388
+ </p>
2389
+
2390
+ <h1><a name="show-commands"></a>SHOW commands</h1>
2391
+ <h2>Overview</h2>
2392
+ <p>
2393
+ pgpool-II provides some information via the SHOW command. SHOW is a real SQL
2394
+ statement, but pgPool-II intercepts this command if it asks for specific
2395
+ pgPool-II information. Available options are:
2396
+ <ul>
2397
+ <li>pool_status, to get the configuration</li>
2398
+ <li>pool_nodes, to get the nodes information</li>
2399
+ <li>pool_processes, to get information on pgPool-II processes</li>
2400
+ <li>pool_pools, to get information on pgPool-II pools</li>
2401
+ <li>pool_version, to get the pgPool_II release version</li>
2402
+ </ul>
2403
+ </p>
2404
+ <p>Other than "pool_status" are added since pgpool-II 3.0.
2405
+ <p>
2406
+ <u>Note</u> : The term 'pool' refers to the pool of PostgreSQL sessions owned by one pgpool process,
2407
+ not the whole sessions owned by pgpool.
2408
+ </p>
2409
+ </p>
2410
+ <p>the "pool_status" SQL statement was already available in previous releases,
2411
+ but the other ones have appeared in release 3.0.</p>
2412
+ <h2>pool_status</h2>
2413
+ <p>"SHOW pool_status" sends back the list of configuration parameters with
2414
+ their name, value, and description. Here is an excerpt of the result:
2415
+ <pre>
2416
+ benchs2=# show pool_status;
2417
+ item | value | description
2418
+ -------------------------------+---------------------------------+------------------------------------------------------------------
2419
+ listen_addresses | 127.0.0.1 | host name(s) or IP address(es) to listen to
2420
+ port | 9999 | pgpool accepting port number
2421
+ socket_dir | /tmp | pgpool socket directory
2422
+ num_init_children | 5 | # of children initially pre-forked
2423
+ child_life_time | 300 | if idle for this seconds, child exits
2424
+ </pre>
2425
+ </p>
2426
+ <h2>pool_nodes</h2>
2427
+ <p>"SHOW pool_nodes" sends back a list of all configured nodes. It
2428
+ displays the node id, the hostname, the port, the status, and the weight (only meaningful
2429
+ if you use the load balancing mode). The possible values in the status column
2430
+ are explained in the <a href="#pcp_node_info">pcp_node_info reference</a>.
2431
+ <pre>
2432
+ benchs2=# show pool_nodes;
2433
+ id | hostname | port | status | lb_weight
2434
+ ------+-------------+------+--------+-----------
2435
+ 0 | 127.0.0.1 | 5432 | 2 | 0.5
2436
+ 1 | 192.168.1.7 | 5432 | 3 | 0.5
2437
+ (2 lignes)
2438
+ </pre>
2439
+ </p>
2440
+ <h2>pool_processes</h2>
2441
+ <p>"SHOW pool_processes" sends back a list of all pgPool-II processes waiting
2442
+ for connections and dealing with a connection.
2443
+ </p>
2444
+ <p>
2445
+ It has 6 columns:
2446
+ <ul>
2447
+ <li>pool_pid is the PID of the displayed pgPool-II process</li>
2448
+ <li>start_time is the timestamp of when this process was launched</li>
2449
+ <li>database is the database name of the currently active backend for this process</li>
2450
+ <li>username is the user name used in the connection of the currently active backend for this process</li>
2451
+ <li>create_time is the creation time and date of the connection</li>
2452
+ <li>pool_counter counts the number of times this pool of connections (process) has been used by clients</li>
2453
+ </ul>
2454
+ </p>
2455
+ <p>This view will always return num_init_children lines.</p>
2456
+ <pre>
2457
+ benchs2=# show pool_processes;
2458
+ pool_pid | start_time | database | username | create_time | pool_counter
2459
+ ----------+---------------------+----------+-----------+---------------------+--------------
2460
+ 8465 | 2010-08-14 08:35:40 | | | |
2461
+ 8466 | 2010-08-14 08:35:40 | benchs | guillaume | 2010-08-14 08:35:43 | 1
2462
+ 8467 | 2010-08-14 08:35:40 | | | |
2463
+ 8468 | 2010-08-14 08:35:40 | | | |
2464
+ 8469 | 2010-08-14 08:35:40 | | | |
2465
+ (5 lines)
2466
+ </pre>
2467
+ <h2>pool_pools</h2>
2468
+ <p>"SHOW pool_pools" sends back a list of pools handled by pgPool-II.
2469
+ their name, value, and description. Here is an excerpt of the result:
2470
+ </p>
2471
+ <p>
2472
+ It has 11 columns:
2473
+ <ul>
2474
+ <li>pool_pid is the PID of the pgPool-II process</li>
2475
+ <li>start_time is the time and date when this process was launched</li>
2476
+ <li>pool_id is the pool identifier (should be between 0 and max_pool-1)</li>
2477
+ <li>backend_id is the backend identifier (should be between 0 and the number of configured backends minus one)</li>
2478
+ <li>database is the database name for this process's pool id connection</li>
2479
+ <li>username is the user name for this process's pool id connection</li>
2480
+ <li>create_time is the creation time and date of this connection</li>
2481
+ <li>majorversion and minorversion are the version of the protocol used in this connection</li>
2482
+ <li>pool_counter counts the number of times this connection has been used by clients</li>
2483
+ <li>pool_backendpid is the PID of the PostgreSQL process</li>
2484
+ <li>pool_connected is a true (1) if a frontend is currently using this backend.</li>
2485
+ </ul>
2486
+ </p>
2487
+ <p>It'll always return num_init_children*max_pool lines.</p>
2488
+ <pre>
2489
+ pool_pid | start_time | pool_id | backend_id | database | username | create_time | majorversion | minorversion | pool_counter | pool_backendpid | pool_connected
2490
+ ----------+---------------------+---------+------------+----------+-----------+---------------------+--------------+--------------+--------------+-----------------+----------------
2491
+ 8465 | 2010-08-14 08:35:40 | 0 | 0 | | | | | | | |
2492
+ 8465 | 2010-08-14 08:35:40 | 1 | 0 | | | | | | | |
2493
+ 8465 | 2010-08-14 08:35:40 | 2 | 0 | | | | | | | |
2494
+ 8465 | 2010-08-14 08:35:40 | 3 | 0 | | | | | | | |
2495
+ 8466 | 2010-08-14 08:35:40 | 0 | 0 | benchs | guillaume | 2010-08-14 08:35:43 | 3 | 0 | 1 | 8473 | 1
2496
+ 8466 | 2010-08-14 08:35:40 | 1 | 0 | | | | | | | |
2497
+ 8466 | 2010-08-14 08:35:40 | 2 | 0 | | | | | | | |
2498
+ 8466 | 2010-08-14 08:35:40 | 3 | 0 | | | | | | | |
2499
+ 8467 | 2010-08-14 08:35:40 | 0 | 0 | | | | | | | |
2500
+ 8467 | 2010-08-14 08:35:40 | 1 | 0 | | | | | | | |
2501
+ 8467 | 2010-08-14 08:35:40 | 2 | 0 | | | | | | | |
2502
+ 8467 | 2010-08-14 08:35:40 | 3 | 0 | | | | | | | |
2503
+ 8468 | 2010-08-14 08:35:40 | 0 | 0 | | | | | | | |
2504
+ 8468 | 2010-08-14 08:35:40 | 1 | 0 | | | | | | | |
2505
+ 8468 | 2010-08-14 08:35:40 | 2 | 0 | | | | | | | |
2506
+ 8468 | 2010-08-14 08:35:40 | 3 | 0 | | | | | | | |
2507
+ 8469 | 2010-08-14 08:35:40 | 0 | 0 | | | | | | | |
2508
+ 8469 | 2010-08-14 08:35:40 | 1 | 0 | | | | | | | |
2509
+ 8469 | 2010-08-14 08:35:40 | 2 | 0 | | | | | | | |
2510
+ 8469 | 2010-08-14 08:35:40 | 3 | 0 | | | | | | | |
2511
+ (20 lines)
2512
+ </pre>
2513
+ </p>
2514
+ <h2>pool_version</h2>
2515
+ <p>"SHOW pool_version" displays a string containing the pgPool-II release
2516
+ number. Here is an example of it:
2517
+ <pre>
2518
+ benchs2=# show pool_version;
2519
+ pool_version
2520
+ ------------------------
2521
+ 3.0-dev (umiyameboshi)
2522
+ (1 line)
2523
+ </pre>
2524
+ </p>
2525
+ <h1><a name="online-recovery"></a>Online Recovery</h1>
2526
+ <h2>Overview</h2>
2527
+ <p>
2528
+ pgpool-II, while in replication mode, can sync a database and attach a node
2529
+ while still servicing clients. We call this feature "online recovery".
2530
+ </p>
2531
+
2532
+ <p>
2533
+ A recovery target node must be in the detached state before doing online
2534
+ recovery.
2535
+
2536
+ If you wish to add a PostgreSQL server dynamically, add 'backend_hostname' and
2537
+ its associated parameters and reload pgpool.conf. pgpool-II registers this new
2538
+ node as a detached node.
2539
+ </p>
2540
+
2541
+ <p>
2542
+ <font color="red">caution: Stop autovacuum on the master node (the
2543
+ first node which is up and running). Autovacuum may change the contents
2544
+ of the database and might cause inconsistency after online recovery if
2545
+ it's running. This applies only if you're recovering with a simple copy mecanism, such
2546
+ as the rsync one explained below. This doesn't apply if you're using PostgreSQL's
2547
+ PITR mechanism.</font>
2548
+ </p>
2549
+
2550
+ <p>
2551
+ If the target PostgreSQL server has already started, you need to shut it down.
2552
+ </p>
2553
+
2554
+ <p>
2555
+ pgpool-II performs online recovery in two separated phases. There are a few
2556
+ seconds or minutes when client will be waiting to connect to pgpool-II while a
2557
+ recovery node synchronizes database. It follows these steps:
2558
+
2559
+ <ol>
2560
+ <li> CHECKPOINT
2561
+ <li> First stage of online recovery
2562
+ <li> Wait until all clients have disconnected
2563
+ <li> CHECKPOINT
2564
+ <li> Second stage of online recovery
2565
+ <li> Start up postmaster (perform pgpool_remote_start)
2566
+ <li> Node attach
2567
+ </ol>
2568
+ </p>
2569
+
2570
+ <p>
2571
+ The first step of data synchronization is called "first stage". Data is
2572
+ synchronized during the first stage. In the first stage, data <b>can</b> be
2573
+ updated or retrieved from any table concurrently.
2574
+ </p>
2575
+
2576
+ <p>
2577
+ You can specify a script executed during the first stage. pgpool-II
2578
+ passes three arguments to the script.
2579
+
2580
+ <ol>
2581
+ <li> The database cluster path of a master node.
2582
+ <li> The hostname of a recovery target node.
2583
+ <li> The database cluster path of a recovery target node.
2584
+ </ol>
2585
+ </p>
2586
+
2587
+ <p>
2588
+ Data synchronization is finalized during what is called "second
2589
+ stage". Before entering the second stage, pgpool-II waits until all
2590
+ clients have disconnected. It blocks any new incoming connection until
2591
+ the second stage is over.
2592
+
2593
+ After all connections have terminated, pgpool-II merges updated data between
2594
+ the first stage and the second stage. This is the final data
2595
+ synchronization step.
2596
+ </p>
2597
+
2598
+ <p>
2599
+ <font color="red">
2600
+ Note that there is a restriction about online recovery. If pgpool-II itself
2601
+ is installed on multiple hosts, online recovery does not work
2602
+ correctly, because pgpool-II has to stop all clients during the 2nd stage of
2603
+ online recovery. If there are several pgpool hosts, only one will have
2604
+ received the online recovery command and will block connections.
2605
+ </font>
2606
+ </p>
2607
+
2608
+ <h2> Configuration for online recovery</h2>
2609
+ <p>
2610
+ Set the following parameters for online recovery in pgpool.conf.
2611
+
2612
+ <ul>
2613
+ <li> backend_data_directory
2614
+ <li> recovery_user
2615
+ <li> recovery_password
2616
+ <li> recovery_1st_stage_command
2617
+ <li> recovery_2nd_stage_command
2618
+ </ul>
2619
+ </p>
2620
+
2621
+
2622
+ <h2><a name="installing-c-functions"></a>Installing C language functions</h2>
2623
+ <p>
2624
+ You need to install the following C language function for online recovery into
2625
+ the "template1" database of all backend nodes.
2626
+
2627
+ Its source code is in pgpool-II tarball.
2628
+ </p>
2629
+
2630
+ <pre>
2631
+ pgpool-II-x.x.x/sql/pgpool-recovery/
2632
+ </pre>
2633
+
2634
+ <p>
2635
+ Change directory there and do "make install".
2636
+ </p>
2637
+
2638
+ <pre>
2639
+ % cd pgpool-II-x.x.x/sql/pgpool-recovery/
2640
+ % make install
2641
+ </pre>
2642
+
2643
+ <p>
2644
+ Then, install the SQL function.
2645
+ </p>
2646
+
2647
+ <pre>
2648
+ % cd pgpool-II-x.x.x/sql/pgpool-recovery/
2649
+ % psql -f pgpool-recovery.sql template1
2650
+ </pre>
2651
+
2652
+
2653
+ <h2> Recovery script deployment </h2>
2654
+ <p>
2655
+ We must deploy some data sync scripts and a remote start script into
2656
+ the database cluster directory ($PGDATA). Sample script files are available in
2657
+ pgpool-II-x.x.x/sample directory.
2658
+ </p>
2659
+
2660
+ <h3>Online recovery by PITR</h3>
2661
+ <p>
2662
+ Here is how to do online recovery by Point In Time Recovery (PITR), which is
2663
+ available in PostgreSQL 8.2 and later versions.
2664
+ Note that all PostgreSQL servers involved need to have PITR enabled.
2665
+ </p>
2666
+
2667
+ <p>
2668
+ A script to get a base backup on a master node and copy it to a
2669
+ recovery target node on the first stage is needed. The script can be named
2670
+ "copy-base-backup" for example. Here is the sample script.
2671
+
2672
+ </p>
2673
+
2674
+ <pre>
2675
+ #! /bin/sh
2676
+ DATA=$1
2677
+ RECOVERY_TARGET=$2
2678
+ RECOVERY_DATA=$3
2679
+
2680
+ psql -c "select pg_start_backup('pgpool-recovery')" postgres
2681
+ echo "restore_command = 'scp $HOSTNAME:/data/archive_log/%f %p'" > /data/recovery.conf
2682
+ tar -C /data -zcf pgsql.tar.gz pgsql
2683
+ psql -c 'select pg_stop_backup()' postgres
2684
+ scp pgsql.tar.gz $RECOVERY_TARGET:$RECOVERY_DATA
2685
+ </pre>
2686
+
2687
+ <p>
2688
+ This script puts the master database in backup mode, generates the following
2689
+ recovery.conf:
2690
+ </p>
2691
+ <pre>
2692
+ restore_command = 'scp master:/data/archive_log/%f %p'
2693
+ </pre>
2694
+ performs the backup, then puts the master database out of backup mode and copies
2695
+ the backup on the chosen target node.
2696
+ </p>
2697
+
2698
+ <p>
2699
+ The second stage of the procedure is a script to force an XLOG file switch.
2700
+ This script is named "pgpool_recovery_pitr" here.
2701
+ It enforces a switch of the transaction log.
2702
+ For this purpose, pg_switch_xlog could be used.
2703
+ However it may return <b>before</b> the switch is done and this might lead to
2704
+ failure of the online recovery procedure.
2705
+ Pgpool-II provides a safer function called "pgpool_switch_xlog" which will wait
2706
+ until the transaction log switching is actually finished.
2707
+ pgpool_switch_xlog is installed during the procedure performed in the
2708
+ <a href="#installing-c-functions">Installing C functions</a> section.
2709
+ </p>
2710
+ <p>
2711
+ Here is the sample script.
2712
+ </p>
2713
+ <p>
2714
+ <pre>
2715
+ #! /bin/sh
2716
+ # Online recovery 2nd stage script
2717
+ #
2718
+ datadir=$1 # master dabatase cluster
2719
+ DEST=$2 # hostname of the DB node to be recovered
2720
+ DESTDIR=$3 # database cluster of the DB node to be recovered
2721
+ port=5432 # PostgreSQL port number
2722
+ archdir=/data/archive_log # archive log directory
2723
+
2724
+ # Force to flush current value of sequences to xlog
2725
+ psql -p $port -t -c 'SELECT datname FROM pg_database WHERE NOT datistemplate AND datallowconn' template1|
2726
+ while read i
2727
+ do
2728
+ if [ "$i" != "" ];then
2729
+ psql -p $port -c "SELECT setval(oid, nextval(oid)) FROM pg_class WHERE relkind = 'S'" $i
2730
+ fi
2731
+ done
2732
+
2733
+ psql -p $port -c "SELECT pgpool_switch_xlog('$archdir')" template1
2734
+ </pre>
2735
+ </p>
2736
+
2737
+ <p>
2738
+ This flushing of sequences is only useful in replication mode: in this case, sequences have to have the
2739
+ same starting point on all nodes. It's not useful in master-slave mode.
2740
+
2741
+ The loop in the script forces PostgreSQL to emit current value of all sequences
2742
+ in all databases in the master node to the transaction log so that it is
2743
+ propagated to the recovery target node.
2744
+ </p>
2745
+
2746
+ <p>
2747
+ We deploy these scripts into the $PGDATA directory.
2748
+ </p>
2749
+ <p>
2750
+ Finally, we edit pgpool.conf.
2751
+
2752
+ <pre>
2753
+ recovery_1st_stage_command = 'copy-base-backup'
2754
+ recovery_2nd_stage_command = 'pgpool_recovery_pitr'
2755
+ </pre>
2756
+
2757
+ </p>
2758
+
2759
+ <p>
2760
+ We have finished preparing online recovery by PITR.
2761
+ </p>
2762
+
2763
+ <h4><p>pgpool_remote_start</p></h4>
2764
+ <p>
2765
+ This script starts up the remote host's postmaster process.
2766
+ pgpool-II executes it the following way.
2767
+ </p>
2768
+
2769
+ <pre>
2770
+ % pgpool_remote_start remote_host remote_datadir
2771
+ remote_host: Hostname of a recovery target.
2772
+ remote_datadir: Database cluster path of a recovery target.
2773
+ </pre>
2774
+
2775
+ <p>
2776
+ In this sample script, we start up the postmaster process over ssh.
2777
+ So you need to be able to connect over ssh without a password for it to work.
2778
+ </p>
2779
+
2780
+ <p>
2781
+ If you recover with PITR, you need to deploy a base backup. PostgreSQL will
2782
+ automatically start up doing a PITR recovery. Then it will accept
2783
+ connections.
2784
+ </p>
2785
+
2786
+ <pre>
2787
+ #! /bin/sh
2788
+ DEST=$1
2789
+ DESTDIR=$2
2790
+ PGCTL=/usr/local/pgsql/bin/pg_ctl
2791
+
2792
+ # Deploy a base backup
2793
+ ssh -T $DEST 'cd /data/; tar zxf pgsql.tar.gz' 2>/dev/null 1>/dev/null < /dev/null
2794
+ # Startup PostgreSQL server
2795
+ ssh -T $DEST $PGCTL -w -D $DESTDIR start 2>/dev/null 1>/dev/null < /dev/null &
2796
+ </pre>
2797
+
2798
+ <h3>Online recovery with rsync.</h3>
2799
+ <p>
2800
+ PostgreSQL 7.4 does not have PITR.
2801
+ PostgreSQL 8.0 and 8.1 cannot force to switch transaction log.
2802
+ So rsync can be used to do online recovery.
2803
+ In the "sample" directory of pgpool-II's tarball,
2804
+ there is a recovery script named "pgpool_recovery". It uses the rsync
2805
+ command. pgpool-II calls the script with three arguments.
2806
+ </p>
2807
+
2808
+ <pre>
2809
+ % pgpool_recovery datadir remote_host remote_datadir
2810
+ datadir: Database cluster path of a master node.
2811
+ remote_host: Hostname of a recovery target node.
2812
+ remote_datadir: Database cluster path of a recovery target node.
2813
+ </pre>
2814
+
2815
+ <p>
2816
+ This script copies physical files with rsync over ssh. So you need to
2817
+ be able to connect over ssh without a password.
2818
+ </p>
2819
+
2820
+ <p>
2821
+ Note about rsync:
2822
+ <ul>
2823
+ <li>-c (or --checksum) option is required to enable reliable file tranmitting
2824
+
2825
+ <li>-z (or --compress) option does compression before transmitting
2826
+ data. This will be great for slower connection, but it might add too much
2827
+ CPU overhead for a 100Mbit or faster connections. In this case you
2828
+ might want not to use this option.
2829
+
2830
+ <li>rsync 3.0.5 has great speed performance
2831
+ improvements (50% faster according to a report from pgpool-general
2832
+ mailing list.
2833
+ </ul>
2834
+
2835
+ </p>
2836
+
2837
+ <p>
2838
+ If you use pgpool_recovery, add the following lines into pgpool.conf.
2839
+
2840
+ <pre>
2841
+ recovery_1st_stage_command = 'pgpool_recovery'
2842
+ recovery_2nd_stage_command = 'pgpool_recovery'
2843
+ </pre>
2844
+ </p>
2845
+
2846
+ <h2>How to perform online recovery</h2>
2847
+ <p>
2848
+ In order to do online recovery, use the pcp_recovery_node command or
2849
+ pgpoolAdmin.
2850
+ </p>
2851
+
2852
+ <p>
2853
+ Note that you need to pass a large number to the first argument of
2854
+ pcp_recovery_node. It is the timeout parameter in seconds. If you use
2855
+ pgpoolAdmin, set "_PGPOOL2_PCP_TIMEOUT " parameter to a large number in
2856
+ pgmgt.conf.php.
2857
+ </p>
2858
+
2859
+ <h1>PostgreSQL version up using online recovery</h1>
2860
+ <h2>replication mode case</h2>
2861
+ <p>
2862
+ You can update PostgreSQL on each node without stopping pgpool-II if pgpool-II operated in replication mode.
2863
+ Please note that active sessions from clients to pgpool-II will be disconnected while disconnecting and attaching DB nodes.
2864
+ Also please note that you cannot do major version up in the method described below
2865
+ (i.e. the version up should not require dump/restore).
2866
+ </p>
2867
+
2868
+ <p>
2869
+ <ol>
2870
+ <li><p>
2871
+ Prepare online recovery.</p>
2872
+ <li><p>Version up should perform nodes which are not master node first.
2873
+ Stop PostgreSQL on a non-master node.
2874
+ Pgpool-II will detect PostgreSQL termination and degenerate emitting logs below.
2875
+ At this point all sessions connected to pgpool-II disconnected.
2876
+ <pre>
2877
+ 2010-07-27 16:32:29 LOG: pid 10215: set 1 th backend down status
2878
+ 2010-07-27 16:32:29 LOG: pid 10215: starting degeneration. shutdown host localhost(5433)
2879
+ 2010-07-27 16:32:29 LOG: pid 10215: failover_handler: set new master node: 0
2880
+ 2010-07-27 16:32:29 LOG: pid 10215: failover done. shutdown host localhost(5433)
2881
+ </pre>
2882
+ </p>
2883
+
2884
+ <li><p>
2885
+ Version up PostgreSQL on the stopping node.
2886
+ You can overwrite old PostgreSQL, we recommend move old PostgreSQL somewhere so that you could recover it just in case however.
2887
+ </p>
2888
+
2889
+ <li><p>
2890
+ If you install new PostgreSQL in different location from the old one and do not want to update your recovery script, you need to match the path by using tools including symbolic link.
2891
+ If you choose to overwrite, you can skip following steps till installation of C function step.
2892
+ You can execute online recovery immediately.
2893
+ </p>
2894
+
2895
+ <li><p>
2896
+ Change installation directory of old PostgreSQL.
2897
+ Installting directory of PostgreSQL is supposed to be /usr/local/pgsql in following description.
2898
+ <pre>
2899
+ $ mv /usr/local/pgsql /usr/local/pgsql-old
2900
+ </pre>
2901
+ </p>
2902
+
2903
+ <li><p>
2904
+ Create a symblic link to the localtion where newer version of PostgreSQL installed.
2905
+ This allow you to continue to use command search path you currently use.
2906
+ Installting directory of newer PostgreSQL is supposed to be /usr/local/pgsql-new in following description.
2907
+ <pre>
2908
+ $ ln -s /usr/local/pgsql-new /usr/local/pgsql
2909
+ </pre>
2910
+ </p>
2911
+
2912
+ <li><p>
2913
+ If database directory is located under older PostgreSQL installation directory, you should create or copy so that newer PostgreSQL can access it.
2914
+ We use symbolic link in the following example.
2915
+ <pre>
2916
+ $ ln -s /usr/local/pgsql-old/data /usr/local/pgsql/data
2917
+ </pre>
2918
+ </p>
2919
+
2920
+ <li><p>
2921
+ Install C functions into PostgreSQL. "Installing C functions" section may help you.
2922
+ Because online recovery copies database cluster, the last step installing functions using psql is not neccessary.
2923
+ Do make install.
2924
+ </p>
2925
+
2926
+ <li><p>
2927
+ Do online recovery. You are done with one node version up.
2928
+ To execute online recovery, you can use pcp_recovery_node or pgpoolAdmin.
2929
+ </p>
2930
+
2931
+ <li><p>
2932
+ Repeat steps above on each node. In the very last master node should be updated.
2933
+ You are done.
2934
+ </p>
2935
+ </ol>
2936
+
2937
+ <h2>If you are using streaming replication</h2>
2938
+ <p>
2939
+ You can update standby PostgreSQL server without stopping pgpool-II.
2940
+ </p>
2941
+
2942
+ <p>
2943
+ The procedure to update standby PostgreSQL servers are same as the one of replication mode.
2944
+ Please refer to "Online recovery with Streaming Replication" to set up recovery_1st_stage_command and recovery_2nd_stage_command.
2945
+ </p>
2946
+
2947
+ <p>
2948
+ You cannot version up primary server without stopping pgpool-II.
2949
+ You need to stop pgpool-II while updating primary server.
2950
+ The procedure to update primary PostgreSQL server is same as the one standby server.
2951
+ The procedure to update primary PostgreSQL server is as follows:
2952
+ <ol>
2953
+ <li>Stop pgpool-II
2954
+ <li>Stop primary PostgreSQL
2955
+ <li>Update primary PostgreSQl
2956
+ <li>Start primary PostgreSQL
2957
+ <li>Start pgpool-II
2958
+ </ol>
2959
+ </p>
2960
+
2961
+ <h1><a name="backup"></a>Backup</h1>
2962
+ <p>
2963
+ To back up backend PostgreSQL servers and system DB, you can physical
2964
+ backup, logical backup (pg_dump, pg_dumpall) and PITR in the same manner as PostgreSQL.
2965
+ Please note that using logical backup and PITR should be performed directory PostgreSQL,
2966
+ rather than via pgpool-II to avoid errors caused by load_balance_mode and replicate_select.
2967
+ </p>
2968
+
2969
+ <h2>replication mode and master/slave mode</h2>
2970
+ <p>
2971
+ If pgpool-II is operated in replication mode or master/slave mode, take a backup on one DB nodes in the cluster.
2972
+ </p>
2973
+
2974
+ <p>
2975
+ If you are using master/slave mode and asynchronous replication
2976
+ systems(Slony-I and streaming replication) and need the latest backup, you should take a backup on the master node.
2977
+ </p>
2978
+
2979
+ <p>
2980
+ pg_dump takes ACCESS SHARE lock on database. Commands taking ACCESS
2981
+ EXECUTE lock, such as ALTER TABLE, DROP TABLE, TRUNCATE, REINDEX,
2982
+ CLUSTER and VACUUM FULL will wait for the completion of pg_dump because
2983
+ of lock conflict. Also this may affect the primary node even if you are
2984
+ doing pg_dump on standby.
2985
+ </p>
2986
+
2987
+ <h2>Parallel mode</h2>
2988
+ <p>
2989
+ If you are using parallel mode and need to take a consistent backup, you need to stop pgpool-II.
2990
+ </p>
2991
+
2992
+ <p>
2993
+ To use logical backup, stop applications and pgpool-II then perform pg_dump or pg_dumpall on all nodes.
2994
+ After finishing backup, start pgpool-II then start applications.
2995
+ </p>
2996
+
2997
+ <p>
2998
+ To use PITR, please make sure that system times are identical on all
2999
+ nodes. Prepare archive logging and take base backup. After finishing
3000
+ backup, stop and restart applications or pgpool-II. Record the time of
3001
+ stop and start. This temporary stop will make consistent state among
3002
+ all over cluster. If you need to restore form the base backup and
3003
+ archive log, set recovery_target_time of recovery.conf in the middle of
3004
+ the start/stop time.
3005
+ </p>
3006
+
3007
+ <h2>Backuping of system DB</h2>
3008
+ <p>
3009
+ You need to backup system DB if pgpool-II is operated in parallel query
3010
+ mode or if you are using query cache.
3011
+ Backup database specified by system_db_dbname in pgpool.conf.
3012
+
3013
+ <h1><a name="deploy"></a>Deploying pgpool-II</a></h1>
3014
+ <p>
3015
+ pgpool-II can run on a dedicated server, on the server where application
3016
+ server is running on or other servers. In this section we discuss how
3017
+ to make those deployments and pros and cons.
3018
+ </p>
3019
+
3020
+ <p>
3021
+ <ul>
3022
+ <dt>Dedicated server
3023
+ <dd>
3024
+ <p>
3025
+ Pgpool-II is running on a dedicated server.
3026
+ It's simple and pgpool-II is not affected by other server softwares.
3027
+ Obvious cons is you need to by more hardware.
3028
+ Also pgpool-II can be a single point of failure with this configuration
3029
+ (you can avoid this by using pgpool-HA described somewhere below).
3030
+ </p>
3031
+
3032
+ <dt>Deploying on a web server or application server
3033
+ <dd>
3034
+ <p>
3035
+ Deploying pgpool-II on a server where Apache, JBoss, Tomcat or other web
3036
+ server and application servers.
3037
+ Since communication between pgpool-II and web servers and application servers
3038
+ is within a local machine, socket communication can be faster than inter sever communication.
3039
+ Also if you are using multiple web serves or application servers, you can avoid
3040
+ the single point of failure problem
3041
+ (in this case you must have identical pgpool.conf on each pgpool-II instanace).
3042
+ There are seveal things you should care about in this configuration:
3043
+ </p>
3044
+ <ul>
3045
+ <li>If the communication between pgpool-II and DB servers is not stable, it is possible
3046
+ that DB node #1 is down from a point of a pgpool-II instance, while it is up from other pgpool-II instance's point of view.
3047
+ To avoid this, you can multiplex the network connection.
3048
+ <li>While executing online recovery in replication mode, you need to stop all pgpool-II instances except the one which is doing online recovery.
3049
+ Othewise DB can be running into inconsistent state.
3050
+ In master slave mode+streaming replication mode, you do not need to stop other pgpool-II instances.
3051
+ You should not execute online recovery at the same time on multiple pgpool-II instances however.
3052
+ </ul>
3053
+ </p>
3054
+
3055
+ <dt>Running pgpool-II on DB server
3056
+ <dd>
3057
+ <p>
3058
+ Running pgpool-II on the server as PostgreSQL is running on.
3059
+ You can avoid the single point of failure problem of pgpool-II with configuration.
3060
+ And obviously you do need to buy additional dedicated server.
3061
+ Problem with this configuration is, application need to aware that which DB server they should connect to.
3062
+ To solve the problem you can use virtual IP with pgpool-HA.
3063
+ </ul>
3064
+ </p>
3065
+
3066
+ <h2>About pgpool-HA</h2>
3067
+ <p>
3068
+ Pgpool-HA is a high availability software for pgpool-II using hearbeat.
3069
+ Pgpool-HA is a sub probject of pgpool project as well as pgpool-II.
3070
+ Pgpool-HA can be available from pgpool development site as an open source softeware.
3071
+ </p>
3072
+
3073
+ <h1><a name="troubleshooting"></a>Troubleshooting</h1>
3074
+ <p>
3075
+ This section describes problems and their workarounds while you are using
3076
+ pgpool-II.
3077
+ </p>
3078
+ <p>
3079
+ <ul>
3080
+
3081
+ <dt>Health check failed
3082
+ <dd>
3083
+ <p>
3084
+ Pgpool-II's health checking feature detects DB nodes failure.
3085
+ </p>
3086
+ <p>
3087
+ <pre>
3088
+ 2010-07-23 16:42:57 ERROR: pid 20031: health check failed. 1 th host foo at port 5432 is down
3089
+ 2010-07-23 16:42:57 LOG: pid 20031: set 1 th backend down status
3090
+ 2010-07-23 16:42:57 LOG: pid 20031: starting degeneration. shutdown host foo(5432)
3091
+ 2010-07-23 16:42:58 LOG: pid 20031: failover_handler: set new master node: 0
3092
+ 2010-07-23 16:42:58 LOG: pid 20031: failover done. shutdown host foo(5432)
3093
+ </pre>
3094
+ </p>
3095
+ <p>
3096
+ The log shows that the DB node 1 (host foo) goes down and disconnected (shutdown)
3097
+ from pgpool, and then that DB node 0 becomes new master.
3098
+ Check DB node 1 and remove the cause of failure. After that perform an online
3099
+ recovery against DB node 1 if possible.
3100
+ </p>
3101
+
3102
+ <dt>Failed to read kind from frontend
3103
+ <dd>
3104
+ <p>
3105
+ <pre>
3106
+ 2010-07-26 18:43:24 LOG: pid 24161: ProcessFrontendResponse: failed to read kind from frontend. frontend abnormally exited
3107
+ </pre>
3108
+ <p>
3109
+ This log indicates that the frontend program didn't disconnect properly from
3110
+ pgpool-II.
3111
+ The possible causes are: bugs of client applications, forced termination (kill)
3112
+ of a client application, or temporary network failure.
3113
+ This kind of events don't lead to a DB destruction or data consistency problem.
3114
+ It's only a warning about a protocol violation.
3115
+ It is advised that you check the applications and networks if the
3116
+ message keeps on occurring.
3117
+ </p>
3118
+
3119
+ <dt>Kind mismatch errors
3120
+ <dd>
3121
+ <p>
3122
+ It is possible that you get this error when pgpool-II operates in
3123
+ replication mode.
3124
+ </p>
3125
+ <pre>
3126
+ 2010-07-22 14:18:32 ERROR: pid 9966: kind mismatch among backends. Possible last query was: "FETCH ALL FROM c;" kind details are: 0[T] 1[E: cursor "c" does not exist]
3127
+ </pre>
3128
+ <p>
3129
+ Pgpool-II waits for responses from the DB nodes after sending an SQL command
3130
+ to them.
3131
+ This message indicates that not all DB nodes returned the same kind of response.
3132
+ You'll get the SQL statement which possibly caused the error after "Possible last query
3133
+ was:".
3134
+ Then the kind of response follows. If the response indicates an error, the
3135
+ error message from PostgreSQL is shown.
3136
+ Here you see "0[T]" displaying the DB node responses: "0[T]"(starting
3137
+ to send row description), and "1[E" indicates that DB node 1 returns an
3138
+ error with message "cursor "c" does not exist", while DB node 0 sends a row
3139
+ description.
3140
+ <p>
3141
+ Caution: You will see this error when operating in master/slave mode as
3142
+ well.
3143
+ For example, even in the master/slave mode, SET command will be basically sent
3144
+ to all DB nodes to keep all the DB nodes in the same state.
3145
+ </p>
3146
+ <p>
3147
+ Check the databases and resync them using online recovery if you find
3148
+ that they are out of sync.
3149
+ </p>
3150
+
3151
+ <p>
3152
+ <dt>Pgpool detected difference of the number of inserted, updated or deleted tuples
3153
+ <dd>
3154
+ <p>
3155
+ In replication mode, pgpool-II detects a different number of
3156
+ INSERT/UPDATE/DELETE rows on affected nodes.
3157
+ </p>
3158
+ <p>
3159
+ <pre>
3160
+ 2010-07-22 11:49:28 ERROR: pid 30710: pgpool detected difference of the number of inserted, updated or deleted tuples. Possible last query was: "update t1 set i = 1;"
3161
+ 2010-07-22 11:49:28 LOG: pid 30710: ReadyForQuery: Degenerate backends: 1
3162
+ 2010-07-22 11:49:28 LOG: pid 30710: ReadyForQuery: Affected tuples are: 0 1
3163
+ </pre>
3164
+ <p>
3165
+ In the example above, the returned number of updated rows by "update t1 set i = 1"
3166
+ was different among DB nodes.
3167
+ The next line indicates that DB 1 got degenerated (disconnected) as a
3168
+ consequence, and that the number of affected rows for DB node 0 was 0, while
3169
+ for DB node 1 that was 1.
3170
+ </p>
3171
+ <p>
3172
+ Stop the DB node which is suspected of having wrong data and do an online
3173
+ recovery.
3174
+ </ul>
3175
+
3176
+
3177
+ <h1>Restrictions<a name="restriction"></a></h1>
3178
+
3179
+ <p>
3180
+ <h2>Functionalities of PostgreSQL</h2>
3181
+ <p>
3182
+ <ul>
3183
+ <li>If you use pg_terminate_backend() to stop a backend, this will trigger
3184
+ a failover.
3185
+ The reason why this happens is that PostgreSQL sends exactly the same
3186
+ message for a terminated backend as for a full postmaster shutdown.
3187
+ There is no workaround as of today. Please do not use this function.
3188
+ </ul>
3189
+
3190
+ <p>
3191
+ <h2><a name="md5"></a>Authentication / Access Controls</h2>
3192
+
3193
+ <p>
3194
+ <ul>
3195
+ <li>In the replication mode or master/slave mode, trust, clear text
3196
+ password, and pam methods are supported. md5 in also supported since pgpool-II 3.0.
3197
+
3198
+ md5 is supported by using "pool_passwd". Here are the steps to enable
3199
+ md5 authentication:
3200
+ <ol>
3201
+ <li>Login as the database's operating system user and type
3202
+ "pg_md5 --md5auth --username=<your_username> <your_passwd>"
3203
+ user name and md5 encrypted password are registered into
3204
+ pool_passwd.
3205
+ If pool_passwd does not exist yet, pg_md5 command will
3206
+ automatically create it for you.</li>
3207
+ <li> The format of pool_passwd is "username:encrypted_passwd".</li>
3208
+ <li>You also need to add an appropriate md5 entry to pool_hba.conf.
3209
+ See <a href="#hba">Setting up pool_hba.conf for client
3210
+ authentication (HBA)</a> for more details.</li>
3211
+ <li>Please note that the user name and password must be
3212
+ identical to those registered in PostgreSQL.</li>
3213
+ </ol>
3214
+
3215
+ </li>
3216
+ <li>In all the other modes, trust, clear text password, crypt, md5,
3217
+ and pam methods are supported.</li>
3218
+ <li>pgpool-II does not support pg_hba.conf-like access controls. If
3219
+ TCP/IP connections are enabled, pgpool-II accepts all the
3220
+ connections from any host. If needed, use iptables and such to
3221
+ control access from other hosts. (PostgreSQL server accepting
3222
+ pgpool-II connections can use pg_hba.conf, of course).</li>
3223
+ </ul>
3224
+ </p>
3225
+
3226
+ <h2>Large objects</h2>
3227
+ <p>
3228
+ pgpool-II 2.3.2 or later supports large object replication if the backend is
3229
+ PostgreSQL 8.1 or later.
3230
+ For this, you need to
3231
+ enable <a href="#lobj_lock_table">lobj_lock_table</a> directive in pgpool.conf.
3232
+ Large object replication using backend function lo_import is not supported, however.
3233
+ </p>
3234
+
3235
+ <h2>Temporary tables in master/slave mode</h2>
3236
+ <p>
3237
+ Creating/inserting/updating/deleting temporary tables are always executed on the
3238
+ master(primary).
3239
+ With pgpool-II 3.0 or later, SELECT on these tables is executed on master as well.
3240
+ However if the temporary table name is used as a literal in SELECT, there's no
3241
+ way to detect it, and the SELECT will be load balanced.
3242
+ That will trigger a "not found the table" error or will find another table
3243
+ having same name.
3244
+ To avoid the problem, use /*NO LOAD BALANCE*/ SQL comment.
3245
+ </p>
3246
+ <p>
3247
+ <pre>
3248
+ Sample SELECT which causes a problem:
3249
+ SELECT 't1'::regclass::oid;
3250
+ </pre>
3251
+ </p>
3252
+ <p>
3253
+ psql's \d command uses literal table names.
3254
+ pgpool-II 3.0 or later checks if the SELECT includes any access to system
3255
+ catalogs and always send these queries to the master.
3256
+ Thus we avoid the problem.
3257
+ </p>
3258
+
3259
+ <h2>Functions, etc. In Replication Mode</h2>
3260
+
3261
+ <p>There is no guarantee that any data provided using a context-dependent
3262
+ mechanism (e.g. random number, transaction ID, OID, SERIAL, sequence), will be
3263
+ replicated correctly on multiple backends.</p>
3264
+ <p>For SERIAL, enabling insert_lock will help replicating data.
3265
+ insert_lock also helps SELECT setval() and SELECT nextval().</p>
3266
+
3267
+ <p>In pgpool-II 2.3 or later, INSERT/UPDATE using CURRENT_TIMESTAMP,
3268
+ CURRENT_DATE, now() will be replicated correctly. INSERT/UPDATE for tables
3269
+ using CURRENT_TIMESTAMP, CURRENT_DATE, now() as their DEFAULT values will also
3270
+ be replicated correctly.
3271
+ This is done by replacing those functions by constants fetched from master at
3272
+ query execution time.
3273
+ There are a few limitations however:
3274
+ <ul>
3275
+ <li>In pgpool-II 3.0 or before, the calculation of temporal data in table default value is not accurate in
3276
+ some cases. For example, the following table definition:
3277
+ <pre>
3278
+ CREATE TABLE rel1(
3279
+ d1 date DEFAULT CURRENT_DATE + 1
3280
+ )
3281
+ </pre>
3282
+ is treated the same as:
3283
+ <pre>
3284
+ CREATE TABLE rel1(
3285
+ d1 date DEFAULT CURRENT_DATE
3286
+ )
3287
+ </pre>
3288
+ <p>
3289
+ pgpool-II 3.1 or later handles these cases correctly.
3290
+ Thus the column "d1" will have tomorrow as the default value.
3291
+ However this enhancement does not apply if extended protocols(used in JDBC, PHP PDO for example) or PREPARE are used.
3292
+ </p>
3293
+ <p>
3294
+ Please note that if the column type is not a temporal one, rewriting is
3295
+ not performed. Such example:
3296
+ <pre>
3297
+ foo bigint default (date_part('epoch'::text,('now'::text)::timestamp(3) with time zone) * (1000)::double precision)
3298
+ </pre>
3299
+ </p>
3300
+ <li>Suppose we have the following table:
3301
+ <pre>
3302
+ CREATE TABLE rel1(
3303
+ c1 int,
3304
+ c2 timestamp default now()
3305
+ )
3306
+ </pre>
3307
+ We can replicate
3308
+ <pre>
3309
+ INSERT INTO rel1(c1) VALUES(1)
3310
+ </pre>
3311
+ since this turn into
3312
+ <pre>
3313
+ INSERT INTO rel1(c1, c2) VALUES(1, '2009-01-01 23:59:59.123456+09')
3314
+ </pre>
3315
+ However,
3316
+ <pre>
3317
+ INSERT INTO rel1(c1) SELECT 1
3318
+ </pre>
3319
+ cannot to be transformed, thus cannot be properly replicated in the current implementation.
3320
+ Values will still be inserted, with no transformation at all.
3321
+ </ul>
3322
+ </p>
3323
+ <p>Tables created by <code>CREATE TEMP TABLE</code> will be deleted at the end of
3324
+ the session by specifying DISCARD ALL in reset_query_list if you are using
3325
+ PostgreSQL 8.3 or later.
3326
+ </p>
3327
+ <p>
3328
+ For 8.2.x or earlier, <code>CREATE TEMP TABLE</code> will not be
3329
+ deleted after exiting a session. It is because of the connection
3330
+ pooling which, from PostgreSQL's backend point of view, keeps the
3331
+ session alive. To avoid this, you must explicitly drop the
3332
+ temporary tables by issuing <code>DROP TABLE</code>, or use <code>CREATE TEMP
3333
+ TABLE ... ON COMMIT DROP</code> inside the transaction block.</p>
3334
+
3335
+ <h2>Queries</h2>
3336
+
3337
+ <p>Here are the queries which cannot be processed by pgpool-II</p>
3338
+
3339
+ <h3>INSERT (for parallel mode)</h3>
3340
+
3341
+ <p>You cannot use <code>DEFAULT</code> with the
3342
+ partitioning key column. For example, if the column x in the table t
3343
+ was the partitioning key column,
3344
+
3345
+ <pre>
3346
+ INSERT INTO t(x) VALUES (DEFAULT);
3347
+ </pre>
3348
+ <p>
3349
+ is invalid. Also, functions cannot be used for this value either.
3350
+ </p>
3351
+
3352
+ <pre>
3353
+ INSERT INTO t(x) VALUES (func());
3354
+ </pre>
3355
+ <p>
3356
+ Constant values must be used to INSERT with the partitioning
3357
+ key. <code>SELECT INTO</code> and <code>INSERT INTO ... SELECT</code>
3358
+ are also not supported.
3359
+ </p>
3360
+
3361
+ <h3>UPDATE (for parallel mode)</h3>
3362
+
3363
+ <p>Data consistency between the backends may be lost if the
3364
+ partitioning key column values are updated. pgpool-II does not
3365
+ re-partition the updated data.</p>
3366
+
3367
+ <p>A transaction cannot be rolled back if a query has caused an error
3368
+ on some backends due to a constraint violation.</p>
3369
+
3370
+ <p>If a function is called in the <code>WHERE</code> clause, that
3371
+ query might not be executed correctly, for example:
3372
+ <pre>
3373
+ UPDATE branches set bid = 100 where bid = (select max(bid) from beances);
3374
+ </pre>
3375
+ </p>
3376
+
3377
+ <h3>SELECT ... FOR UPDATE (for parallel mode)</h3>
3378
+
3379
+ <p>If a function is called in the <code>WHERE</code> clause, that
3380
+ query might not be executed correctly. For example:
3381
+ <pre>
3382
+ SELECT * FROM branches where bid = (select max(bid) from beances) FOR UPDATE;
3383
+ </pre>
3384
+ </p>
3385
+
3386
+ <h3>COPY (for parallel mode)</h3>
3387
+
3388
+ <p><code>COPY BINARY</code> is not supported. Copying from files is
3389
+ also not supported. Only <code>COPY FROM STDIN</code> and <code>COPY
3390
+ TO STDOUT</code> are supported.</p>
3391
+
3392
+ <h3>ALTER/CREATE TABLE (for parallel mode)</h3>
3393
+
3394
+ <p>To update the partitioning rule, pgpool-II must be restarted in
3395
+ order to read them from the System DB.</p>
3396
+
3397
+ <h3>Transaction (for parallel mode)</h3>
3398
+
3399
+ <p><code>SELECT</code> statements executed inside a transaction block
3400
+ will be executed in a separate transaction. Here is an example:
3401
+
3402
+ <pre>
3403
+ BEGIN;
3404
+ INSERT INTO t(a) VALUES (1);
3405
+ SELECT * FROM t ORDER BY a; <-- INSERT above is not visible from this SELECT statement
3406
+ END;
3407
+ </pre>
3408
+
3409
+ <h3>Views / Rules (for parallel mode)</h3>
3410
+
3411
+ <p>
3412
+ The same definition will be created on all the backends for views and rules.
3413
+ </p>
3414
+
3415
+ <pre>
3416
+ SELECT * FROM a, b where a.i = b.i
3417
+ </pre>
3418
+ <p>
3419
+ <code>JOIN</code>s like above will be executed on each backend, and
3420
+ then merged with the results returned by each backend. Views and Rules
3421
+ that join across the nodes cannot be created.
3422
+ However, to JOIN tables that access data only in the same node, a VIEW can be made.
3423
+ This VIEW has to be registered in the pgpool_catalog.dist_def table. A col_name and
3424
+ a dist_def_func will have to be registered too. These are used when an insert is
3425
+ performed on the view.
3426
+ </p>
3427
+
3428
+ <h3>Functions / Triggers (for parallel mode)</h3>
3429
+
3430
+ <p>The same definition will be created on all the backends for
3431
+ functions. Joining across the nodes, and accessing data on the other nodes cannot
3432
+ be performed inside the functions.</p>
3433
+
3434
+ <h3>Extended Query Protocol (for parallel mode)</h3>
3435
+
3436
+ <p>The extended query protocol used by JDBC drivers, etc. is not
3437
+ supported. The simple query protocol must be used. This means you can't use
3438
+ prepared statements.</p>
3439
+
3440
+ <h3>Natural Join (for parallel mode)</h3>
3441
+
3442
+ <p>The Natural Join is not supported.
3443
+ "ON join condition" or "USING (join_column)" must be used.</p>
3444
+
3445
+ <h3>USING CLAUSE (for parallel mode)</h3>
3446
+
3447
+ <p>The USING CLAUSE is converted to an ON CLAUSE by the query rewrite process.
3448
+ Therefore, when "*" is used at target list, the joined column(s) appear twice.</p>
3449
+ <p>
3450
+ Here is an example:
3451
+ </p>
3452
+ <p><pre>
3453
+ =# SELECT * FROM t1 JOIN t2 USING(id);
3454
+ id | t | t
3455
+ ----+-----+-------
3456
+ 1 | 1st | first
3457
+ (1 row)
3458
+ </pre></p>
3459
+ <p>
3460
+ In the rewrite process "USING" is translated into "ON". So the
3461
+ effective result is as follows:
3462
+ </p><p><pre>
3463
+ =# SELECT * FROM t1 JOIN t2 ON t1.id = t2.id;
3464
+ id | t | id | t
3465
+ ----+-----+----+-------
3466
+ 1 | 1st | 1 | first
3467
+ (1 row)
3468
+ </pre>
3469
+ </p>
3470
+ <p>
3471
+ Notice that column "t" is duplicated.
3472
+ </p>
3473
+
3474
+ <h3>Multi-byte Characters (for all modes)</h3>
3475
+
3476
+ <p>pgpool-II does not translate between different multi-byte
3477
+ characters. The encoding for the client, backend and System DB must be
3478
+ the same.</p>
3479
+
3480
+ <h3>Multi-statement Query (for all modes)</h3>
3481
+ <p>
3482
+ pgpool-II cannot process multi-statement queries.
3483
+ </p>
3484
+
3485
+ <h3>Deadlocks (for parallel mode)</h3>
3486
+
3487
+ <p>Deadlocks across the backends cannot be detected. For example:
3488
+ </p>
3489
+ <pre>
3490
+ (tellers table is partitioned using the following rule)
3491
+ tid <= 10 --> node 0
3492
+ tid >= 10 --> node 1
3493
+
3494
+ A) BEGIN;
3495
+ B) BEGIN;
3496
+ A) SELECT * FROM tellers WHERE tid = 11 FOR UPDATE;
3497
+ B) SELECT * FROM tellers WHERE tid = 1 FOR UPDATE;
3498
+ A) SELECT * FROM tellers WHERE tid = 1 FOR UPDATE;
3499
+ B) SELECT * FROM tellers WHERE tid = 11 FOR UPDATE;
3500
+ </pre>
3501
+ <p>
3502
+ In the case above, a single node cannot detect the deadlock, so
3503
+ pgpool-II will wait for the response indefinitely. This phenomenon
3504
+ can occur with any query that acquires row level locks.
3505
+ </p>
3506
+ <p>Also, if a deadlock occurs in one node, transaction states in each
3507
+ node will not be consistent. Therefore, pgpool-II terminates the
3508
+ process if a deadlock is detected.
3509
+ </p>
3510
+ <pre>
3511
+ pool_read_kind: kind does not match between master(84) slot[1] (69)
3512
+ </pre>
3513
+
3514
+ <h3>Schemas (for parallel mode)</h3>
3515
+
3516
+ <p>Objects in a schema other than public must be fully qualified like:
3517
+ </p>
3518
+ <pre>
3519
+ schema.object
3520
+ </pre>
3521
+ <p>
3522
+ pgpool-II cannot resolve the correct schema when the path is set as
3523
+ follows:
3524
+ </p>
3525
+ <pre>
3526
+ set search_path = xxx
3527
+ </pre>
3528
+ <p>
3529
+ and the schema name is omitted in a query.
3530
+ </p>
3531
+ <h3>table name - column name(for parallel mode)</h3>
3532
+ <p>
3533
+ Limitation object:Parallel mode
3534
+ </p>
3535
+ <p>
3536
+ A table or a column name cannot start by pool_.
3537
+ When rewriting queries, these names are used by internal processing.
3538
+ </p>
3539
+
3540
+ </p>
3541
+ <h2>System DB</h2>
3542
+
3543
+ <h3>Partitioning Rules</h3>
3544
+
3545
+ <p>Only one partitioning key column can be defined in one
3546
+ partitioning rule. Conditions like 'x or y' are not supported.</p>
3547
+
3548
+ <h2>Environment Requirements</h2>
3549
+
3550
+ <h3>libpq</h3>
3551
+
3552
+ <p><code>libpq</code> is linked while building pgpool-II. libpq
3553
+ version must be 3.0. Building pgpool-II with libpq version 2.0 will
3554
+ fail. Also, the System DB must be PostgreSQL 7.4 or later.</p>
3555
+
3556
+ <h2>Query Cache</h2>
3557
+
3558
+ <p>Currently, the query cache must be deleted manually. pgpool-II does not
3559
+ invalidate old query cache automatically when the data is updated.</p>
3560
+
3561
+ <h2>Compatibility with pgpool</h2>
3562
+
3563
+ <h1>References<a name="reference"></a></h1>
3564
+ <h2>PCP Command Reference</h2>
3565
+
3566
+ <h3>PCP Command List</h3>
3567
+
3568
+ <p>PCP commands are UNIX commands which manipulate pgpool-II via the network.
3569
+
3570
+ <pre>
3571
+ * pcp_node_count - retrieves the number of nodes
3572
+ * pcp_node_info - retrieves the node information
3573
+ * pcp_proc_count - retrieves the process list
3574
+ * pcp_proc_info - retrieves the process information
3575
+ * pcp_systemdb_info - retrieves the System DB information
3576
+ * pcp_detach_node - detaches a node from pgpool-II
3577
+ * pcp_attach_node - attaches a node to pgpool-II
3578
+ * pcp_promote_node - promote a new master node to pgpool-II
3579
+ * pcp_stop_pgpool - stops pgpool-II
3580
+ </pre>
3581
+ </p>
3582
+
3583
+
3584
+ <h2>Common Command-line Arguments</h2>
3585
+
3586
+ <p>There are five arguments common to all of the PCP commands. They
3587
+ give information about pgpool-II and authentication. Extra
3588
+ arguments may be needed for some commands.
3589
+
3590
+ <pre>
3591
+ e.g.) $ pcp_node_count 10 localhost 9898 postgres hogehoge
3592
+
3593
+ First argument - timeout value in seconds. PCP disconnects if
3594
+ pgpool-II does not respond in this many seconds.
3595
+ Second argument - pgpool-II's hostname
3596
+ Third argument - PCP port number
3597
+ Fourth argument - PCP username
3598
+ Fifth argument - PCP password
3599
+ </pre>
3600
+
3601
+ <p>PCP usernames and passwords must be declared in
3602
+ <code>pcp.conf</code> in <code>$prefix/etc</code>
3603
+ directory. <code>-F</code> option can be used when starting pgpool-II
3604
+ if <code>pcp.conf</code> is placed somewhere else. The password does
3605
+ not need to be in md5 format when passing it to the PCP commands.</p>
3606
+
3607
+
3608
+ <h2>PCP Commands</h2>
3609
+
3610
+ <p>All PCP commands display the results to the standard output.</p>
3611
+
3612
+
3613
+ <h3>pcp_node_count</h3>
3614
+
3615
+ <pre>
3616
+ Format:
3617
+ pcp_node_count _timeout_ _host_ _port_ _userid_ _passwd_
3618
+ </pre>
3619
+
3620
+ <p>
3621
+ Displays the total number of nodes defined in <code>pgpool.conf</code>. It does
3622
+ not distinguish between nodes status, ie attached/detached. ALL nodes are counted.
3623
+ </p>
3624
+
3625
+
3626
+ <h3><a name="pcp_node_info"/>pcp_node_info</h3>
3627
+
3628
+ <pre>
3629
+ Format:
3630
+ pcp_node_info _timeout_ _host_ _port_ _userid_ _passwd_ _nodeid_
3631
+ </pre>
3632
+
3633
+ <p>
3634
+ Displays the information on the given node ID. Here is an output example:
3635
+ </p>
3636
+
3637
+ <pre>
3638
+ $ pcp_node_info 10 localhost 9898 postgres hogehoge 0
3639
+ host1 5432 1 1073741823.500000
3640
+
3641
+ The result is in the following order:
3642
+ 1. hostname
3643
+ 2. port number
3644
+ 3. status
3645
+ 4. load balance weight
3646
+
3647
+ Status is represented by a digit from [0 to 3].
3648
+ 0 - This state is only used during the initialization. PCP will never display it.
3649
+ 1 - Node is up. No connections yet.
3650
+ 2 - Node is up. Connections are pooled.
3651
+ 3 - Node is down.
3652
+ </pre>
3653
+ <p>
3654
+ The load balance weight is displayed in normalized format.
3655
+ </p>
3656
+
3657
+ <p>
3658
+ The --verbose option can help understand the output. For example:
3659
+ </p>
3660
+
3661
+ <pre>
3662
+ $ pcp_node_info --verbose 10 localhost 9898 postgres hogehoge 0
3663
+ Hostname: host1
3664
+ Port : 5432
3665
+ Status : 1
3666
+ Weight : 0.5
3667
+ </pre>
3668
+
3669
+ <p>Specifying an invalid node ID will result in an error with exit
3670
+ status 12, and BackendError will be displayed.</p>
3671
+
3672
+ <h3>pcp_proc_count</h3>
3673
+ <p>
3674
+ <pre>
3675
+ Format:
3676
+ pcp_proc_count _timeout_ _host_ _port_ _userid_ _passwd_
3677
+ </pre>
3678
+ <p>
3679
+ Displays the list of pgpool-II children process IDs. If there is more than
3680
+ one process, IDs will be delimited by a white space.
3681
+ </p>
3682
+ <h3>pcp_proc_info</h3>
3683
+ <p>
3684
+ <pre>
3685
+ Format:
3686
+ pcp_proc_info _timeout_ _host_ _port_ _userid_ _passwd_ _processid_
3687
+ </pre>
3688
+ <p>
3689
+ Displays the information on the given pgpool-II child process ID. The
3690
+ output example is as follows:
3691
+ </p>
3692
+ <pre>
3693
+ $ pcp_proc_info 10 localhost 9898 postgres hogehoge 3815
3694
+ postgres_db postgres 1150769932 1150767351 3 0 1 1467 1
3695
+ postgres_db postgres 1150769932 1150767351 3 0 1 1468 1
3696
+
3697
+ The result is in the following order:
3698
+ 1. connected database name
3699
+ 2. connected username
3700
+ 3. process start-up timestamp
3701
+ 4. connection created timestamp
3702
+ 5. protocol major version
3703
+ 6. protocol minor version
3704
+ 7. connection-reuse counter
3705
+ 8. PostgreSQL backend process id
3706
+ 9. 1 if frontend conncted 0 if not
3707
+ </pre>
3708
+ <p>
3709
+ If there is no connection to the backends, nothing will be
3710
+ displayed. If there are multiple connections, one connection's
3711
+ information will be displayed on each line multiple
3712
+ times. Timestamps are displayed in EPOCH format.
3713
+ </p>
3714
+
3715
+ <p>
3716
+ The --verbose option can help understand the output. For example:
3717
+ </p>
3718
+
3719
+ <pre>
3720
+ $ pcp_proc_info --verbose 10 localhost 9898 postgres hogehoge 3815
3721
+ Database : postgres_db
3722
+ Username : postgres
3723
+ Start time : 1150769932
3724
+ Creation time: 1150767351
3725
+ Major : 3
3726
+ Minor : 0
3727
+ Counter : 1
3728
+ PID : 1467
3729
+ Connected : 1
3730
+ Database : postgres_db
3731
+ Username : postgres
3732
+ Start time : 1150769932
3733
+ Creation time: 1150767351
3734
+ Major : 3
3735
+ Minor : 0
3736
+ Counter : 1
3737
+ PID : 1468
3738
+ Connected : 1
3739
+ </pre>
3740
+
3741
+ <p>Specifying an invalid node ID will result in an error with exit
3742
+ status 12, and BackendError will be displayed.</p>
3743
+
3744
+ <h3>pcp_systemdb_info</h3>
3745
+ <p>
3746
+ <pre>
3747
+ Format:
3748
+ pcp_systemdb_info _timeout_ _host_ _port_ _userid_ _passwd_
3749
+ </pre>
3750
+ <p>
3751
+ Displays the System DB information. The output example is as follows:
3752
+ </p>
3753
+ <pre>
3754
+ $ pcp_systemdb_info 10 localhost 9898 postgres hogehoge
3755
+ localhost 5432 yamaguti '' pgpool_catalog pgpool 3
3756
+ yamaguti public accounts aid 4 aid bid abalance filler integer integer integer character(84) dist_def_accounts
3757
+ yamaguti public branches bid 3 bid bbalance filler integer integer character(84) dist_def_branches
3758
+ yamaguti public tellers bid 4 tid bid tbalance filler integer integer integer character(84) dist_def_tellers
3759
+
3760
+ First, the System DB information will be displayed on the first
3761
+ line. The result is in the following order:
3762
+ 1. hostname
3763
+ 2. port number
3764
+ 3. username
3765
+ 4. password. '' for no password.
3766
+ 5. schema name
3767
+ 6. database name
3768
+ 7. number of partioning rules defined
3769
+ </pre>
3770
+ <p>
3771
+ Second, partitioning rules will be displayed on the following lines. If
3772
+ there are multiple definitions, one definition will be displayed on
3773
+ each line multiple times. The result is in the following order:
3774
+ </p>
3775
+ <pre>
3776
+ 1. targeted partitioning database name
3777
+ 2. targeted partitioning schema name
3778
+ 3. targeted partitioning table name
3779
+ 4. partitioning key column name
3780
+ 5. number of columns in the targeted table
3781
+ 6. column names (displayed as many as said in 5.)
3782
+ 7. column types (displayed as many as said in 5.)
3783
+ 8. partitioning rule function name
3784
+ </pre>
3785
+ <p>
3786
+ If the System DB is not defined (i.e. not in pgpool-II mode, and query
3787
+ cache is disabled), it results in error with exit status 12, and
3788
+ BackendError will be displayed.</p>
3789
+
3790
+
3791
+ <h3>pcp_detach_node</h3>
3792
+ <pre>
3793
+ Format:
3794
+ pcp_detach_node [-g] _timeout_ _host_ _port_ _userid_ _passwd_ _nodeid_
3795
+ </pre>
3796
+ <p>
3797
+ Detaches the given node from pgpool-II.
3798
+ If -g is given, wait until all clients are disconnected (unless
3799
+ client_idle_limit_in_recovery is -1 or recovery_timeout is expired).
3800
+ </p>
3801
+
3802
+
3803
+ <h3>pcp_attach_node</h3>
3804
+ <p>
3805
+ <pre>
3806
+ Format:
3807
+ pcp_attach_node _timeout_ _host_ _port_ _userid_ _passwd_ _nodeid_
3808
+
3809
+ Attaches the given node to pgpool-II.
3810
+ </pre>
3811
+ </p>
3812
+
3813
+ <h3>pcp_promote_node</h3>
3814
+ <p>
3815
+ <pre>
3816
+ Format:
3817
+ pcp_promote_node [-g] _timeout_ _host_ _port_ _userid_ _passwd_ _nodeid_
3818
+
3819
+ Promotes the given node as new master to pgpool-II. In master/slave streaming replication only.
3820
+ If -g is given, wait until all clients are disconnected (unless
3821
+ client_idle_limit_in_recovery is -1 or recovery_timeout is expired).
3822
+ </pre>
3823
+ </p>
3824
+
3825
+ <h3>pcp_stop_pgpool</h3>
3826
+ <pre>
3827
+ Format:
3828
+ pcp_stop_pgpool _timeout_ _host_ _port_ _userid_ _passwd_ _mode_
3829
+ </pre>
3830
+
3831
+ <p>
3832
+ Terminate the pgpool-II process with the given shutdown mode. The available
3833
+ modes are as follows:
3834
+ </p>
3835
+
3836
+ <pre>
3837
+ s - smart mode
3838
+ f - fast mode
3839
+ i - immediate mode
3840
+ </pre>
3841
+ <p>
3842
+ If the pgpool-II process does not exist, it results in error with exit
3843
+ status 8, and ConnectionError will be displayed.
3844
+ </p>
3845
+ <p>
3846
+ * Currently, there is no difference between the fast and immediate
3847
+ mode. pgpool-II terminates all the processes whether there are clients
3848
+ connected to the backends or not.</p>
3849
+
3850
+
3851
+ <h2>Exit Status</h2>
3852
+
3853
+ <p>PCP commands exits with status 0 when everything goes well. If any
3854
+ error had occurred, it will exit with the following error status.
3855
+
3856
+ <pre>
3857
+ UNKNOWNERR 1 Unknown Error (should not occur)
3858
+ EOFERR 2 EOF Error
3859
+ NOMEMERR 3 Memory shortage
3860
+ READERR 4 Error while reading from the server
3861
+ WRITEERR 5 Error while writing to the server
3862
+ TIMEOUTERR 6 Timeout
3863
+ INVALERR 7 Argument(s) to the PCP command was invalid
3864
+ CONNERR 8 Server connection error
3865
+ NOCONNERR 9 No connection exists
3866
+ SOCKERR 10 Socket error
3867
+ HOSTERR 11 Hostname resolution error
3868
+ BACKENDERR 12 PCP process error on the server (specifying an invalid ID, etc.)
3869
+ AUTHERR 13 Authorization failure
3870
+ </pre>
3871
+ </p>
3872
+
3873
+ <h1>Inside information<a name="internal"></a></h1>
3874
+ <p>
3875
+ pgpool-II version 2.0.x brings extensive modifications, compared with the version 1.x
3876
+ Please note that what follows doesn't apply to version 1.x.
3877
+ </p>
3878
+
3879
+ <h2>Parallel execution engine</h2>
3880
+ <p>
3881
+ The parallel execution engine is built into pgpool-II.
3882
+ This engine performs the same Query on each node, and drives the engine that
3883
+ transmits the result to the front end, depending on the nodes' answers.
3884
+ </p>
3885
+
3886
+ <h2>Query Rewriting</h2>
3887
+ <p>
3888
+ This explains the Query rewriting that pgpool-II does in parallel mode.
3889
+ </p>
3890
+ <p>
3891
+ In parallel mode, a query transmitted by the client goes through two stages of
3892
+ processing:
3893
+ </p>
3894
+ <ul>
3895
+ <li>Analysis of Query
3896
+ <li>Rewriting of Query
3897
+ </ul>
3898
+ <p>
3899
+ What follows explains these two processing steps:
3900
+ </p>
3901
+ <h3>Analysis of Query</h3>
3902
+ <h4><p>Introduction</p></h4>
3903
+ <p>
3904
+ The retrieval query submitted by the client goes through the SQL parser. It is then analyzed
3905
+ using information stored in the system DB. Execution status of each part
3906
+ of this query is updated using this information. This execution status stores
3907
+ where this node can be treated. For instance, if a table's data is distributed
3908
+ on several nodes (as declared in the catalog's pgpool_catalog.dist_def table),
3909
+ it has to be retrieved from all nodes. On the other hand, data from a table
3910
+ registered in pgpool_catalog.replicate_def is replicated, and can therefore
3911
+ be retrieved from any node. These states are 'P' when data has to be processed by
3912
+ all nodes, 'L' when it should be processed by one node. The 'S' status is a special
3913
+ case: it means that there is another step to be performed on the data after
3914
+ retrieving it from all nodes. For example, sorting data coming from a table
3915
+ registered in the pgpool_catalog.dist_def table.
3916
+ </p>
3917
+
3918
+ <p>
3919
+ The retrieval query is analyzed in the following order, and its execution status
3920
+ changes during this processing. Where the query will be processed depends on the
3921
+ final status of the main select.
3922
+ </p>
3923
+
3924
+ <ol>
3925
+ <li>Are UNION, EXTRACT, and INTERSECT used or not?
3926
+ <li>What is the Execution status of FROM clause ?
3927
+ <li>Change the execution status by TARGETLIST
3928
+ <li>Change in execution status according to WHERE clause
3929
+ <li>Change in execution status according to GROUP BY clause
3930
+ <li>Change in execution status according to HAVING clause
3931
+ <li>Change in execution status according to ORDER BY clause
3932
+ <li>Changes into the LIMIT OFFSET predicate in the execution status.
3933
+ <li>Acquisition of the final execution status of SELECT
3934
+ </ol>
3935
+
3936
+ <p>
3937
+ The relation between the final execution status of SELECT and the processing
3938
+ place is as follows.
3939
+ </p>
3940
+
3941
+ <p>
3942
+ <table border>
3943
+ <tr><td>Execution status</td><td>Processed place</td></tr>
3944
+ <tr><td align=center>L</td><td>Query issued on either node. </td></tr>
3945
+ <tr><td align=center>P</td><td>Returns data to the client by running the
3946
+ same query on all nodes and using the parallel execution engine.</td></tr>
3947
+ <tr><td align=center>S</td><td>After processing using the system DB, data
3948
+ is returned to the client. </td></tr>
3949
+ </table>
3950
+ </p>
3951
+
3952
+ <p>
3953
+ The above-mentioned rule also applies to Sub-Query. In the simple following
3954
+ Query, if p1-table is registered in pgpool_catalog.dist_def table of the system
3955
+ DB (p1-table is distributed), the final execution status of the subquery
3956
+ becomes P, and as a result, the parent of the subquery, SELECT, also becomes P.
3957
+ </p>
3958
+
3959
+ <pre>
3960
+ SELECT * FROM (SELECT * FROM P1-table) as P2-table;
3961
+ </pre>
3962
+
3963
+ <p>
3964
+ Next, let's explain how the execution status changes concretely.
3965
+ Let's start with an example, to explain the FROM status.
3966
+ </p>
3967
+
3968
+ <h4><p>Execution status of FROM clause</p></h4>
3969
+ <p>
3970
+ This is a retrieval Query (SELECT). The data set and its status (P,L and S) is
3971
+ defined according to the FROM clause
3972
+
3973
+ The execution status of the table is as follows: when there is only one table in
3974
+ the from clause, the execution status of the entire dataset is this table's
3975
+ execution status. When there are two or more tables or sub-queries in the FROM
3976
+ clause, the execution is decided according to the join method and the execution
3977
+ statuses, as show in the following table.
3978
+ </p>
3979
+
3980
+ <p>
3981
+ <table border>
3982
+ <tr><td>JOIN type</td><td align = center colspan = 3> LEFT OUTER JOIN </td><td align = center colspan = 3> RIGHT OUTER JOIN </td><td align = center colspan = 3>FULL OUTER JOIN</td><td align = center colspan = 3>Other</td></tr>
3983
+ <tr><td align = center>left/right</td><td> P </td><td> L </td><td> S </td><td> P </td><td> L </td><td> S </td><td> P </td><td> L </td><td> S </td><td> P </td><td> L </td><td> S </td></tr>
3984
+
3985
+ <tr><td align = center> P </td><td> S </td><td> P </td><td> S </td><td> S </td><td> S </td><td> S </td><td> S </td><td> S </td><td> S </td><td> S </td><td> P </td><td> S </td></tr>
3986
+
3987
+ <tr><td align = center> L </td><td> S </td><td> L </td><td> S </td><td> P </td><td> L </td><td> S </td><td> S </td><td> L </td><td> S </td><td> P </td><td> L </td><td> S </td></tr>
3988
+
3989
+ <tr><td align = center> S </td><td> S </td><td> S </td><td> S </td><td> S </td><td> S </td><td> S </td><td> S </td><td> S </td><td> S </td><td> S </td><td> S </td><td> S </td></tr>
3990
+
3991
+ </td></tr>
3992
+ </table>
3993
+ </p>
3994
+
3995
+ <p>
3996
+ In the following examples, P1-table is in the P status.
3997
+ L1-table and L2-table are in the L status.
3998
+
3999
+ <pre>
4000
+ SELECT * FROM P1-table,L1-table,L2-table;
4001
+ </pre>
4002
+
4003
+
4004
+ P1-table (left) and L1-table (right) are joined, and according to the table they
4005
+ get the P status. With this P status, they are joined with the L2-table, in the L
4006
+ status, which is now in the P status too.
4007
+ </p>
4008
+
4009
+
4010
+ <h4><p>Changes in execution status because of TARGETLIST and WHERE clause</p></h4>
4011
+ <p>
4012
+ In a basic Query, the execution status is the one from the FROM clause.
4013
+ However, if there is a TARGETLIST, the execution status of the WHERE clause can
4014
+ change in the following cases.
4015
+ </p>
4016
+ <ol>
4017
+ <li>When there is a subquery
4018
+ <li>When there is an aggregate function or DISTINCT in TARGETLIST marked as 'P'
4019
+ <li>When a column that does not exist in a table (data set)
4020
+ in the FROM clause is used
4021
+ </ol>
4022
+ <p>
4023
+ In these cases, the final execution status of the subquery, the execution status of
4024
+ TARGETLIST and the WHERE clause get the S status if the initial status was
4025
+ P or S.
4026
+ <p>
4027
+ In the following example, when the table used by the subquery is P, the final
4028
+ execution status of the subquery gets the P status. Therefore, The execution
4029
+ status of the WHERE clause gets the S status, whatever the execution status of
4030
+ L1 is, and this query is run in the system DB.
4031
+ <pre>
4032
+ SELECT * FROM L1-table where L1-table.column IN (SELECT * FROM P1-table);
4033
+ </pre>
4034
+ <p>
4035
+ The FROM clause changes to the S status when there is an aggregate function in
4036
+ a 'P' TARGETLIST, in order to perform the aggregate after all data has been
4037
+ acquired.
4038
+ Some optimization on the aggregate function is done under specific conditions.
4039
+ </p>
4040
+ <p>
4041
+ A column that does not exist in a table can be used in a query. For instance, in
4042
+ the following correlated subquery:
4043
+ </p>
4044
+ <pre>
4045
+ SELECT * FROM L1-table WHERE L1-table.col1 IN (SELECT * FROM P1-table WHERE P1-table.col = L1-table.col1);
4046
+ </pre>
4047
+ <p>
4048
+ This subquery refers to L1-table.col1, from the L1-table. The execution status
4049
+ of the WHERE clause of the subquery is 'S'.
4050
+ </p>
4051
+ <h4><p>Change in execution status because of GROUP BY, HAVING, ORDER BY and LIMIT/OFFSET</p></h4>
4052
+
4053
+ <p>
4054
+ The execution status of the WHERE clause is changed to 'S' when there is any GROUP
4055
+ BY, HAVING, or ORDER BY clause, or LIMIT/OFFSET predicate and status is 'P'. A
4056
+ query with no GROUP BY clause gets the execution status of the WHERE clause.
4057
+ In the same way, the execution status of the GROUP BY clause is
4058
+ used when there is no HAVING clause. The ORDER BY clause and the LIMIT/OFFSET
4059
+ predicate are also similar in this behavior.
4060
+ </p>
4061
+
4062
+ <h4><p>When UNION, EXTRACT, and INTERSECT are used</p></h4>
4063
+ <p>
4064
+ UNION, EXTRACT, and INTERSECT queries' status depends on the final execution
4065
+ status of both the left and right SELECT statements. If both statements are L, the
4066
+ combined statement is L. If both statements are P, and the query is a UNION ALL
4067
+ the combined statement is P. For any other combination, the resulting status is
4068
+ S.
4069
+ </p>
4070
+ <h4><p>Acquisition of the final execution status of SELECT</p></h4>
4071
+ <p>
4072
+ If everything in the SELECT has a status of L, then the final execution status
4073
+ is L. The same rule applies for P. For any other combination, the final status is S.
4074
+ If the status is L, the load is distributed among nodes when loadbalance_mode is
4075
+ true and sent to the MASTER if false. For P, parallel processing is done with
4076
+ the parallel execution engine. For S, the query rewriting presented below is done.
4077
+ </p>
4078
+
4079
+ <h3>Query rewriting</h3>
4080
+ <p>
4081
+ The Query is rewritten by using the execution status acquired while analyzing
4082
+ the query.
4083
+ Here is an example. The P1-table has the P status, the L1-table has the L status.
4084
+
4085
+ </p>
4086
+ <pre>
4087
+ SELECT P1-table.col, L1-table.col
4088
+ FROM P1-table,L1-table
4089
+ where P1-table.col = L1-table.col
4090
+ order by P1-table.col;
4091
+ </pre>
4092
+
4093
+ <p>
4094
+ In this query, because there is an ORDER BY clause, the status is S.
4095
+ The FROM clause, the WHERE clause, and TARGETLIST are in the P status.
4096
+ The query is rewritten into something like this :
4097
+ </p>
4098
+
4099
+ <pre>
4100
+ SELECT P1-table.col, L1-table.col FROM
4101
+ dblink(select pool_parallel(SELECT P1-table.col, L1-table.col FROM P1-table,L1-table where P1-table.col = L1-table.col))
4102
+ order by P1-table.col;
4103
+ </pre>
4104
+ <p>
4105
+ dblink transmits the query to pgpool-II here.
4106
+ the pool_parallel function is responsible for sending the query to the
4107
+ parallel execution engine.
4108
+ </p>
4109
+ <p>In this example, the FROM and WHERE clause, and the TARGETLIST are run in
4110
+ parallel mode. This isn't the real rewritten query, just something for the sake
4111
+ of providing an example.
4112
+ </p>
4113
+ <p>
4114
+ Here is another case:
4115
+ </p>
4116
+
4117
+ <pre>
4118
+ SELECT L1-table.col FROM L1-table WHERE L1-table.col % 2 = 0 AND L1-table.col IN (SELECT P1-table FROM P1-table) ;
4119
+ </pre>
4120
+
4121
+ <p>
4122
+ In this example, the FROM and WHERE clause and the TARGETLIST are in the L
4123
+ status. Because the subquery is in the P status, the query itself is in the S status.
4124
+ The rewriting is, as a consequence, performed as follows.
4125
+ </p>
4126
+ <pre>
4127
+ SELECT L1-table.col
4128
+ FROM dblink(SELECT loadbalance(SELECT L1-table.col
4129
+ FROM L1-table
4130
+ WHERE L1-table.col % 2 = 0
4131
+ AND TRUE))
4132
+ WHERE
4133
+ L1-table.col %2 = 0 AND
4134
+ L1-table.col IN
4135
+ (
4136
+ SELECT P1-Table FROM
4137
+ dblink(select pool_parallel(SELECT P1-table FROM P1-table))
4138
+ ) ;
4139
+ </pre>
4140
+ <p>
4141
+ pool_loadbalance is a function responsible for dispatching queries to either node.
4142
+ </p>
4143
+
4144
+ <h3>Query rewriting for aggregate functions</h3>
4145
+ <p>
4146
+ For grouping queries (aggregate functions and GROUP BY), rewriting tries to
4147
+ reduce the load on the system DB by performing a first aggregate on each node.
4148
+ </p>
4149
+ <p>
4150
+ First, let's see what pgpool-II does for rewriting.
4151
+ </p>
4152
+ <p>
4153
+ This query has the P status in the FROM clause and count(*) in TARGETLIST.
4154
+ So the rewriting is done as follows.
4155
+ </p>
4156
+ <pre>
4157
+ select count(*) from P1-table;
4158
+
4159
+ -> rewrite
4160
+
4161
+ SELECT
4162
+ sum(pool_c$1) as count
4163
+ FROM
4164
+ dblink(select pool_parallel('select count(*) from P1-table'))
4165
+ AS pool_$1g (pool_c$1 bigint);
4166
+ </pre>
4167
+ <p>
4168
+ Query rewriting like above is done in these conditions.
4169
+ </p>
4170
+ <ol>
4171
+ <li>The FROM clause is in the P status.
4172
+ <li>The column specified in the aggregate function (only count, sum, min,
4173
+ max, and avg) and GROUP BY is used in the target list.
4174
+ <li>The WHERE clause is in the P status.
4175
+ <li>Only the columns defined by the aggregate function (only count, sum,
4176
+ min, max, and avg), used in the HAVING clause and the FROM clause, and
4177
+ the column specified for GROUP BY are used.
4178
+ </ol>
4179
+ <h3>Notes on the parallel mode</h3>
4180
+ <p>
4181
+ The column names and types are needed when a query is analyzed in parallel mode.
4182
+ Therefore, when an expression or a function is used in the TARGETLIST of
4183
+ a subquery, the alias and type (through a cast) are needed. Please note that
4184
+ if no cast is provided in an expression or a function, the text type will be
4185
+ chosen as a default. For count(), bigint type is assumed, and for sum(),
4186
+ numeric. For min()/max(), if the argument is a date type, returned datatype is date,
4187
+ else, it is assumed numeric. avg() is processed as sum()/count() (sum divided by count).
4188
+
4189
+ <h3>About the performance of a parallel mode</h3>
4190
+ <p>Here is a rough estimate of the query performance versus execution status:
4191
+ </p>
4192
+ <p>
4193
+ <table border>
4194
+ <tr><td>Execution status</td><td>Performance</td></tr>
4195
+ <tr><td align = center>L</td><td>There is no performance deterioration with a
4196
+ single node, excluding the overhead of pgpool-II, because there is no parallel
4197
+ querying done at all.</td></tr>
4198
+ <tr><td align = center>P</td><td>Parallel processing is fast, especially the
4199
+ sequential scans. It's easy to get speedups because the scan of a big table
4200
+ becomes the parallel scan of much smaller ones by being distributed on several
4201
+ nodes.
4202
+ <tr><td align = center>S</td><td>When aggregate functions can be rewritten in a
4203
+ parallel fashion, they are fast.</td></tr>
4204
+ </td></tr>
4205
+ </table>
4206
+ </p>
4207
+
4208
+ <h1>Tutorial</h1>
4209
+ <p>
4210
+ <a href="tutorial-en.html">A tutorial for pgpool-II</a> is available.
4211
+ </p>
4212
+
4213
+ <div class="copyright">
4214
+ <hr>
4215
+ <copyright>
4216
+ Copyright &copy; 2003 &ndash; 2011 pgpool Global Development Group
4217
+ </copyright>
4218
+ </div>
4219
+ </body>
4220
+ </html>