From dbc9ab7c201405a3442abbd39f66b03a84d52fcd Mon Sep 17 00:00:00 2001 From: Marko Kreen Date: Tue, 28 Aug 2007 09:33:38 +0000 Subject: [PATCH] doc update --- AUTHORS | 14 +++++++++-- Makefile | 36 +++++++++++++++++++---------- NEWS | 9 ++++++-- doc/Makefile | 17 +++++++++++--- doc/pgbouncer.config.txt | 50 +++++++++++++++++++++++++++++----------- doc/todo.txt | 11 +++++++-- 6 files changed, 102 insertions(+), 35 deletions(-) diff --git a/AUTHORS b/AUTHORS index dfceaba..99f6e79 100644 --- a/AUTHORS +++ b/AUTHORS @@ -1,4 +1,14 @@ -Marko Kreen - main coder -Martin Pihlak - head inquisitor +Main author +----------- + +Marko Kreen + +Contributors +------------ + +David Fetter +Dimitri Fontaine +Martin Pihlak +Robert Gogolok diff --git a/Makefile b/Makefile index 0f9dcb0..1aa41cf 100644 --- a/Makefile +++ b/Makefile @@ -8,9 +8,12 @@ HDRS = client.h loader.h objects.h pooler.h proto.h sbuf.h server.h util.h \ list.h mbuf.h varcache.h # data & dirs to include in tgz -DATA = README NEWS etc/pgbouncer.ini Makefile config.mak.in config.h.in \ - configure configure.ac debian/packages debian/changelog -DIRS = etc src debian +DOCS = doc/makefile doc/overview.txt doc/pgbouncer.cmdline.txt \ + doc/pgbouncer.config.txt doc/todo.txt +MANPAGES = doc/pgbouncer.1 doc/pgbouncer.5 +DATA = README NEWS AUTHORS etc/pgbouncer.ini Makefile config.mak.in config.h.in \ + configure configure.ac debian/packages debian/changelog doc/Makefile +DIRS = doc etc src debian # keep autoconf stuff separate -include config.mak @@ -25,7 +28,7 @@ hdrs = $(addprefix $(srcdir)/src/, $(HDRS)) srcs = $(addprefix $(srcdir)/src/, $(SRCS)) objs = $(addprefix $(builddir)/lib/, $(OBJS)) FULL = $(PACKAGE_TARNAME)-$(PACKAGE_VERSION) -DISTFILES = $(DIRS) $(DATA) $(srcs) $(hdrs) +DISTFILES = $(DIRS) $(DATA) $(DOCS) $(srcs) $(hdrs) $(MANPAGES) # Quiet by default, 'make V=1' shows commands V=0 @@ -40,7 +43,7 @@ endif ## actual targets now ## # default target -all: pgbouncer +all: pgbouncer doc-all # final executable pgbouncer: config.mak $(objs) @@ -54,31 +57,38 @@ $(builddir)/lib/%.o: $(srcdir)/src/%.c config.mak $(hdrs) $(Q) $(CC) -c -o $@ $< $(DEFS) $(CFLAGS) $(CPPFLAGS) # install binary and other stuff -install: pgbouncer +install: pgbouncer doc-install mkdir -p $(DESTDIR)$(bindir) mkdir -p $(DESTDIR)$(docdir) $(BININSTALL) -m 755 pgbouncer $(DESTDIR)$(bindir) $(INSTALL) -m 644 $(srcdir)/etc/pgbouncer.ini $(DESTDIR)$(docdir) # create tarfile -tgz: config.mak $(DISTFILES) +tgz: config.mak $(DISTFILES) $(MANPAGES) rm -rf $(FULL) $(FULL).tgz mkdir $(FULL) (for f in $(DISTFILES); do echo $$f; done) | cpio -p $(FULL) tar czf $(FULL).tgz $(FULL) rm -rf $(FULL) +doc/pgbouncer.1: + make -C doc pgbouncer.1 + +doc/pgbouncer.5: + make -C doc pgbouncer.5 + # create debian package deb: configure yada rebuild debuild -uc -us -b # clean object files -clean: - rm -f *~ src/*~ *.o src/*.o lib/*.o pgbouncer core core.* +clean: doc-clean + rm -f *~ src/*~ *.o src/*.o lib/*.o lib/*.s pgbouncer core core.* + rm -f lib/*.log # clean configure results -distclean: clean +distclean: clean doc-distclean rm -f config.h config.log config.status config.mak rm -rf lib autom4te* @@ -98,6 +108,10 @@ config.mak:: echo "Please run 'make boot && ./configure' first.";exit 1;} @test -f $@ || { echo "Please run ./configure first.";exit 1;} +doc-all doc-install doc-clean doc-distclean doc-realclean: + $(MAKE) -C doc $(subst doc-,,$@) DESTDIR=$(DESTDIR) + + # targets can depend on this to force 'make boot' configure:: @test -f $@ || { echo "Please run 'make boot' first.";exit 1;} @@ -126,8 +140,6 @@ check: config.mak pgbouncer.pg: $(CC) -pg $(DEFS) -g -O2 $(CPPFLAGS) $(LDFLAGS) -o $@ $(srcs) $(LIBS) - - pg: pgbouncer.pg $(builddir)/lib/%.s: $(srcdir)/src/%.c config.mak $(hdrs) diff --git a/NEWS b/NEWS index 9311da1..50b981f 100644 --- a/NEWS +++ b/NEWS @@ -3,17 +3,22 @@ = Features = + * Keep track of following server parameters: + + client_encoding datestyle, timezone, standard_conforming_strings + * Database connect string enhancements: - Accept hostname in host= - Accept custom unix socket location in host= - Accept quoted values: password=' asd''foo' + * server_reset_query, to be sent immidiately after release - * Keep track of following server variables: - client_encoding, datestyle, timezone, standard_conforming_strings + * Cancel pkt sent for idle connection does not drop it anymore. * Cancel with ^C from psql works for SUSPEND / PAUSE. * Print FD limits on startup. * When suspending, try to hit packet boundary ASAP. + * Add 'timezone' to database parameters. = Code cleanup = diff --git a/doc/Makefile b/doc/Makefile index 9a6e93a..ad4a040 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -2,11 +2,20 @@ wiki = https://developer.skype.com/SkypeGarage/DbProjects/PgBouncer web = mkz@shell.pgfoundry.org:/home/pgfoundry.org/groups/pgbouncer/htdocs/ -all: man +-include ../config.mak + +MANPAGES = pgbouncer.1 pgbouncer.5 + +all: $(MANPAGES) -man: pgbouncer.1 pgbouncer.5 html: pgbouncer.config.html pgbouncer.cmdline.html +install: $(MANPAGES) + mkdir -p $(DESTDIR)$(mandir)/man1/ + mkdir -p $(DESTDIR)$(mandir)/man5/ + install -m 644 pgbouncer.1 $(DESTDIR)$(mandir)/man1/ + install -m 644 pgbouncer.5 $(DESTDIR)$(mandir)/man5/ + upload: devupload.sh overview.txt $(wiki) devupload.sh todo.txt $(wiki)/ToDo @@ -23,7 +32,7 @@ pgbouncer.5: pgbouncer.config.xml asciidoc -b docbook -d manpage $< %.html: %.txt - asciidoc $< + asciidoc -a toc $< manpage.xml: manpage.txt asciidoc8 -d manpage -b docbook $< @@ -31,3 +40,5 @@ manpage.xml: manpage.txt clean: rm -f pgbouncer.8 manpage.xml *.[1-9] *.html *.xml +realclean distclean: clean + diff --git a/doc/pgbouncer.config.txt b/doc/pgbouncer.config.txt index 0a1268b..b178a3a 100644 --- a/doc/pgbouncer.config.txt +++ b/doc/pgbouncer.config.txt @@ -19,7 +19,7 @@ Config file is in "ini" format. Section names are between " and ignored. The characters ";" and "#" are not recognized when they appear later in the line. -== Section pgbouncer === +== SECTION [pgbouncer] == === Generic settings === @@ -104,11 +104,15 @@ statement:: Maximum number of client connections allowed. +Default: 100 + ==== default_pool_size ==== How many server connection to allow per user/database pair. Can be overrided in per-database config. +Default: 20 + === Log settings === ==== log_connections ==== @@ -135,11 +139,15 @@ Default: 1 List of users that are allowed to run all commands on console. +Default: empty + ==== stats_users ==== List of users that are allowed to run read-only queries on console. Thats means all SHOW commands except SHOW FDS. +Default: empty. + === Connection sanity checks, timeouts === ==== server_check_delay ==== @@ -147,34 +155,56 @@ all SHOW commands except SHOW FDS. How long to keep released immidiately available, without running sanity-check query on it. If 0 then the query is ran always. +Default: 30 + ==== server_check_query ==== -Good variants are +SELECT 1;+, to just see if connection is alive and -+ABORT; RESET ALL; SET SESSION AUTHORIZATION DEFAULT+ to do full -reset. +Simple do-nothing query to check if server connection is alive. If empty string, then sanity checking is disabled. +Default: SELECT 1; + ==== server_lifetime ==== Pooler tries to close server connections that are been connected longer than this. +Default: 3600 + ==== server_idle_timeout ==== If server connection has been idle more than this then there's too many -connections in the pool and this on can be dropped. +connections in the pool and this one can be dropped. + +Default: 600 ==== server_connect_timeout ==== If connection and login wont finish in this time, the connection will be closed. +Default: 15 + ==== server_login_retry ==== If login failed, because of failure from connect() or authentication that pooler waits this much before retrying to connect. +Default: 15 + +==== client_login_timeout ==== + +If client connect but does not manage to login in this time, it will be +disconnected. Mainly needed to avoid dead connections stalling SUSPEND and thus +online restart. + +Default: 60 + +=== Dangerous timeouts === + +Setting following timeouts cause unexcpected errors. + ==== query_timeout ==== Queries running longer than that are canceled. This should be used only with @@ -191,14 +221,6 @@ problems. Default: 0 (disabled) -==== client_login_timeout ==== - -If client connect but does not manage to login in this time, it will be -disconnected. Mainly needed to avoid dead connections stalling SUSPEND and thus -online restart. - -Default: 0 (disabled) - === Low-level network settings === ==== pkt_buf ==== @@ -235,7 +257,7 @@ Default: not set Default: not set -== Section [databases] == +== SECTION [databases] == This contains key=value pairs where key will be taken as database name and value as libpq-connstring style list of key=value pairs. As actual libpq is not diff --git a/doc/todo.txt b/doc/todo.txt index 9bd352e..5945b53 100644 --- a/doc/todo.txt +++ b/doc/todo.txt @@ -3,10 +3,10 @@ == Ver 1.1 == * create manpage - * report existing pidfile to console * drop_on_error/keep_on_error - if released conn is in error state, then issue rollback and keep it * suspend_timeout - drop stalled conns + * rename disable_varcache to track_parameters == Ver 1.0.9 == @@ -31,4 +31,11 @@ * keep stats about error counts * auth_conn - access to pg_shadow, so auth_file is not needed - * possibility to specify failover databases + * units for config parameters. + * cleanup of logging levels, to make log more useful + +== Dropped ideas == + + * possibility to specify failover databases. + * load-balancing between different servers. + * keeping track of prepared plans - fixed in 8.3 by DISCARD ALL; -- 2.50.1