Chapter 6 The SQL REPL — An Interactive Setup j 57
The query in the report.sql le uses the :'name' variable syntax. Using :name would be missing the quotes around the literal value injected, and :'' allows one to remedy this even with values containing spaces. psql also supports :"variable" notation for double-quoting values, which is used for dynamic SQL when identi ers are a parameter (column name or table names).
1 select surname, races.name, races.year, results.position
2from results
3join drivers using(driverid)
4join races using(raceid)
5where drivers.surname = :'name'
6 |
and position between 1 and 3 |
7 |
order by position |
8limit :n;
When running psql for reports, it might be good to have a speci c setup. In this example, you can see I’ve been using the --no-psqlrc switch to be sure we’re not loading my usual interactive setup all with all the UTF-8 bells and whistles, and with ON_ERROR_ROLLBACK. Usually, you don’t want to have that set for a reporting or a batch script.
You might want to set ON_ERROR_STOP though, and maybe some other options.
Discovering a Schema
Let’s get back to the interactive features of psql. The tool’s main task is to send SQL statements to the database server and display the result of the query, and also server noti cations and error messages. On top of that psql provides a set of client-side commands all beginning with a backslash character.
Most of the provided commands are useful for discovering a database schema. All of them are implemented by doing one or several catalog queri against the server. Again, it’s sending a SQL statement to the server, and it is possible for you to learn how to query the PostgreSQL catalogs by reviewing those queries.
As an example, say you want to report the size of your databases but you don’t know where to look for that information. Reading the psql documentation you ndthatthe \l+ commandcandothat, andnowyouwanttoseetheSQLbehind it:
~# \set ECHO_HIDDEN true
Chapter 6 The SQL REPL — An Interactive Setup j 58
~# \l+
********* QUERY **********
SELECT d.datname as "Name", pg_catalog.pg_get_userbyid(d.datdba) as "Owner",
pg_catalog.pg_encoding_to_char(d.encoding) as "Encoding", d.datcollate as "Collate",
d.datctype as "Ctype",
pg_catalog.array_to_string(d.datacl, E'\n') AS "Access privileges", CASE WHEN pg_catalog.has_database_privilege(d.datname, 'CONNECT')
THEN pg_catalog.pg_size_pretty(pg_catalog.pg_database_size(d.datname)) ELSE 'No Access'
END as "Size",
t.spcname as "Tablespace",
pg_catalog.shobj_description(d.oid, 'pg_database') as "Description" FROM pg_catalog.pg_database d
JOIN pg_catalog.pg_tablespace t on d.dattablespace = t.oid ORDER BY 1;
**************************
List of databases
...
~# \set ECHO_HIDDEN false
So now if you only want to have the database name and its on-disk size in bytes, it is as easy as running the following query:
1SELECT datname,
2 |
pg_database_size(datname) as bytes |
3 |
FROM pg_database |
4ORDER BY bytes desc;
There’s not much point in this book including the publicly available documentation of all the commands available in psql, so go read the whole manual page to nd gems you didn’t know about — there are plenty of them!
Interactive Query Editor
You might have noticed that we did set the EDITOR environment variable early in this section. This is the command used by psql each time you use visual editing commands such as \e. This command launches your EDITOR on the last edited query (or an empty one) in a temporary le, and will execute the query once you end the editing session.
If you’re using emacs or vim typing with a full-blown editor from within a terminal, it is something you will be very happy to do. In other cases, it is, of course, possible to set EDITOR to invoke your favorite IDE if your psql client runs lo-
Chapter 6 The SQL REPL — An Interactive Setup j 59
cally.