270 lines
6.0 KiB
Groff
270 lines
6.0 KiB
Groff
.\" This is -*-nroff-*-
|
|
.\" XXX standard disclaimer belongs here....
|
|
.\" $Header: /cvsroot/pgsql/doc/man/Attic/monitor.1,v 1.1.1.1 1996/08/18 22:14:25 scrappy Exp $
|
|
.TH MONITOR UNIX 11/05/95 Postgres95 Postgres95
|
|
.SH NAME
|
|
monitor \(em run the interactive terminal monitor
|
|
.SH SYNOPSIS
|
|
.BR monitor
|
|
[\c
|
|
.BR "-N"
|
|
]
|
|
[\c
|
|
.BR "-Q"
|
|
]
|
|
[\c
|
|
.BR "-T"
|
|
]
|
|
[\c
|
|
.BR "-a"
|
|
system]
|
|
[\c
|
|
.BR "-c"
|
|
query]
|
|
[\c
|
|
.BR "-d"
|
|
path]
|
|
.br
|
|
.in +5n
|
|
[\c
|
|
.BR "-h"
|
|
hostname]
|
|
[\c
|
|
.BR "-p"
|
|
port]
|
|
[\c
|
|
.BR "-q"
|
|
]
|
|
[\c
|
|
.BR "-t"
|
|
tty_device]
|
|
[dbname]
|
|
.in -5n
|
|
.SH DESCRIPTION
|
|
The interactive terminal monitor is a simple frontend to Postgres retained
|
|
for backwards compatiblity. Users are encouraged to the use the
|
|
.IR "psql"
|
|
interface instead.
|
|
.PP
|
|
.IR "monitor"
|
|
enables you to formulate, edit and review queries before issuing them
|
|
to Postgres. If changes must be made, a Unix editor may be called
|
|
to edit the
|
|
.BR "query buffer"
|
|
managed by the terminal monitor. The editor used is determined by the
|
|
value of the
|
|
.SM EDITOR
|
|
environment variable. If
|
|
.SM EDITOR
|
|
is not set, then
|
|
.BR "vi"
|
|
is used by default.
|
|
.PP
|
|
.IR "Monitor"
|
|
is a frontend application, like any other. Hence, a
|
|
.IR "postmaster"
|
|
process must be running on the database server host before
|
|
.IR "monitor"
|
|
is executed. In addition, the correct
|
|
.IR "postmaster"
|
|
port number must be specified
|
|
as described below.
|
|
.PP
|
|
The optional argument
|
|
.IR dbname
|
|
specifies the name of the database to be accessed. This database must
|
|
already have been created using
|
|
.IR createdb .
|
|
.IR Dbname
|
|
defaults to the value of the
|
|
.SM USER
|
|
environment variable.
|
|
.PP
|
|
.IR "Monitor"
|
|
understands the following command-line options:
|
|
.TP 5n
|
|
.BR "-N"
|
|
Specifies that query results will be dumped to the screen without any
|
|
attempt at formatting. This is useful in with the
|
|
.BR -c
|
|
option in shell scripts.
|
|
.TP
|
|
.BR "-Q"
|
|
Produces extremely unverbose output.
|
|
This is useful
|
|
with the
|
|
.BR -c
|
|
option in shell scripts.
|
|
.TP
|
|
.BR "-T"
|
|
Specifies that attribute names will not be printed.
|
|
This is useful
|
|
with the
|
|
.BR -c
|
|
option in shell scripts.
|
|
.TP
|
|
.BR "-a" " system"
|
|
Specifies an authentication system
|
|
.IR "system"
|
|
(see
|
|
.IR introduction (1))
|
|
to use in connecting to the
|
|
.IR postmaster
|
|
process. The default is site-specific.
|
|
.TP
|
|
.BR "-c" " query"
|
|
Specifies that
|
|
.IR "monitor"
|
|
is to execute one query string,
|
|
.IR "query" ,
|
|
and then exit. This is useful for shell scripts, typically in
|
|
conjunction with the
|
|
.BR -N
|
|
and
|
|
.BR -T
|
|
options. Examples of shell scripts in the Postgres distribution using
|
|
.IB "monitor" " -c"
|
|
include
|
|
.IR createdb ,
|
|
.IR destroydb ,
|
|
.IR createuser ,
|
|
and
|
|
.IR destroyuser ,
|
|
.TP
|
|
.BR "-d" " path"
|
|
.IR path
|
|
specifies the path name of the file or tty to which frontend (i.e.,
|
|
.IR monitor )
|
|
debugging messages are to be written; the default is not to generate
|
|
any debugging messages.
|
|
.TP
|
|
.BR "-h" " hostname"
|
|
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 5432, or the value of the
|
|
.SM PGPORT
|
|
environment variable (if set).
|
|
.TP
|
|
.BR "-q"
|
|
Specifies that the monitor should do its work quietly. By default, it
|
|
prints welcome and exit messages and the queries it sends to the
|
|
backend. If this option is used, none of this happens.
|
|
.TP
|
|
.BR "-t" " tty_device"
|
|
.IR "tty_device"
|
|
specifies the path name to the file or tty
|
|
to which backend (i.e.,
|
|
.IR postgres )
|
|
debugging messages are to be written; the default is
|
|
.IR "/dev/null" .
|
|
.TP
|
|
.BR "-s"
|
|
parses after each query (enables "single step" mode).
|
|
.TP
|
|
.BR "-S"
|
|
Turns off sending query when ";" is encountered.
|
|
.PP
|
|
You may set environment variables to avoid typing some of the above
|
|
options. See the
|
|
.SM "ENVIRONMENT VARIABLES"
|
|
section below.
|
|
.SH "MESSAGES AND PROMPTS"
|
|
The terminal monitor gives a variety of messages to keep the user
|
|
informed of the status of the monitor and the query buffer.
|
|
.PP
|
|
The terminal monitor displays two kinds of messages:
|
|
.IP go
|
|
The query buffer is empty and the terminal monitor is ready for input.
|
|
Anything typed will be added to the buffer.
|
|
.IP *
|
|
This prompt is typed at the beginning of each line when the terminal
|
|
monitor is waiting for input.
|
|
.SH "TERMINAL MONITOR COMMANDS"
|
|
.IP \ee
|
|
Enter the editor to edit the query buffer.
|
|
.IP \eg
|
|
Submit query buffer to Postgres for execution.
|
|
.IP \eh
|
|
Get on-line help.
|
|
.IP "\ei \fIfilename\fR"
|
|
Include the file
|
|
.IR filename
|
|
into the query buffer.
|
|
.IP \ep
|
|
Print the current contents of the query buffer.
|
|
.IP \eq
|
|
Exit from the terminal monitor.
|
|
.IP \er
|
|
Reset (clear) the query buffer.
|
|
.IP \es
|
|
Escape to a Unix subshell. To return to the terminal monitor, type
|
|
\*(lqexit\*(rq at the shell prompt.
|
|
.IP \et
|
|
Print the current time.
|
|
.IP "\ew \fIfilename\fR"
|
|
Store (write) the query buffer to an external file
|
|
.IR filename .
|
|
.IP \e\e
|
|
Produce a single backslash at the current location in query buffer.
|
|
.IP \e;
|
|
Produce a single semi-colon at the current location in query buffer.
|
|
.SH "ENVIRONMENT VARIABLES"
|
|
You may set any of the following environment variables to avoid
|
|
specifying command-line options:
|
|
.nf
|
|
hostname: PGHOST
|
|
port: PGPORT
|
|
tty: PGTTY
|
|
options: PGOPTION
|
|
realm: PGREALM
|
|
.fi
|
|
.PP
|
|
If
|
|
.SM PGOPTION
|
|
is specified, then the options it contains are parsed
|
|
.BR before
|
|
any command-line options.
|
|
.PP
|
|
.SM PGREALM
|
|
only applies if
|
|
.IR Kerberos
|
|
authentication is in use. If this environment variable is set, Postgres
|
|
will attempt authentication with servers for this realm and use
|
|
separate ticket files to avoid conflicts with local ticket files. See
|
|
.IR introduction (1)
|
|
for additional information on
|
|
.IR Kerberos .
|
|
.PP
|
|
See
|
|
.IR introduction (libpq)
|
|
for additional details.
|
|
.SH "RETURN VALUE"
|
|
When executed with the
|
|
.BR "-c"
|
|
option,
|
|
.IR monitor
|
|
returns 0 to the shell on successful query completion, 1 otherwise.
|
|
.SH "SEE ALSO"
|
|
introduction(libpq),
|
|
createdb(1),
|
|
createuser(1),
|
|
postgres(1),
|
|
postmaster(1).
|
|
.SH BUGS
|
|
Does not poll for asynchronous notification events generated by
|
|
.IR listen (l)
|
|
and
|
|
.IR notify (l).
|
|
.PP
|
|
Escapes (backslash characters) cannot be commented out.
|
|
.SH "SEE ALSO"
|
|
psql(1)
|