psql is a terminal-based front-end to PostgreSQL. It enables you to type in queries interactively, issue them to PostgreSQL, and see the query results. Alternatively, input can come from a file. psql also provides a number of meta-commands and various shell-like features to facilitate writing scripts and automating a wide variety of tasks.
This chapter describes how to use psql and the commands and features it provides.
psql is a regular PostgreSQL client application. In order to connect to a database you need to know the name of your target database, the hostname and port number of the server and what user name you want to connect as. You can tell psql about those parameters via command line options, namely -d, -h, -p, and -U respectively. If an argument is found that does not belong to any option it will be interpreted as the database name (or the user name, if the database name is also given). Not all these options are required, defaults do apply. If you omit the host name psql will connect via a UNIX domain socket to a server on the local host. The default port number is compile-time determined. Since the database server uses the same default, you will not have to specify the port in most cases. The default user name is your Linux username, as is the default database name. Note that you cannot just connect to any database under any username. Your database administrator should have informed you about your access rights. To save you some typing you can also set the environment variables PGDATABASE, PGHOST, PGPORT and PGUSER to appropriate values.
If the connection could not be made for any reason (for example, insufficient privileges, postmaster is not running on the server, etc.), psql will return an error and terminate.
In normal operation, psql provides a prompt with the name of the database to which psql is currently connected, followed by the string "=>". The syntax is:
psql [options] [dbname [user]] |
For example:
$ psql testdb
Welcome to psql, the PostgreSQL interactive terminal.
Type: \copyright for distribution terms
\h for help with SQL commands
\? for help on internal slash commands
\g or terminate with semicolon to execute query
\q to quit
testdb=> |
At the prompt, the user may type in SQL queries. Ordinarily, input lines are sent to the backend when a query-terminating semicolon is reached. An end-of-line does not terminate a query. Queries can be spread over several lines for clarity. If the query was sent and without error, the query results are displayed on the screen.
Whenever a query is executed, psql also polls for asynchronous notification events generated by LISTEN and NOTIFY.