mirror of
https://github.com/postgres/postgres.git
synced 2025-06-23 14:01:44 +03:00
moved man pages here, as requested by Bryan
This commit is contained in:
Marc G. Fournier
359
src/man/psql.1
Normal file
359
src/man/psql.1
Normal file
@ -0,0 +1,359 @@
|
||||
.\" This is -*-nroff-*-
|
||||
.\" XXX standard disclaimer belongs here....
|
||||
.\" $Header: /cvsroot/pgsql/src/man/Attic/psql.1,v 1.1 1996/11/14 10:17:50 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.
|
||||
|
||||
Reference in New Issue
Block a user