360 lines
8.5 KiB
Groff
360 lines
8.5 KiB
Groff
.\" This is -*-nroff-*-
|
|
.\" XXX standard disclaimer belongs here....
|
|
.\" $Header: /cvsroot/pgsql/doc/man/Attic/psql.1,v 1.1.1.1 1996/08/18 22:14:26 scrappy Exp $
|
|
.TH PSQL UNIX 1/20/96 Postgres95 Postgres95
|
|
.SH NAME
|
|
psql \(em run the interactive query front-end
|
|
.SH SYNOPSIS
|
|
.BR psql
|
|
[\c
|
|
.BR "-a"
|
|
authsvc
|
|
]
|
|
[\c
|
|
.BR "-A"
|
|
]
|
|
[\c
|
|
.BR "-c"
|
|
query
|
|
]
|
|
[\c
|
|
.BR "-d"
|
|
dbName]
|
|
[\c
|
|
.BR "-e"
|
|
]
|
|
[\c
|
|
.BR "-f"
|
|
filename]
|
|
[\c
|
|
.BR "-h"
|
|
hostname]
|
|
[\c
|
|
.BR "-H"
|
|
]
|
|
[\c
|
|
.BR "-l"
|
|
port]
|
|
[\c
|
|
.BR "-n"
|
|
]
|
|
[\c
|
|
.BR "-o"
|
|
filename
|
|
]
|
|
[\c
|
|
.BR "-p"
|
|
port]
|
|
[\c
|
|
.BR "-q"
|
|
]
|
|
[\c
|
|
.BR "-s"
|
|
]
|
|
[\c
|
|
.BR "-S"
|
|
]
|
|
[\c
|
|
.BR "-t"
|
|
]
|
|
[\c
|
|
.BR "-x"
|
|
]
|
|
[dbname]
|
|
.in -5n
|
|
.SH DESCRIPTION
|
|
psql is a interactive query front-end to Postgres. It enables you to
|
|
type in queries interactively, issue them to Postgres, and see the query
|
|
results.
|
|
.IR psql
|
|
can be used in a pipe sequence, and automatically detects when it
|
|
is not listening or talking to a real tty.
|
|
.IR psql
|
|
is designed to be an enhanced version of the older
|
|
.IR "monitor"
|
|
program.
|
|
.PP
|
|
.IR "psql"
|
|
is a frontend application, like any other. Hence, a
|
|
.IR "postmaster"
|
|
process must be running on the database server host before
|
|
.IR "psql"
|
|
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.
|
|
.IR dbname
|
|
defaults to the value of the
|
|
.SM USER
|
|
environment variable or, if that's not set, to the Unix account name of the
|
|
current user.
|
|
.PP
|
|
.IR "psql"
|
|
understands the following command-line options:
|
|
.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 "-A"
|
|
Turn off fill justification when printing out attributes.
|
|
.TP
|
|
.BR "-c" " query"
|
|
Specifies that
|
|
.IR "psql"
|
|
is to execute one query string,
|
|
.IR "query" ,
|
|
and then exit. This is useful for shell scripts, typically in
|
|
conjunction with the
|
|
.BR -q ""
|
|
options.
|
|
.BR -c
|
|
option in shell scripts.
|
|
.TP
|
|
.BR "-d" " dbName"
|
|
Specifies the name of the database to connect to.
|
|
.TP
|
|
.BR "-e" " "
|
|
Echo the query sent to the backend
|
|
.TP
|
|
.BR "-f" " filename"
|
|
Use the file
|
|
.IR "filename"
|
|
as the source of queries instead of reading queries interactively.
|
|
.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 "-H"
|
|
Turns on
|
|
.SM HTML3.0
|
|
tabular output.
|
|
.TP
|
|
.BR "-l"
|
|
Lists all available databases
|
|
.TP
|
|
.BR "-n"
|
|
Do not use the readline library for input line editing and command history.
|
|
.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
|
|
.IR psql
|
|
should do its work quietly. By default, it
|
|
prints welcome and exit messages and prompts for each query, and prints
|
|
out the number of rows returned from a query.
|
|
If this option is used, none of this happens. This is useful with the
|
|
.BR -c
|
|
option in shell scripts.
|
|
.TP
|
|
.BR "-s"
|
|
Run in single-step mode where the user at prompted for each query before
|
|
it is sent to the backend.
|
|
.TP
|
|
.BR "-S"
|
|
Run ins single-line mode where each query is terminated by a newline,
|
|
instead of a semicolon.
|
|
.TP
|
|
.BR "-t"
|
|
Turn off printing of attributes names.
|
|
This is useful with the
|
|
.BR -c
|
|
option in shell scripts.
|
|
.TP
|
|
.BR "-x"
|
|
Turns on extended field mode. When enabled each tuple will have its field
|
|
names printed on the left with the field values printed on the right.
|
|
This is useful for tuples which are otherwise too long to fit into
|
|
one screen line. HTML tuple output supports this mode also.
|
|
.PP
|
|
You may set environment variables to avoid typing some of the above
|
|
options. See the
|
|
.SM "ENVIRONMENT VARIABLES"
|
|
section below.
|
|
.SH "CONNECTING TO A DATABASE"
|
|
.IR psql
|
|
attempts to make a connection to the database at the hostname and
|
|
port number specified on the command line. If the connection could not
|
|
be made for any reason (e.g. insufficient privileges, postmaster is not
|
|
running on the server, etc)
|
|
.IR psql
|
|
will return an error that says
|
|
.nf
|
|
Connection to database failed.
|
|
.fi
|
|
The reason for the connection failure is not provided.
|
|
.SH "ENTERING QUERIES"
|
|
In normal operation, psql provides a prompt with the name of the
|
|
database that psql is current connected to followed by the string "=>".
|
|
For example,
|
|
.nf
|
|
Welcome to the POSTGRES95 interactive sql monitor:
|
|
Please read the file COPYRIGHT for copyright terms of POSTGRES95
|
|
|
|
type \e? for help on slash commands
|
|
type \eq to quit
|
|
type \eg or terminate with semicolon to execute query
|
|
You are currently connected to the database: testdb
|
|
|
|
testdb=>
|
|
.fi
|
|
.PP
|
|
At the prompt, the user may type in SQL queries. Unless the -S option
|
|
is set, input lines are sent to the backend when a query-terminating
|
|
semicolon is reached.
|
|
.PP
|
|
Whenever a query is executed, psql also polls for asynchronous notification
|
|
events generated by
|
|
.IR listen (l)
|
|
and
|
|
.IR notify (l).
|
|
.PP
|
|
.SH "PSQL COMMANDS"
|
|
.IP "\ea"
|
|
Toggle field alignment when printing out attributes.
|
|
.IP "\eC \fIcaption\fR"
|
|
Set the HTML3.0 table caption.
|
|
.IP "\ec \fIdbname\fR"
|
|
Establish a connection to a new database. The previous connection is closed.
|
|
.IP "\ed [\fItable\fR]"
|
|
List tables in the database, or if
|
|
.IR table
|
|
is specified, list the columns in
|
|
.IR table.
|
|
If table name is
|
|
.IR *,
|
|
list all tables and column information for each tables.
|
|
.IP "\ee [\fIfilename\fR]"
|
|
Edit the current query buffer or \fIfile\fR.
|
|
.IP "\eE [\fIfilename\fR]"
|
|
Edit the current query buffer or \fIfile\fR and execute it
|
|
upon editor exit.
|
|
.IP "\ef [\fIseparator\fR]"
|
|
Set the field separator. Default is a single blank space.
|
|
.IP "\eg [\fI|command\fR] | [\fIfilename\fR]"
|
|
Send the current query input buffer to the backend and optionally
|
|
save the output in
|
|
.IR filename
|
|
or pipe the output into
|
|
.IR "|command".
|
|
.IP "\eh [\fIcommand\fR]"
|
|
Give syntax help on the specified SQL command. If the
|
|
.IR command
|
|
is not specified, list all the commands for which syntax help is
|
|
available. If the
|
|
.IR command
|
|
is
|
|
.IR *,
|
|
give syntax help on all SQL commands.
|
|
.IP "\eH"
|
|
Toggle html3 output.
|
|
.IP "\ei \fIfilename\fR"
|
|
Read queries from
|
|
.IR filename
|
|
into the query input buffer.
|
|
.IP "\el"
|
|
List all the databases in the server.
|
|
.IP "\em"
|
|
Toggle monitor-like table display.
|
|
This is standard SQL output (i.e extra border characters).
|
|
.IP "\eo [\fI|command\fR] | [\fIfilename\fR]"
|
|
Send query results to
|
|
.IR filename .
|
|
Or pipe into
|
|
.IR command .
|
|
If no arguments are specified, send query results to
|
|
.IR stdout .
|
|
.IP "\ep"
|
|
Print the current query buffer.
|
|
.IP \eq
|
|
Quit the psql program.
|
|
.IP "\er"
|
|
Reset(clear) the query buffer.
|
|
.IP "\es [\fIfilename\fR]"
|
|
Print or save the command line history to \fIfilename\fR. (Only available if psql is
|
|
configured to use readline)
|
|
.IP "\et"
|
|
Toggle display of output attribute name headings and row count (defaults to on).
|
|
.IP "\eT"
|
|
Set html3.0 <table ...> options.
|
|
.IP "\ex"
|
|
Toggles extended field mode. When enabled each tuple will have its field
|
|
names printed on the left with the field values printed on the right.
|
|
This is useful for tuples which are otherwise too long to fit into
|
|
one screen line. HTML tuple output mode supports this flag too.
|
|
.IP "\e! [\fIcommand\fR]"
|
|
Escape to shell or execute
|
|
.IR command.
|
|
.IP \e?
|
|
Get help information about the \e commands.
|
|
.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 psql
|
|
returns 0 to the shell on successful query completion, 1 otherwise.
|
|
.IR psql
|
|
will also return 1 if the connection to a database could not be made for
|
|
any reason.
|
|
.SH "SEE ALSO"
|
|
introduction(libpq),
|
|
monitor(1)
|
|
postgres(1),
|
|
postmaster(1).
|
|
.SH BUGS
|
|
If multiple queries are sent to the backend at once without semicolon
|
|
termination after each query, psql gets confused about the query
|
|
results. The queries will still be processed correctly by the backend.
|
|
|