Received: from localhost (unknown [200.46.204.187])
	by postgresql.org (Postfix) with ESMTP id CECEC2E004B
	for <pgsql-docs-postgresql.org@postgresql.org>;
	Sun,  2 Dec 2007 19:36:48 -0400 (AST)
Received: from postgresql.org ([200.46.204.71])
	by localhost (mx1.hub.org [200.46.204.187]) (amavisd-maia, port 10024)
	with ESMTP id 80403-02 for <pgsql-docs-postgresql.org@postgresql.org>;
	Sun,  2 Dec 2007 19:36:34 -0400 (AST)
Received: from k2smtpout04-01.prod.mesa1.secureserver.net
	(k2smtpout04-01.prod.mesa1.secureserver.net [64.202.189.166])
	by postgresql.org (Postfix) with SMTP id A526B2E003E
	for <pgsql-docs@postgresql.org>; Sun,  2 Dec 2007 19:36:37 -0400 (AST)
Received: (qmail 4215 invoked from network); 2 Dec 2007 23:36:35 -0000
Received: from unknown (HELO mail.cowdot.com) (208.109.83.21)
	by k2smtpout04-01.prod.mesa1.secureserver.net (64.202.189.166) with
	ESMTP; 02 Dec 2007 23:36:35 -0000
Received: by mail.cowdot.com (Postfix, from userid 99)
	id 420CB57ADB2; Sun,  2 Dec 2007 16:36:22 -0700 (MST)
Received: from albert.local (111.pool85-52-225.static.orange.es
	[85.52.225.111])
	by mail.cowdot.com (Postfix) with ESMTP id 07D8957ADA2;
	Sun,  2 Dec 2007 16:36:18 -0700 (MST)
From: Albert Cervera i Areny <albert@nan-tic.com>
Organization: NaN
To: Bruce Momjian <bruce@momjian.us>
Subject: Re: About contrib modules
Date: Mon, 3 Dec 2007 00:36:46 +0100
User-Agent: KMail/1.9.7
Cc: pgsql-docs@postgresql.org
References: <200711221623.lAMGNEX03651@momjian.us>
In-Reply-To: <200711221623.lAMGNEX03651@momjian.us>
MIME-Version: 1.0
Content-Type: Multipart/Mixed;
  boundary="Boundary-00=_PG0UHtbGCmLkang"
Message-Id: <200712030036.47011.albert@nan-tic.com>
X-Virus-Scanned: Maia Mailguard 1.0.1
X-Archive-Number: 200712/5
X-Sequence-Number: 4673

--Boundary-00=_PG0UHtbGCmLkang
Content-Type: text/plain;
  charset="iso-8859-15"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline

A Dijous 22 Novembre 2007, Bruce Momjian va escriure:
> albert@nan-tic.com wrote:
> > I'm sorry I haven't said anything yet. I've got no Internet connection at
> > home. I'll work on the remaining work on contrib docs as soon as my
> > Internet connection is restablished.
>
> Thanks.  We probably have 1-2 weeks left to get it into 8.3 final.

Attached, contrib docs with the changes of the last months. Had to update 
cube, apart from most modules of Tom's list. Everything should be up to date 
now.

-- 
Albert Cervera i Areny
http://www.NaN-tic.com

--Boundary-00=_PG0UHtbGCmLkang
Content-Type: text/x-diff;
  charset="iso-8859-15";
  name="old.diff"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
	filename="old.diff"

Index: cube.sgml
===================================================================
RCS file: /projects/cvsroot/pgsql/doc/src/sgml/cube.sgml,v
retrieving revision 1.2
diff -c -r1.2 cube.sgml
*** cube.sgml	11 Nov 2007 14:23:18 -0000	1.2
--- cube.sgml	2 Dec 2007 23:32:29 -0000
***************
*** 353,358 ****
--- 353,364 ----
        </entry>
       </row>
       <row>
+       <entry><literal>cube(text)</literal></entry>
+       <entry>Takes text input and returns a cube. This is useful for making 
+       cubes from computed strings.
+       </entry>
+      </row>
+      <row>
        <entry><literal>cube(float8) returns cube</literal></entry>
        <entry>This makes a one dimensional cube with both coordinates the same.
         If the type of the argument is a numeric type other than float8 an
Index: intarray.sgml
===================================================================
RCS file: /projects/cvsroot/pgsql/doc/src/sgml/intarray.sgml,v
retrieving revision 1.2
diff -c -r1.2 intarray.sgml
*** intarray.sgml	12 Nov 2007 01:37:34 -0000	1.2
--- intarray.sgml	2 Dec 2007 23:32:29 -0000
***************
*** 12,20 ****
  
   <para>
    Current implementation provides index support for one-dimensional array of
!   int4's - gist__int_ops, suitable for small and medium size of arrays (used on
    default), and gist__intbig_ops for indexing large arrays (we use superimposed
!   signature with length of 4096 bits to represent sets).
   </para>
  
   <sect2>
--- 12,21 ----
  
   <para>
    Current implementation provides index support for one-dimensional array of
!   integers: gist__int_ops, suitable for small and medium size of arrays (used by 
    default), and gist__intbig_ops for indexing large arrays (we use superimposed
!   signature with length of 4096 bits to represent sets). There is also a 
!   non-default gin__int_ops for GIN indexes on integer arrays.
   </para>
  
   <sect2>
Index: pageinspect.sgml
===================================================================
RCS file: /projects/cvsroot/pgsql/doc/src/sgml/pageinspect.sgml,v
retrieving revision 1.1
diff -c -r1.1 pageinspect.sgml
*** pageinspect.sgml	10 Nov 2007 23:30:46 -0000	1.1
--- pageinspect.sgml	2 Dec 2007 23:32:29 -0000
***************
*** 32,46 ****
       A page image obtained with <literal>get_raw_page</literal> should be passed as argument:
      </para>
      <programlisting>
!         test=# SELECT * FROM page_header(get_raw_page('pg_class',0));
!            lsn    | tli | flags | lower | upper | special | pagesize | version
!         ----------+-----+-------+-------+-------+---------+----------+---------
!          0/3C5614 |   1 |     1 |   216 |   256 |    8192 |     8192 |       4
!         (1 row)
      </programlisting>
      <para>
!      The returned columns correspond to the fields in the PageHeaderData-struct,
!      see src/include/storage/bufpage.h for more details.
      </para>
     </listitem>
  
--- 32,45 ----
       A page image obtained with <literal>get_raw_page</literal> should be passed as argument:
      </para>
      <programlisting>
! regression=# SELECT * FROM page_header(get_raw_page('pg_class',0));
!      lsn    | tli | flags | lower | upper | special | pagesize | version | prune_xid
!       -----------+-----+-------+-------+-------+---------+----------+---------+-----------
!         0/24A1B50 |   1 |     1 |   232 |   368 |    8192 |     8192 |       4 |         0
      </programlisting>
      <para>
!      The returned columns correspond to the fields in the PageHeaderData struct.
!      See src/include/storage/bufpage.h for more details.
      </para>
     </listitem>
  
Index: pgbench.sgml
===================================================================
RCS file: /projects/cvsroot/pgsql/doc/src/sgml/pgbench.sgml,v
retrieving revision 1.2
diff -c -r1.2 pgbench.sgml
*** pgbench.sgml	11 Nov 2007 14:23:18 -0000	1.2
--- pgbench.sgml	2 Dec 2007 23:32:29 -0000
***************
*** 379,384 ****
--- 379,399 ----
      <para>
       Variables can also be defined by using -D option.
      </para>
+     <program
+    </listitem>
+    <listitem>
+     <para>
+      <literal>\sleep num [us|ms|s] - Causes script execution to sleep for the
+      specified duration of microseconds (us), milliseconds (ms) or the default
+      seconds (s).
+     </para>
+     <para>
+      Example:
+     </para>
+     <programlisting>
+ \setrandom millisec 1000 2500
+ \sleep : millisec ms
+     </programlisting>
     </listitem>
    </itemizedlist>
   </sect2>
Index: pgrowlocks.sgml
===================================================================
RCS file: /projects/cvsroot/pgsql/doc/src/sgml/pgrowlocks.sgml,v
retrieving revision 1.2
diff -c -r1.2 pgrowlocks.sgml
*** pgrowlocks.sgml	11 Nov 2007 14:23:18 -0000	1.2
--- pgrowlocks.sgml	2 Dec 2007 23:32:29 -0000
***************
*** 102,108 ****
   <sect2>
    <title>Example</title>
    <para>
!    <literal>pgrowlocks</literal> returns the following data type:
    </para>
    <para>
     Here is a sample execution of pgrowlocks:
--- 102,108 ----
   <sect2>
    <title>Example</title>
    <para>
!    <literal>pgrowlocks</literal> returns the following columns:
    </para>
    <para>
     Here is a sample execution of pgrowlocks:
Index: standby.sgml
===================================================================
RCS file: /projects/cvsroot/pgsql/doc/src/sgml/Attic/standby.sgml,v
retrieving revision 1.1
diff -c -r1.1 standby.sgml
*** standby.sgml	10 Nov 2007 23:30:46 -0000	1.1
--- standby.sgml	2 Dec 2007 23:32:30 -0000
***************
*** 7,15 ****
   </indexterm>
  
   <para>
!   <literal>pg_standby</literal> is a production-ready program that can be used 
!   to create a Warm Standby server. Other configuration is required as well, 
!   all of which is described in the main server manual.
   </para>
   <para>
    The program is designed to be a wait-for <literal>restore_command</literal>, 
--- 7,15 ----
   </indexterm>
  
   <para>
!   <literal>pg_standby</literal> allows the creation of a Warm Standby server. 
!   Other configuration is required as well, all of which is described in the 
!   main server manual.
   </para>
   <para>
    The program is designed to be a wait-for <literal>restore_command</literal>, 
***************
*** 18,24 ****
    you could configure <literal>pg_standby</literal> in the following way:
   </para>
   <programlisting>
!    restore_command = 'pg_standby archiveDir %f %p'
   </programlisting>
   <para>
    which would be sufficient to define that files will be restored from 
--- 18,24 ----
    you could configure <literal>pg_standby</literal> in the following way:
   </para>
   <programlisting>
! restore_command = 'pg_standby archiveDir %f %p %r'
   </programlisting>
   <para>
    which would be sufficient to define that files will be restored from 
***************
*** 72,83 ****
     with the pg_standby command usage as
    </para>
    <programlisting>
!    pg_standby [OPTION]... [ARCHIVELOCATION] [NEXTWALFILE] [XLOGFILEPATH]
    </programlisting>
    <para>
     When used within the <literal>restore_command</literal> the %f and %p macros
     will provide the actual file and path required for the restore/recovery.
    </para>
  
    <table>
     <title>Options</title>
--- 72,96 ----
     with the pg_standby command usage as
    </para>
    <programlisting>
!    pg_standby [OPTION]... ARCHIVELOCATION NEXTWALFILE XLOGFILEPATH [RESTARTWALFILE]
    </programlisting>
    <para>
     When used within the <literal>restore_command</literal> the %f and %p macros
     will provide the actual file and path required for the restore/recovery.
    </para>
+   <para>
+   </para>
+    <literal>pg_standby</literal> assumes that <literal>ARCHIVELOCATION</literal>
+    is a directory accessible by the server-owning user.
+   </para>
+   <para>
+    If <literal>RESTARTWALFILE</literal> is specified, typically by using the 
+    <literal>%r</literal> option, then all files prior to this file will be 
+    removed from <literal>ARCHIVELOCATION</literal>. This then minimises the 
+    number of files that need to be held, whilst at the same time maintaining 
+    restart capability. This capability additionally assumes that 
+    <literal>ARCHIVELOCATION</literal> directory is writable.
+   </para>
  
    <table>
     <title>Options</title>
***************
*** 95,102 ****
        <entry>-k numfiles</entry>
        <entry>
         <para>
!         Cleanup files in the archive so that we maintain no more
!         than this many files in the archive. 
         </para>
         <para>
          You should be wary against setting this number too low,
--- 108,118 ----
        <entry>-k numfiles</entry>
        <entry>
         <para>
!         Cleanup files in the archive so that we maintain no more than this 
! 	many files in the archive. This parameter will be silently ignored if
! 	<literal>RESTARTWALFILE</literal> is specified, since that
! 	specification method is more accurate in determining the correct
! 	cut-off point in archive.
         </para>
         <para>
          You should be wary against setting this number too low,
***************
*** 110,117 ****
--- 126,142 ----
          on either primary or standby.
         </para>
         <para>
+         Setting <literal>numfiles</literal> to be zero will disable deletion
+ 	of files from <literal>ARCHIVELOCATION</literal>.
+        </para>
+        <para>
          If in doubt, use a large value or do not set a value at all.
         </para>
+        <para>
+         If you specify neither <literal>RESTARTWALFILE nor -k, then -k 0 will
+ 	be assumed, i.e. keep all files in archive. <literal>Default=0, 
+ 	Min=0</literal>
+        </para>
        </entry>
       </row>
       <row>
***************
*** 122,130 ****
          WAL files will remain in archive
         </para>
         <para>
!         Link is more efficient, but the default is copy to 
!         allow you to maintain the WAL archive for recovery
!         purposes as well as high-availability.
         </para>
         <para>
          This option uses the Windows Vista command mklink
--- 147,156 ----
          WAL files will remain in archive
         </para>
         <para>
!         Link is more efficient, but the default is copy to allow you to 
! 	maintain the WAL archive for recovery purposes as well as 
! 	high-availability. The default setting is not necessarily recommended,
! 	consult the main database server manual for discussion.
         </para>
         <para>
          This option uses the Windows Vista command mklink
***************
*** 145,151 ****
          we will wait 5 secs, 10 secs then 15 secs before reporting
          the failure back to the database server. This will be
          interpreted as and end of recovery and the Standby will come
!         up fully as a result. <literal>Default=3</literal>
         </para>
        </entry>
       </row>
--- 171,177 ----
          we will wait 5 secs, 10 secs then 15 secs before reporting
          the failure back to the database server. This will be
          interpreted as and end of recovery and the Standby will come
!         up fully as a result. <literal>Default=3 Min=0</literal>
         </para>
        </entry>
       </row>
***************
*** 156,162 ****
         if the file to be restored is available in the archive yet.
         The default setting is not necessarily recommended,
         consult the main database server manual for discussion.
!        <literal>Default=5</literal>
        </entry>
       </row>
       <row>
--- 182,188 ----
         if the file to be restored is available in the archive yet.
         The default setting is not necessarily recommended,
         consult the main database server manual for discussion.
!        <literal>Default=5, Min=1, Max=60</literal>
        </entry>
       </row>
       <row>
***************
*** 176,183 ****
         the maximum number of seconds to wait for the next file,
         after which recovery will end and the Standby will come up.
         The default setting is not necessarily recommended,
!        consult the main database server manual for discussion.
!        <literal>Default=0</literal>
        </entry>
       </row>
      </tbody>
--- 202,210 ----
         the maximum number of seconds to wait for the next file,
         after which recovery will end and the Standby will come up.
         The default setting is not necessarily recommended,
!        consult the main database server manual for discussion. A setting of
!        zero means wait forever.
!        <literal>Default=0, Min=0</literal>
        </entry>
       </row>
      </tbody>
***************
*** 193,198 ****
--- 220,251 ----
   </sect2>
  
   <sect2>
+   <title>Supported versions</title>
+   <para>
+    <literal>pg_standby</literal> is designed to work with PostgreSQL 8.2 and
+    and later. It is currently compatible across minor changes between the way
+    8.3 and 8.2 operate.
+   </para>
+   <para>
+    PostgreSQL 8.3 provides the <literal>%r</literal> command line substitution,
+    designed to let <literal>pg_standby</literal> know the last file it needs to
+    keep. If the last parameter is omitted, no error is generated, allowing 
+    <literal>pg_standby</literal> to function correctly with PostgreSQL 8.2 
+    also. With PostgreSQL 8.2, the <literal>-k</literal> option must be used if 
+    archive cleanup is required. This option remains available in 8.3.
+   </para>
+  </sect2>
+ 
+  <sect2>
+   <title>Additional design notes</title>
+   <para>
+    The use of a move command seems like it would be a good idea, but this would
+    prevent recovery from being restartable. Also, the last WAL file is always 
+    requested twice from the archive.
+   </para>
+  </sect2>
+ 
+  <sect2>
    <title>Examples</title>
  
    <itemizedlist>
***************
*** 228,235 ****
       *not* in the restore_command, in 8.2, 8.1, 8.0 on Windows.
      </para>
      <programlisting>
! restore_command = 'pg_standby -c -d -s 5 -w 0 -t C:\pgsql.trigger.5442
!  ..\archive %f %p 2>> standby.log'
      </programlisting>
      <para>
       which will
--- 281,287 ----
       *not* in the restore_command, in 8.2, 8.1, 8.0 on Windows.
      </para>
      <programlisting>
! restore_command = 'pg_standby -c -d -s 5 -w 0 -t C:\pgsql.trigger.5442 ..\archive %f %p 2>> standby.log'
      </programlisting>
      <para>
       which will

--Boundary-00=_PG0UHtbGCmLkang--