1 files changed, 61 insertions, 0 deletions
diff --git a/doc/man/purge.l b/doc/man/purge.l
new file mode 100644
index 00000000000..9e1f68a99f9
--- /dev/null
+++ b/doc/man/purge.l
@@ -0,0 +1,61 @@
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.TH PURGE SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+purge \(em discard historical data
+.SH SYNOPSIS
+.nf
+\fBpurge\fR classname [ \fBbefore\fR abstime ] [ \fBafter\fR reltime ]
+.fi
+.SH DESCRIPTION
+.BR Purge
+allows a user to specify the historical retention properties of a
+class.  If the date specified is an absolute time such as \*(lqJan 1
+1987\*(rq, Postgres will discard tuples whose validity expired before
+the indicated time.
+.BR Purge 
+with no
+.IR before
+clause is equivalent to \*(lqpurge before now\*(rq. Until specified
+with a purge command, instance preservation defaults to
+\*(lqforever\*(rq.
+.PP
+The user may purge a class at any time as long as the purge date never
+decreases.  Postgres will enforce this restriction, silently.
+.PP
+Note that the 
+.BR purge
+command does not do anything except set a parameter for system 
+operation.  Use
+.IR vacuum (l)
+to enforce this parameter.
+.SH EXAMPLE
+.nf
+--
+--Always discard data in the EMP class
+--prior to January 1, 1989
+--
+purge EMP before "Jan 1 1989"
+.fi
+.nf
+--
+--Retain only the current data in EMP
+--
+purge EMP
+.fi
+.SH "SEE ALSO"
+vacuum(l).
+.SH "BUGS AND CAVEATS"
+Error messages are quite unhelpful.  A complaint about
+\*(lqinconsistent times\*(rq followed by several nine-digit numbers
+indicates an attempt to \*(lqback up\*(rq a purge date on a relation.
+.PP
+You cannot purge certain system catalogs (namely, \*(lqpg_class\*(rq,
+\*(lqpg_attribute\*(rq, \*(lqpg_am\*(rq, and \*(lqpg_amop\*(rq) due 
+to circularities in the system catalog code.
+.PP
+This definition of the 
+.BR purge
+command is really only useful for non-archived relations, since 
+tuples will not be discarded from archive relations (they are 
+never vacuumed).