MONITOR(UNIX)

NAME
monitor — run the interactive terminal monitor

SYNOPSIS
monitor [-N ] [-Q ] [-T ] [-a system] [-c query] [-d path]
[-h hostname] [-p port] [-q ] [-t tty_device] [dbname]

DESCRIPTION
The interactive terminal monitor is a simple frontend to Postgres retained for backwards compatiblity. Users are encouraged to the use the psql interface instead.

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 query buffer managed by the terminal monitor. The editor used is determined by the value of the EDITOR environment variable. If EDITOR is not set, then vi is used by default.

Monitor is a frontend application, like any other. Hence, a postmaster process must be running on the database server host before monitor is executed. In addition, the correct postmaster port number must be specified as described below.

The optional argument dbname specifies the name of the database to be accessed. This database must already have been created using createdb. Dbname defaults to the value of the USER environment variable.

Monitor understands the following command-line options:

-N  Specifies that query results will be dumped to the screen without any attempt at formatting. This is useful in with the -c option in shell scripts.

-Q  Produces extremely unverbose output. This is useful with the -c option in shell scripts.

-T  Specifies that attribute names will not be printed. This is useful with the -c option in shell scripts.

-a system
    Specifies an authentication system system (see pgintro(1)) to use in connecting to the postmaster process. The default is site-specific.

-c query
    Specifies that monitor is to execute one query string, query, and then exit. This is useful for shell scripts, typically in conjunction with the -N and -T options. Examples of shell scripts in the Postgres distribution using monitor -c include createdb, destroydb, createuser, and destroyuser,

-d path
    path specifies the path name of the file or tty to which frontend (i.e., monitor) debugging messages are to be written; the default is not to generate any debugging messages.

-h hostname
    Specifies the hostname of the machine on which the postmaster is running. Defaults to the name of the local host, or the value of the PGHOST environment variable (if set).

-p port
    Specifies the Internet TCP port on which the postmaster is listening for connections. Defaults to 5432, or the value of the PGPORT environment variable (if set).

-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.

-t tty_device
    tty_device specifies the path name to the file or tty to which backend (i.e., postgres) debugging messages are to be written; the default is /dev/null.

-s  parses after each query (enables "single step" mode).

-S  Turns off sending query when ";" is encountered.

You may set environment variables to avoid typing some of the above options. See the ENVIRONMENT VARIABLES section below.

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.

The terminal monitor displays two kinds of messages:

go  The query buffer is empty and the terminal monitor is ready for input. Anything typed will be added to the buffer.

*   This prompt is typed at the beginning of each line when the terminal monitor is waiting for input.

TERMINAL MONITOR COMMANDS

\e  Enter the editor to edit the query buffer.

\g  Submit query buffer to Postgres for execution.

\h  Get on-line help.

\i filename
    Include the file filename into the query buffer.

\p  Print the current contents of the query buffer.

\q  Exit from the terminal monitor.

\r  Reset (clear) the query buffer.

\s  Escape to a Unix subshell. To return to the terminal monitor, type “exit” at the shell prompt.

\t  Print the current time.

\w filename
    Store (write) the query buffer to an external file filename.

\\  Produce a single backslash at the current location in query buffer.

\;  Produce a single semi-colon at the current location in query buffer.

ENVIRONMENT VARIABLES
You may set any of the following environment variables to avoid specifying command-line options:
hostname:	PGHOST
port:		PGPORT
tty:		PGTTY
options:		PGOPTION
realm:		PGREALM

If PGOPTION is specified, then the options it contains are parsed before any command-line options.

PGREALM only applies if 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 pgintro(1) for additional information on Kerberos.

See pgintro(libpq) for additional details.

RETURN VALUE
When executed with the -c option, monitor returns 0 to the shell on successful query completion, 1 otherwise.

SEE ALSO
libpq(3), createdb(1), createuser(1), postgres(1), postmaster(1).

BUGS
Does not poll for asynchronous notification events generated by listen(l) and notify(l).

Escapes (backslash characters) cannot be commented out.

SEE ALSO
psql(1)