.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /usr/local/devel/postgres/src/ref/unix/RCS/vacuum.1src,v 1.3 1994/02/09 10:55:11 aoki Exp $
.TH VACUUM UNIX 02/08/94
.XA 1 Vacuum
.SH NAME
vacuum \(em vacuum a database
.SH SYNOPSIS
.BR vacuum
[\c
.BR -a
system]
[\c
.BR -h
host]
[\c
.BR -p
port]
[dbname]
.SH DESCRIPTION
.IR Vacuum
vacuums a \*(PG database.
Vacuuming a database moves deleted records to an archive
(for archived classes; see 
.IR create (commands)),
cleans out records from aborted transactions, and updates statistics
that are stored in the system catalogs and used by the query
optimizer.  Databases should be vacuumed periodically, if for no other
reason than to update the statistics (which make the system run more
efficiently).  We recommend using using a mechanism such as
.IR "cron" (1)
or 
.IR "at" (1)
to vacuum production databases on a nightly basis.
.PP
.IR Vacuum
is a shell script that invokes
.IR monitor .
Hence, a
.IR postmaster
process must be running on the database server host before
.IR vacuum 
is executed.  In addition, the 
.SM PGOPTION
and
.SM PGREALM
environment variables will be passed on to
.IR monitor
and processed as described in 
.IR monitor (unix).
.PP
The optional argument
.IR dbname
specifies the name of the database to be vacuumed.
.IR Dbname
defaults to the value of the 
.SM USER
environment variable.
.PP
.IR Vacuum
understands the following command-line options:
.TP 5n
.BR "-a" " system"
Specifies an authentication system 
.IR "system"
(see 
.IR introduction (unix))
to use in connecting to the 
.IR postmaster
process.  The default is site-specific.
.TP
.BR "-h" " host"
Specifies the hostname of the machine on which the 
.IR postmaster
is running.  Defaults to the name of the local host, or the value of
the
.SM PGHOST
environment variable (if set).
.TP
.BR "-p" " port"
Specifies the Internet TCP port on which the
.IR postmaster
is listening for connections.  Defaults to 4321, or the value of the
.SM PGPORT
environment variable (if set).
.SH "SEE ALSO"
monitor(unix),
postmaster(unix),
vacuum(commands).
.SH DIAGNOSTICS
.TP 5n
.BI "Error: Failed to connect to backend (host=" "xxx" ", port=" "xxx" ")"
.IR Vacuum
could not attach to the 
.IR postmaster 
process on the specified host and port.  If you see this message,
ensure that the
.IR postmaster
is running on the proper host and that you have specified the proper
port.  If your site uses an authentication system, ensure that you
have obtained the required authentication credentials.
.TP
.BI "user \*(lq" "username" "\*(rq is not in \*(lqpg_user\*(rq"
You do not have a valid entry in the relation \*(lqpg_user\*(rq and
cannot do anything with \*(PG at all; contact your \*(PG site
administrator.
.TP 
.BI "can't create lock file -- another vacuum cleaner running?"
Although 
.IR vacuum
uses standard \*(PG locking to prevent problems with concurrent 
access to data, \*(PG attempts to prevent more than one 
.IR vacuum
process from running at once (which is guaranteed to cause
deadlock, since both processes write to the entire database)
by creating the file
.(C
\&.../data/base/<database>/pg_vlock
.)C
If the 
.IR vacuum
process crashes before removing this file, future 
.IR vacuum
processes will be unable to start.  If you see this message and
you know for certain that no other 
.IR vacuum
process is running, contact your \*(PG database administrator
in order to have the lock file removed.
.SH BUGS
\*(PG does not reclaim space in the classes that have been
vacuumed.  Furthermore, new tuples are always placed at the
end of a heap class.  Consequently, contrary to what you 
might expect, classes never shrink and the
.BR vacuum
command does not slow down the rate of growth.  However, it 
does update statistics and speed up scans of the classes
(by removing invalid instances) as advertised.