Команды psql для PostgreSQL: шпаргалка с примерами

psql — терминальный клиент PostgreSQL. Через него можно подключиться к базе, выполнять SQL, смотреть таблицы и схемы, запускать SQL-файлы, импортировать CSV и сохранять вывод. Ниже сначала идёт короткая шпаргалка, затем — синтаксис и примеры по каждой задаче

Синтаксис примеров сверен с официальной документацией psql для PostgreSQL 18. Перед применением проверьте свою версию командой psql --version и откройте документацию той же версии, если она отличается

Быстрая шпаргалка: основные команды psql

Запуск psql и подключение к PostgreSQL

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

# База postgres на локальном сервере
psql -U postgres -d postgres

# Конкретный хост, порт, роль и база
psql -h localhost -p 5432 -U myuser -d mydb

# Linux: запуск от системного пользователя postgres
sudo -u postgres psql -d postgres

После входа проверьте фактическое подключение:

\conninfo

Команда покажет базу, роль, хост, порт и параметры SSL, если они используются

-W не передаёт пароль в командной строке, а включает ранний запрос пароля. Для повторяющихся подключений безопаснее настроить пароль PostgreSQL и файл .pgpass, чем вписывать пароль в URI или shell-скрипт

Базы, схемы, таблицы и другие объекты

Метакоманды psql начинаются с обратной косой черты. Им не нужна точка с запятой

\l                 -- базы
\l+                -- базы с дополнительными сведениями
\c mydb            -- переключиться на mydb
\c mydb myuser     -- переключиться и сменить роль
\dn                -- схемы
\dt                -- видимые таблицы
\dt analytics.*    -- таблицы схемы analytics
\dt *.*            -- таблицы всех схем, включая системные
\d users           -- структура users
\d+ users          -- расширенное описание users

\dt users фильтрует список таблиц по шаблону users. Эта команда не показывает колонки таблицы. \d users показывает структуру: колонки, типы, NOT NULL, значения по умолчанию, индексы, ограничения, правила и триггеры

Другие часто нужные списки:

\di    -- индексы
\dv    -- представления
\dm    -- материализованные представления
\df    -- функции
\ds    -- последовательности
\dp    -- права на таблицы, представления и последовательности

<a id=»roles»></a>

Роли, пользователи и пароли

\du             -- роли
\du+            -- роли с комментариями
\du myuser      -- роль myuser
\password       -- изменить пароль текущей роли
\password postgres

\password безопаснее ручного ALTER ROLE ... PASSWORD: новый пароль не попадает в историю команд и серверный журнал. Для SQL-команд CREATE ROLE, GRANT и REVOKE есть отдельная инструкция про пользователей и права в PostgreSQL

<a id=»files»></a>

Выполнение SQL, файлов и обмен CSV

В интерактивной сессии SQL-запрос обычно завершается точкой с запятой:

SELECT id, email, created_at
FROM users
WHERE active = true
ORDER BY created_at DESC
LIMIT 10;

Файл в открытой сессии запускает \i, а из shell — параметр -f:

\i /path/to/script.sql

psql -U postgres -d mydb -f script.sql

Пакетный запуск и коды завершения

Одноразовый запрос можно выполнить без входа в интерактивную сессию:

psql -U postgres -d postgres -Atc "SELECT current_database();"

Если подключение идёт к базе postgres, вывод будет таким:

postgres

Для скрипта, который должен остановиться при первой SQL-ошибке, включите ON_ERROR_STOP:

psql -v ON_ERROR_STOP=1 -U postgres -d mydb -f check.sql
echo $?

Код 0 означает нормальное завершение. Код 1 возвращается при фатальной ошибке самого psql, например если файл не найден. Код 2 означает, что соединение с сервером было потеряно в неинтерактивной сессии. Код 3 возвращается при ошибке в скрипте, если был включён ON_ERROR_STOP

На Windows вместо echo $? используйте echo %ERRORLEVEL% в cmd.exe или $LASTEXITCODE в PowerShell

Импорт и экспорт CSV через psql

Для импорта CSV в таблицу:

\copy users (id, email) FROM '/Users/me/users.csv' WITH (FORMAT csv, HEADER true)

Для экспорта результата запроса:

\copy (SELECT id, email FROM users ORDER BY id) TO '/Users/me/users.csv' WITH (FORMAT csv, HEADER true)

Файл читает или создаёт клиент psql на компьютере, где он запущен. В этом главное отличие \copy от SQL-команды COPY с именем файла: серверный COPY обращается к файловой системе сервера PostgreSQL и требует соответствующих прав. Более подробные сценарии разобраны в материале про импорт и экспорт данных PostgreSQL

<a id=»output»></a>

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

\x                -- переключить вертикальный режим
\x auto           -- включать его для широкого результата
\t                -- скрыть заголовки колонок и счётчик строк
\timing on        -- показывать время выполнения
\pset pager off   -- отключить pager
\pset null 'NULL' -- печатать NULL явно
\pset format csv  -- выводить CSV
\pset format aligned

Команда \o направляет все последующие результаты в файл. Вызов без аргумента возвращает вывод в терминал:

\o output.txt
SELECT id, email FROM users ORDER BY id;
\o

Shell, каналы и переменные psql

Команда \! запускает shell-команду на компьютере с psql. Безопасный пример \! pwd показывает текущий каталог:

\! pwd

Не вставляйте в \! непроверенные строки из базы или ввода пользователя: psql передаёт аргумент shell как команду

Вывод одного запроса можно передать в shell-канал. Для Unix-систем:

SELECT current_database(), current_user
\g | cat

Здесь \g | cat выполняет текущий SQL-буфер и передаёт успешный результат команде cat

\gset сохраняет единственную строку результата в переменные psql. Префикс info_ будет добавлен к именам колонок:

SELECT current_database() AS db, current_user AS usr
\gset info_
\echo :info_db :info_usr

Команда \gset info_ требует, чтобы запрос вернул ровно одну строку. \setenv PAGER less можно использовать для установки переменной окружения в процессе psql

Полезные системные запросы

-- Версия PostgreSQL
SELECT version();
SHOW server_version;

-- Текущая база и роль
SELECT current_database(), current_user;
SHOW port;

-- Размеры баз
SELECT datname,
       pg_size_pretty(pg_database_size(datname)) AS size
FROM pg_database
ORDER BY pg_database_size(datname) DESC;

-- Таблицы схемы public и их общий размер
SELECT tablename,
       pg_size_pretty(pg_total_relation_size(
           format('%I.%I', schemaname, tablename)::regclass
       )) AS size
FROM pg_tables
WHERE schemaname = 'public'
ORDER BY pg_total_relation_size(
    format('%I.%I', schemaname, tablename)::regclass
) DESC;

-- Активные подключения
SELECT pid, usename, datname, state, query
FROM pg_stat_activity
WHERE state <> 'idle';

<a id=»help»></a>

Справка и история

\?              -- справка по метакомандам psql
\h              -- список SQL-команд со справкой
\h ALTER TABLE  -- синтаксис ALTER TABLE
\s              -- история команд
\e              -- открыть редактор для текущего SQL-буфера

Если не помните команду, начните с \?: psql сам покажет список, соответствующий установленной версии клиента

<a id=»faq»></a>

Частые вопросы

Как выйти из psql?

Введите \q и нажмите Enter. В Unix-терминале также работает Ctrl+D. Если psql ждёт завершения многострочного запроса, Ctrl+C отменит текущий ввод и вернёт обычное приглашение

Как посмотреть таблицы через psql?

\dt показывает видимые пользовательские таблицы. Для конкретной схемы используйте \dt analytics.*. Для описания колонок, типов, индексов и ограничений нужна другая команда: \d users

Как подключиться к удалённому PostgreSQL?

Укажите хост, порт, роль и базу:

psql -h 192.168.1.100 -p 5432 -U myuser -d mydb

На сервере PostgreSQL должны быть настроены listen_addresses и pg_hba.conf, а сетевой экран должен пропускать нужный порт. Не открывайте базу для всего интернета и не отключайте TLS только ради того, чтобы убрать ошибку подключения