Перейти к основному содержимому

Работа с psql

Рассмотрим возможности интерактивного клиента psql. psql предоставляет богатый набор функций – от простого выполнения запросов до сложного форматирования вывода, работы с переменными и автоматизации задач.

Форматирование вывода​

По умолчанию psql выводит результаты запросов в выровненном табличном виде с заголовками столбцов. Но часто требуется изменить формат вывода, например, для последующей обработки другими программами.

Рассмотрим пример с генерацией числового ряда:

postgres=# SELECT min(g.i), max(g.i), avg(g.i) FROM generate_series(0,10) as g(i);
min  | max | avg
-----+-----+--------------------
   0 |  10 | 5.0000000000000000
(1 row)

Изменим формат вывода:

postgres=# \a \t
Output format is unaligned.
Tuples only is on.

Клиент psql поддерживает различные форматы вывода результатов запроса. Например, можно отключить вывод заголовков – \t, а также отказаться от выравнивания – \a.

Данные метакоманды работают как переключатели. Чтобы вернуть стандартные значения параметров форматирования, следует их выполнить повторно.

Посмотрим на вывод той же команды после изменений:

postgres=# SELECT min(g.i), max(g.i), avg(g.i) FROM generate_series(0,10) as g(i);
0|10|5.0000000000000000

Это не совсем удобно для восприятия информации человеком, но необходимо, если результат запроса перенаправляется в другую программу или файл для последующей обработки.

Посмотреть на все установленные параметры psql, влияющие на форматирование, можно командой \pset:

postgres=# \pset
border                   1
columns                  0
csv_fieldsep             ','
expanded                 off
fieldsep                 '|'
fieldsep_zero            off
footer                   on
format                   aligned
linestyle                ascii
null                     ''
numericlocale            off
pager                    1
pager_min_lines          0
recordsep                '\n'
recordsep_zero           off
tableattr
title
tuples_only              off
unicode_border_linestyle single
unicode_column_linestyle single
unicode_header_linestyle single

Этой же командой можно детально настроить форматирование (\pset <параметр> <значение>), например, сделать пробел разделителем:

postgres=# \pset fieldsep ' '
Field separator is " ".
postgres=# SELECT min(g.i), max(g.i), avg(g.i) FROM generate_series(0,10) as g(i);
0 10 5.0000000000000000

Для смены разделителя также есть метакоманда \f.

Примечание

Изменение параметров форматирования, равно и как изменение общих параметров psql командой \set, сохраняется только в рамках запущенного экземпляра psql. После перезапуска psql параметры будут сброшены.

Для постоянного сохранения настроек нужно поместить соответствующие команды в файл .psqlrc, тогда они будут выполняться при каждом запуске программы.

Коротко о главном:

  • \a — выравнивание;
  • \t — вывод только строк;
  • \f — разделитель полей;
  • \pset — детальная настройка форматирования;
  • метакоманды форматирования работают как переключатели.

Расширенный вывод​

Когда в запросе много столбцов и вывод не помещается по горизонтали, удобно использовать расширенный (вертикальный) вывод.

Чтобы установить расширенный вывод только для одного запроса, нужно вместо завершения команды символом точка с запятой ; указать метакоманду \gx:

postgres=# SELECT min(i), max(i), avg(i) FROM generate_series(0,10) g(i) \gx
-[ RECORD 1 ]-----------
min | 0
max | 10
avg | 5.0000000000000000

Режим расширенного вывода устанавливается метакомандой \x:

postgres=# \x
Expanded display is on.
postgres=# SELECT min(g.i), max(g.i), avg(g.i) FROM generate_series(0,10) as g(i);
-[ RECORD 1 ]-----------
min | 0
max | 10
avg | 5.0000000000000000
Коротко о главном:

  • \x — переключение в режим расширенного вывода;
  • Поля строк в расширенном выводе печатаются по вертикали;
  • \gx — вывести в расширенном режиме результаты одной команды.

Буфер запроса​

Последний выполненный запрос сохраняется в специальном буфере psql.

Посмотрим содержимое буфера:

postgres=# \p
SELECT min(g.i), max(g.i), avg(g.i) FROM generate_series(0,10) as g(i)

Выполним запрос из буфера повторно:

postgres=# \g
 min | max | avg
 ----+-----+--------------------
   0 |  10 | 5.0000000000000000
(1 row)

Очистим буфер:

postgres=# \r
Query buffer reset (cleared).

Метакоманда \w <файл> сохраняет содержимое буфера в файл.

Коротко о главном:

  • \p — вывести содержимое буфера;
  • \g — выполнить команду SQL в буфере;
  • \r — стереть содержимое буфера;
  • \w — записать в файл содержимое буфера.

История команд​

Клиент psql сохраняет историю выполненных команд. Эта функциональность реализуется библиотекой readline, включенной во множество других программ, например Bash.

Совершенно аналогично Bash, нажатие на клавиши вверх-вниз позволяет просматривать историю выполненных команд, нажатие Ctrl+R позволяет перейти в режим интерактивного поиска выполненной команды по подстроке.

Метакоманда \s выводит список выполненных ранее команд:

postgres=# \s
\set
\? command
\? options
\? variables

По умолчанию в СУБД Pangolin история команд psql не сохраняется между сеансами по соображениям безопасности. Для запоминания истории необходимо включить специальный параметр psql.save_history.

Проверим значение параметра:

postgres=# \dconfig+ psql.save_history
                List of configuration parameters
     Parameter     |   Value  | Type |   Context  | Access
-------------------+----------+------+------------+---------------
 psql.save_history | off      | bool | postmaster |
(1 row)

Для включения параметра необходимо изменить конфигурацию:

postgres=# ALTER SYSTEM SET psql.save_history TO on;

После изменений требуется перезагрузка сервера.

Другой способ изменить параметр — добавить текстовым редактором строку конфигурации в файл postgresql.conf и перезагрузить сервер:

psql.save_history = 'on'

Подробнее о конфигурации смотрите в «Главе 05. Конфигурация сервера».

Коротко о главном:

  • \s — вывод истории команд, можно записать в файл;
  • Сканирование команд в истории посредством стрелок вверх-вниз;
  • Ctrl+R — поиск последней выполненной команды по подстроке;
  • Включить сохранение истории можно параметром psql.save_history.

Многократное выполнение буфера​

Метакоманда \watch позволяет выполнять запрос из буфера повторно с заданным интервалом:

postgres=# SELECT now();
postgres=# \watch
Mon 16 Mar 2026 01:27:41 PM MSK (every 2s)

              now
-------------------------------
 2026-03-16 13:27:41.549461+03
(1 row)

Mon 16 Mar 2026 01:27:43 PM MSK (every 2s)

              now
-------------------------------
 2026-03-16 13:27:43.549496+03
(1 row)

Mon 16 Mar 2026 01:27:45 PM MSK (every 2s)

              now
-------------------------------
 2026-03-16 13:27:45.549471+03

Запрос будет выполняться каждые 2 секунды до прерывания (Ctrl+C). Можно задавать интервал в секундах \watch i[nterval]=1.

Это полезно для отслеживания хода выполнения сопроводительных операций в представлениях pg_stat_progress_copy, pg_stat_progress_basebackup и других.

Коротко о главном:

  • \watch многократно повторяет команду в буфере до тех пор, пока не будет прервана;
  • Комбинация клавиш Ctrl+C прерывает поток вывода \watch;
  • по умолчанию повтор каждые две секунды.

Вывод в файл или поток​

Результаты запросов можно направлять в файл с помощью команды \o[ut] <файл>:

postgres=# \o time.txt
postgres=# SELECT now();

В psql можно выполнять команды shell метакомандой \!:

postgres=# \! cat time.txt
             now
------------------------------
 2026-03-16 12:25:25.16045+03
(1 row)

Вернуть вывод в консоль позволяет выполнение метакоманды \o без аргумента.

Также можно перенаправить вывод на вход команде shell \o | <команда>:

postgres=# \o | head -5
postgres=# SELECT * FROM generate_series(1, 10);
 generate_series
-----------------
               1
               2
               3
Коротко о главном:

  • \o[ut] <файл> — перенаправляет весь последующий вывод в файл;
  • \o — возвращает вывод на терминал;
  • \o | <команда_ОС> — перенаправляет поток вывода команде ОС.

Генерация скрипта​

Можно формировать SQL-скрипты, перенаправив вывод psql в файл скрипта. Обращение к файлу будет выполняться от имени того пользователя, от которого был запущен psql.

Для начала настроим вывод без выравнивания, без заголовков, с пробелом в качестве разделителя:

postgres=# \a \t \f ' '
Output format is unaligned.
Tuples only is on.
Field separator is " ".

Перенаправим вывод в файл db_sizes.sql:

postgres=# \o db_sizes.sql

Сгенерируем команды для каждой базы данных:

postgres=# SELECT format('SELECT ''%I:'', pg_size_pretty(pg_database_size(''%I''));', datname, datname) FROM pg_database;

Команда SELECT в примере генерирует несколько команд SELECT для получения размеров баз данных.

примечание

Если в форматируемом тексте встречаются апострофы вида «'», их следует экранировать повторным символом.

В результате в файле db_sizes.sql окажется:

SELECT 'postgres:', pg_size_pretty(pg_database_size('postgres'));
SELECT 'student:', pg_size_pretty(pg_database_size('student'));
SELECT 'template1:', pg_size_pretty(pg_database_size('template1'));
SELECT 'template0:', pg_size_pretty(pg_database_size('template0'));

Подготовленный скрипт можно выполнить несколькими способами.

Выполнение скрипта из файла​

Записанные в файл команды можно выполнить из командной строки с помощью psql -f файл или psql < файл:

[postgres@ServerName ~]$ psql -AtF ' ' -f db_sizes.sql
postgres: 9151 kB
student: 9535 kB
template1: 9239 kB
template0: 8945 kB
А -AtF ' ' это что?

Это уже знакомое форматирование:

  • -A – отключить выравнивание (аналог \a);
  • -t– только строки (аналог \t);
  • -F ' ' – установить разделитель полей (аналог \f).

Выполнение скрипта в psql​

В интерактивном режиме команды psql выполнить команды из скритпа SQL позволяет метакоманда \i <файл>.

Для начала изменим формат:

postgres=# \a \t \f ' '
Output format is unaligned.
Tuples only is on.
Field separator is " ".

Выполним записанные в файл команды:

postgres=# \i db_sizes.sql
postgres: 9151 kB
student: 9535 kB
template1: 9239 kB
template0: 8945 kB

Переменные psql​

По аналогии с shell, psql имеет собственные переменные, среди которых есть ряд встроенных (выступающих в качестве параметров psql, определяющих его поведение).

Как и с переменными shell, принято, что системные переменные названы в верхнем регистре (хотя это всего лишь соглашение). Посмотреть список переменных psql можно командой \set без аргументов:

postgres=# \set
AUTOCOMMIT = 'on'
COMP_KEYWORD_CASE = 'preserve-upper'
...

Создать собственную переменную и присвоить ей значение можно с помощью команды \set <переменная> <значение>:

postgres=# \set myVar Привет!
postgres=# \echo :myVar
Привет!
примечание

У переменных psql нет возможности задать тип данных, все значения хранятся как текстовые строки.

Коротко о главном:

  • \set выводит список переменных psql или устанавливает их;
  • некоторые переменные, например AUTOCOMMIT, влияют на поведение самого psql;
  • \echo — вывод на терминал или в поток;
  • для извлечения значения переменной перед именем ставят двоеточие.

Взаимодействие с ОС​

В переменную psql можно записать результат выполнения команды shell, для этого команду shell необходимо написать в открывающих кавычках:

postgres=# \set osDate `date`
postgres=# \echo :osDate
Mon Mar 16 02:43:12 PM MSK 2026

Будет запущена порожденная оболочка (subshell), в которой будет выполнена написанная команда, а результат ее выполнения будет записан в переменную psql.

Если результат shell-команды не требуется сохранять, то можно воспользоваться \! <команда>. При этом результат команды будет отправлен на экран:

postgres=# \! date
Mon Mar 16 02:39:45 PM MSK 2026
Коротко о главном:

  • Команда в открывающих кавычках команда выполняется в ОС, результат возвращается в psql;
  • \! выполняет команду ОС.

Переменные окружения​

Чтобы использовать в сеансе psql значение переменной из ОС, нужно считать его в переменную psql. Для этого применяется метакоманда \getenv <переменная> <переменная окружения>.

Создадим переменную psql osUser со значение переменной окружения USER:

postgres=# \getenv osUser USER

Ранее была создана переменная myVar. Выведем значение обеих переменных:

postgres=# \echo :myVar :osUser
Привет! student

Сбросить переменную можно так:

postgres=# \unset osUser

Назначить значение переменной окружения непосредственно из psql можно метакомандой \setenv. При этом следует понимать, что переменные окружения не являются аналогами глобальных переменных в универсальных языках программирования. Окружение процесса, состоящее в том числе и из переменных, копируется в окружение дочерних процессов и никак иначе.

Поэтому использование \setenv уместно лишь для того, чтобы установить переменную окружения, влияющую на сам процесс psql.

Например, установим программу для постраничного просмотра и ее опции:

postgres=# \setenv PAGER less
postgres=# \setenv LESS -XS

Переменная PAGER указывает, что для постраничного просмотра будет использоваться программа less. Переменная LESS передает less опции -X (не очищать экран при выходе) и -S (не переносить длинные строки).

postgres=# \! echo $PAGER
less
postgres=# \! echo $LESS
-XS

Удалить созданные переменные окружения можно так:

postgres=# \setenv PAGER
postgres=# \setenv LESS
Коротко о главном:

  • команда \getenv считывает в ОС значение переменной окружения и записывает в переменную psql;
  • удалить переменную psql – \unset;
  • команда \setenv устанавливает переменную окружения;
  • удалить переменную окружения – \setenv <переменная_окружения>.

Файл ресурсов .psqlrc​

При запуске psql выполняются два скрипта (при их наличии). Сначала общий системный скрипт psqlrc, затем пользовательский файл .psqlrc. По умолчанию оба файла отсутствуют.

Пользовательский файл должен располагаться в домашнем каталоге пользователя, запустившего psql, а расположение системного скрипта можно узнать при помощи утилиты pg_config:

[postgres@ServerName ~]$ pg_config --sysconfdir
/usr/pangolin-{major.minor}/etc

Обычное применение этих файлов заключается в выполнении SQL-команд, которые автоматически должны срабатывать при входе в сеанс. Также часто настраивают значения переменных psql, например, задавая приглашение командной строки.

Настройка приглашения​

Приглашение командной строки в psql настраивается через три переменные:

  • PROMPT1 — обычное приглашения перед началом ввода команды;
  • PROMPT2 — приглашение при продолжении ввода команды (после Enter без ;);
  • PROMPT3 — приглашение при вводе данных для команды COPY.

Посмотрим на приглашение, которое стоит по умолчанию:

postgres=# \echo :PROMPT1
%/%R%x%#
Разбор спецсимволов:

  • %/ — имя текущей базы данных;

  • %R — текущий режим:

    • = — готовность ввода команды;
    • - — продолжение ввода команды;
    • ' — вводится литерал;

  • %x — статус транзакции;

  • %# — для суперпользователя – #, для остальных – >.

Итоги​

  • Интерактивная оболочка psql предоставляет возможности редактирования и исполнения команд SQL;
  • Клиент psql может гибко настраиваться с помощью собственных переменных и переменных окружения;
  • Можно использовать файл настройки ресурсов.

Самопроверка​

Вопрос 1

Какая метакоманда для psql-команд позволяет выключить расширенный вывод?

Вопрос 2

Каким образом можно несколько раз повторить команду в буфере через заданное количество секунд?

Вопрос 3

Как в psql вывести команды в буфере?