Открыть страницу поиска
Привет, Я DocuDroid!
Открыть страницу ИИ Помощника
Оценка ИИ поиска
Спасибо за оценку нашего ИИ поиска!
Мы будем признательны, если вы поделитесь своими впечатлениями, чтобы мы могли улучшить наш ИИ поиск для вас и других читателей.
GitHub

psql

Интерактивный терминал Greengage DB.

Синтаксис

psql [<option> ...] [<dbname> [<username>]]

Описание

psql — это терминальный клиент для Greengage DB. Позволяет вводить запросы интерактивно, отправлять их в Greengage DB и просматривать результаты. В качестве альтернативы можно использовать файл в качестве источника ввода. Кроме того, утилита предоставляет ряд метакоманд и функций, подобных командным оболочкам, для упрощения написания скриптов и автоматизации различных задач.

Параметры

-a | --echo-all

Выводит все непустые входные строки в стандартный вывод по мере чтения. Не применяется к строкам в интерактивном режиме. Эквивалентно установке переменной ECHO в значение all.

-A | --no-align

Переключает в режим невыровненного вывода. Режим вывода по умолчанию — выровненный.

-c '<command>' | --command='<command>'

Выполняет указанный SQL-запрос и завершает работу. Полезно для использования в скриптах. command может быть либо полноценным SQL-запросом, который анализируется сервером, либо одной метакомандой psql с обратной косой чертой (\). Таким образом, при использовании этого параметра нельзя смешивать SQL и метакоманды psql. Для этого можно передать строку в psql следующим образом:

$ echo '\x \\ SELECT * FROM gp_segment_configuration;' | psql

Здесь \\ используется как разделитель для метакоманд.

Если command содержит несколько SQL-запросов, они выполняются в одной транзакции, если явно не указаны BEGIN/COMMIT для разделения на несколько транзакций. Это отличается от поведения при передаче той же строки в стандартный ввод psql. Также возвращается результат только последней SQL-команды.

-d <dbname> | --dbname=<dbname>

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

Если этот параметр содержит = или начинается с допустимого URI-префикса (postgresql:// или postgres://), он обрабатывается как строка conninfo. Дополнительную информацию см. в разделе Connection Strings документации PostgreSQL.

-e | --echo-queries

Выводит все SQL-команды, отправляемые на сервер, в стандартный вывод.

-E | --echo-hidden

Отображает фактические запросы, сгенерированные командами \d и другими командами с обратной косой чертой. Полезно для изучения внутренних операций psql. Эквивалентно установке переменной ECHO_HIDDEN в on.

-f <filename> | --file=<filename>

Использует файл filename в качестве источника команд вместо интерактивного ввода. После обработки файла psql завершает работу. По функциональности во многом эквивалентно метакоманде \i.

Если filename — это - (дефис), считывается стандартный ввод до EOF или метакоманды \q. Обратите внимание, что в этом случае не используется Readline (как при указании -n).

Использование этого параметра несколько отличается от psql < <filename>. Оба варианта делают то, что ожидается, но -f предоставляет дополнительные возможности, например, сообщения об ошибках с номерами строк. Также этот параметр может снизить накладные расходы при запуске. С другой стороны, перенаправление ввода из командного интерпретатора (в теории) гарантирует тот же вывод, что и при ручном вводе.

-F <separator> | --field-separator=<separator>

Использует указанный разделитель в качестве разделителя полей для невыровненного вывода.

-H | --html

Включает вывод в формате HTML-таблицы.

-l | --list

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

-L <filename> | --log-file=<filename>

Записывает весь вывод запросов в указанный лог-файл в дополнение к обычному выводу.

-n | --no-readline

Отключает использование Readline для редактирования командной строки и использования истории команд. Может быть полезно для отключения расширенных действий клавиши табуляции при вырезании и вставке.

-o <filename> | --output=<filename>

Записывает вывод результатов всех запросов в указанный файл.

-P <assignment> | --pset=<assignment>

Позволяет указать параметры вывода в стиле \pset в командной строке. Обратите внимание, что нужно разделять имя и значение знаком равенства вместо пробела. Таким образом, чтобы установить формат вывода в LaTeX, можно написать -P format=latex.

-q | --quiet

Запускает psql в тихом режиме. По умолчанию выводятся приветственные сообщения и различная информация. При использовании этого параметра вывод подавляется. Полезно вместе с параметром -c. Эквивалентно установке переменной QUIET в on.

-R <separator> | --record-separator=<separator>

Использует separator в качестве разделителя записей для невыровненного вывода.

-s | --single-step

Запускает psql в пошаговом режиме. Пользователю выводится запрос перед отправкой каждой команды на сервер с возможностью отменить выполнение. Можно использовать для отладки скриптов.

-S | --single-line

Запускает psql в однострочном режиме, где новая строка завершает SQL-команду так же, как точка с запятой.

-t | --tuples-only

Отключает вывод имен столбцов и результирующей строки с количеством полученных записей. Эта команда эквивалентна \pset tuples_only.

-T <table_options> | --table-attr=<table_options>

Позволяет указать параметры, которые должны быть размещены внутри тега HTML-таблицы. Подробности см. в \pset.

-v <assignment> | --set=<assignment> | --variable=<assignment>

Выполняет присваивание переменной аналогично метакоманде \set. Обратите внимание, что в командной строке имя и значение (если оно есть) разделяются знаком равенства. Чтобы сбросить переменную, опустите знак равенства. Чтобы установить переменную с пустым значением, укажите знак равенства без значения. Присваивания выполняются на ранней стадии запуска, поэтому переменные, зарезервированные для внутренних целей, могут быть перезаписаны позже.

-V | --version

Выводит версию psql и завершает работу.

-x | --expanded

Включает режим расширенного форматирования таблиц.

-X | --no-psqlrc

Не читает файл запуска (ни общесистемный файл psqlrc, ни пользовательский файл ~/.psqlrc).

-z | --field-separator-zero

Устанавливает нулевой байт в качестве разделителя полей для невыровненного режима вывода.

-0 | --record-separator-zero

Устанавливает нулевой байт в качестве разделителя записей для невыровненного режима вывода. Полезно при взаимодействии с другими программами, например, с xargs -0.

-1 | --single-transaction

При выполнении скрипта оборачивает его в BEGIN/COMMIT для выполнения как единой транзакции. Гарантирует, что либо все команды завершатся успешно, либо изменения не будут применены.

Если скрипт использует BEGIN, COMMIT или ROLLBACK, этот параметр не даст желаемого эффекта. Также если скрипт содержит команду, которую нельзя выполнить внутри блока транзакции, это приведет к сбою команды (и, следовательно, всей транзакции).

-? | --help

Показывает справку об аргументах командной строки psql и завершает работу.

Параметры подключения

-h <host> | --host=<host>

Имя хоста, на котором запущен мастер Greengage DB. Если параметр не указан, считывается из переменной окружения PGHOST; по умолчанию используется localhost.

При запуске psql на мастер-хосте, если значение host начинается с косой черты, оно используется в качестве каталога для сокета домена Unix.

-p <port> | --port=<port>

TCP-порт, на котором мастер Greengage DB ожидает подключения. Если параметр не указан, считывается из переменной окружения PGPORT; по умолчанию используется порт 5432.

-U <username> | --username=<username>

Имя роли базы данных для подключения. Если параметр не указан, считывается из переменной окружения PGUSER; по умолчанию используется текущее имя системной роли.

-W | --password

Принудительно запрашивает пароль. Обычно psql автоматически запрашивает пароль при необходимости. Автоматическое определение необходимости запроса пароля работает не всегда, поэтому этот параметр принудительно вызывает запрос пароля. Если пароль не будет введен, а сервер требует аутентификацию, подключение завершится неудачей.

-w | --no-password

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

ПРИМЕЧАНИЕ

Этот параметр действует на протяжении всей сессии, поэтому он влияет на использование метакоманды \connect, а также на первоначальную попытку подключения.

Код завершения

psql возвращает:

  • 0 — при нормальном завершении;

  • 1 — если произошла собственная критическая ошибка (нехватка памяти, файл не найден);

  • 2 — если подключение к серверу прервалось и сессия не была интерактивной;

  • 3 — если произошла ошибка в скрипте и была установлена переменная ON_ERROR_STOP.

Использование

Подключение к базе данных

psql — это клиентское приложение для Greengage DB. Для подключения необходимы: имя целевой базы данных, имя хоста и порт мастера Greengage DB, а также имя пользователя. Эти параметры передаются через опции командной строки: -d, -h, -p и -U соответственно. Аргумент, не принадлежащий ни одной опции, интерпретируется как имя базы данных (или имя пользователя, если база данных уже указана). Не все параметры обязательны — для большинства есть значения по умолчанию. Если имя хоста не указано, psql подключится через сокет домена Unix к мастеру на локальном хосте или через TCP/IP к localhost на хостах без сокетов домена Unix. Номер порта по умолчанию — 5432. Если мастер использует другой порт, его необходимо указать. Имя пользователя и имя базы данных по умолчанию совпадают с именем пользователя операционной системы. Учтите, что нельзя просто подключиться к любой базе под любым пользователем. Администратор базы данных должен предоставить вам соответствующие права доступа.

Когда значения по умолчанию не подходят, можно сэкономить время на вводе, установив любую или все переменные окружения PGAPPNAME, PGDATABASE, PGHOST, PGPORT и PGUSER в соответствующие значения.

Также удобно иметь файл ~/.pgpass, чтобы избежать регулярного ввода паролей. Этот файл должен находиться в вашем домашнем каталоге и содержать строки в следующем формате:

<hostname>:<port>:<database>:<username>:<password>

Права доступа к файлу .pgpass должны запрещать любой доступ для группы и других пользователей (например, chmod 0600 ~/.pgpass). Если права доступа менее строгие, файл будет проигнорирован. Однако в настоящее время на клиентах Microsoft Windows права доступа к файлу не проверяются. Дополнительную информацию см. в разделе The Password File документации PostgreSQL.

Альтернативный способ указания параметров подключения — строка conninfo или URI вместо имени базы данных. Этот механизм дает широкие возможности по управлению параметрами подключения. Например:

$ psql "service=myservice sslmode=require"
$ psql postgresql://mdw:5433/mydb?sslmode=require

Таким образом, также можно использовать LDAP для поиска параметров подключения, как описано в разделе LDAP Lookup of Connection Parameters документации PostgreSQL. Дополнительную информацию обо всех доступных параметрах подключения см. в разделе Parameter Keywords.

Если не удалось установить подключение (недостаточно прав, сервер не запущен и т. д.), psql вернет ошибку и завершит работу.

Если стандартный ввод или стандартный вывод являются терминалом, psql устанавливает кодировку клиента в auto, которая определяет подходящую кодировку из настроек локали (переменная окружения LC_CTYPE в Unix-системах). Если это работает не так, как ожидалось, кодировку можно переопределить через переменную окружения PGCLIENTENCODING.

Ввод SQL-команд

При нормальной работе psql выводит приглашение с именем базы данных, к которой в данный момент выполнено подключение; за именем базы данных следует строка => для обычного пользователя или =# для суперпользователя. Например:

testdb=>
testdb=#

В командной строке можно вводить SQL-команды. Обычно входные строки отправляются на сервер при достижении точки с запятой. Конец строки не завершает команду. Это позволяет разбивать команды на несколько строк для удобства. Если команда выполнена без ошибок, результаты отображаются в терминале.

Если недоверенные пользователи имеют доступ к базе данных без безопасного шаблона использования схемы, начните сессию с удаления общедоступных для записи схем из search_path. Добавьте options=-csearch_path= к строке подключения или выполните SELECT pg_catalog.set_config('search_path', '', false) перед другими SQL-командами. Это относится не только к psql, но и к любому интерфейсу для выполнения произвольных SQL-команд.

Метакоманды

Все, что вводится в psql и начинается с обратной косой черты без кавычек, является метакомандой psql. Эти команды делают утилиту psql более полезной для администрирования и написания скриптов.

Формат метакоманды psql: обратная косая черта, сразу за ней команда, затем аргументы. Аргументы отделяются от команды и друг от друга любым количеством пробелов.

Чтобы включить пробелы в аргумент, заключите его в одинарные кавычки. Чтобы включить одинарную кавычку в такой аргумент, нужно написать две одинарные кавычки внутри текста в одинарных кавычках. Все, что содержится в одинарных кавычках, подлежит заменам, принятым в языке C: \n (новая строка), \t (табуляция), \b (возврат на символ), \r (возврат каретки), \f (перевод страницы), \digits (восьмеричное число) и \xdigits (шестнадцатеричное число). Обратная косая черта перед любым другим символом внутри одинарных кавычек экранирует этот символ.

Внутри аргумента текст, заключенный в обратные кавычки (`), воспринимается как командная строка, которая передается в командную оболочку. Вывод команды (с удаленными в конце символами новой строки) заменяет текст в обратных кавычках.

Если внутри аргумента появляется двоеточие (:) без кавычек, за которым следует имя переменной psql, оно заменяется значением переменной, как описано в разделе SQL-интерполяция.

Некоторые команды принимают SQL-идентификатор (например, имя таблицы) в качестве аргумента. Эти аргументы следуют синтаксическим правилам SQL: буквы без кавычек приводятся к нижнему регистру, а двойные кавычки (") защищают буквы от преобразования регистра и позволяют включать пробелы. Внутри двойных кавычек парные двойные кавычки сводятся к одной в результирующем имени. Например, FOO"BAR"BAZ интерпретируется как fooBARbaz, а "A weird"" name" как A weird" name.

Разбор аргументов прекращается, когда встречается другая обратная косая черта без кавычек. Это воспринимается как начало новой метакоманды. Специальная последовательность \\ (две обратные косые черты) отмечает конец аргументов и продолжает разбор SQL-команд, если таковые имеются. Таким образом, SQL и команды psql могут свободно смешиваться в одной строке. Но в любом случае аргументы метакоманды не могут продолжаться за пределами конца строки.

Определены следующие метакоманды:

\a

Если текущий формат вывода таблицы невыровненный, он переключается на выровненный. Если текущий режим выровненный, то устанавливается невыровненный. Эта команда сохранена для обратной совместимости. См. \pset для более общего решения.

\c | \connect [<dbname> [<username>] [<host>] [<port>]] | <conninfo>

Устанавливает новое подключение к Greengage DB. Параметры подключения можно указать, используя позиционный синтаксис или строки подключения conninfo, которые подробно описаны в разделе libpq Connection Strings.

Если команда не содержит имя базы данных, имя пользователя, хост или порт, новое подключение может повторно использовать значения из предыдущего подключения. По умолчанию значения из предыдущего подключения повторно используются, за исключением случаев обработки строки conninfo. Передача первого аргумента -reuse-previous=on или -reuse-previous=off переопределяет это значение по умолчанию. Когда команда не указывает и не использует повторно конкретный параметр, используется значение libpq по умолчанию. Указание любого из параметров dbname, username, host или port как - эквивалентно пропуску этого параметра.

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

\c mydb myuser host.dom 6432
\c service=foo
\c "host=localhost port=5432 dbname=mydb connect_timeout=10 sslmode=disable"
\c postgresql://tom@localhost/mydb?application_name=myapp
\C [<title>]

Устанавливает заголовок любых таблиц, печатаемых в результате запроса, или сбрасывает такой заголовок. Эта команда эквивалентна \pset title.

\cd [<directory>]

Изменяет текущий рабочий каталог. Без аргумента переходит в домашний каталог текущего пользователя. Чтобы вывести текущий рабочий каталог, используйте \!pwd.

\conninfo

Отображает информацию о текущем подключении, включая имя базы данных, имя пользователя, тип подключения (сокет домена Unix, TCP/IP и т. д.), хост и порт.

\copy {<table> [(<column_list>)] | (<query>)} {from | to} {'<filename>' | program '<command>' | stdin | stdout | pstdin | pstdout} [with] (<option> [, …​])

Выполняет копирование на клиенте. Это операция, которая выполняет SQL-команду COPY, но вместо работы с файлами на сервере psql читает или записывает файлы в локальной файловой системе и пересылает данные между сервером и локальной системой. Это означает, что доступ к файлам осуществляется с привилегиями локального пользователя, а не сервера, и не требуются права суперпользователя.

Когда указан параметр program, команда выполняется клиентом psql, а данные передаются между сервером и этой программой. Это означает, что права доступа соответствуют локальному пользователю, а не серверу, и не требуются привилегии суперпользователя SQL.

Команда \copy …​ from stdin | to stdout читает или записывает данные через стандартный ввод или вывод команды соответственно. Все строки обрабатываются из того же источника ввода, что использует команда, и продолжают поступать до тех пор, пока не встретится \. или поток не достигнет EOF. Вывод направляется в то же место, что и стандартный вывод команды. Для работы со стандартным вводом или выводом в psql можно использовать pstdin или pstdout. Этот параметр особенно полезен для заполнения таблиц данными, встроенными в SQL-скрипт.

Синтаксис команды аналогичен синтаксису SQL-команды COPY, а параметр option должен соответствовать одному из параметров SQL-команды COPY. Обратите внимание, что из-за этого к команде \copy применяются специальные правила разбора. В частности, здесь не работают подстановка переменных и escape-последовательности с обратной косой чертой.

Эта операция менее эффективна, чем SQL-команда COPY, так как все данные проходят через клиент-серверное соединение.

\copyright

Отображает информацию об авторских правах и условиях распространения PostgreSQL, на котором основан Greengage DB.

\d [<relation_pattern>] | \d+ [<relation_pattern>] | \dS [<relation_pattern>]

Для каждого отношения (таблицы, внешней таблицы, представления, материализованного представления, индекса, последовательности или сторонней таблицы), соответствующего указанному шаблону, отображаются все столбцы, их типы, табличное пространство (если оно отличается от значения по умолчанию) и любые специальные атрибуты, такие как NOT NULL или значения по умолчанию. Также выводятся связанные индексы, ограничения, правила и триггеры. Для сторонних таблиц дополнительно отображается связанный сторонний сервер.

  • Для некоторых типов отношений команда \d отображает дополнительную информацию по каждому столбцу: значения последовательностей, индексированные выражения для индексов и параметры обертки сторонних данных для сторонних таблиц.

  • Команда \d+ работает аналогично, за исключением того, что выводится более подробная информация: любые комментарии, связанные со столбцами, наличие OID в таблице, а также определение представления, если отношение является представлением.

    Для партиционированных таблиц команды \d и \d+, примененные к родительской партиционированной таблице или ее дочерней партиции, отображают информацию о таблице, включая ключи партиционирования на текущем уровне. Команда \d+ дополнительно показывает непосредственные дочерние партиции и указывает, является ли каждая из них внешней или обычной таблицей.

    Для оптимизированных для добавления (Append-Optimized, AO) и колоночных таблиц \d+ отображает параметры хранения таблицы. Для оптимизированных для добавления таблиц параметры отображаются для таблицы. Для колоночных таблиц параметры хранения отображаются для каждого столбца.

  • По умолчанию показываются только созданные пользователем объекты; укажите шаблон или модификатор S для включения системных объектов.

    ПРИМЕЧАНИЕ

    Если команда \d вызывается без указания шаблона, это эквивалентно \dtvmsE и отображает список всех видимых таблиц, представлений, материализованных представлений, последовательностей и сторонних таблиц.

\da[S] [<aggregate_pattern>]

Выводит список агрегатных функций вместе с типами данных, которыми они оперируют. Если указан шаблон, отображаются только агрегатные функции, имена которых соответствуют шаблону. По умолчанию отображаются только объекты, созданные пользователем; укажите шаблон или модификатор S, чтобы включить системные объекты.

\db[+] [<tablespace_pattern>]

Отображает список всех доступных табличных пространств вместе с соответствующими путями. Если указан шаблон, выводятся только табличные пространства, имена которых соответствуют шаблону. Если к имени команды добавлен +, для каждого объекта также показываются соответствующие привилегии.

\dc[S+] [<conversion_pattern>]

Отображает список преобразований между кодировками наборов символов. Если указан шаблон, выводятся только преобразования, имена которых соответствуют шаблону. По умолчанию отображаются только объекты, созданные пользователем; чтобы включить системные объекты, укажите шаблон или модификатор S. Если к имени команды добавлен +, каждый объект выводится вместе с соответствующим описанием.

\dC[+] [<pattern>]

Отображает список приведений типов. Если указан шаблон, выводятся только приведения, исходный или целевой тип которых соответствует шаблону. Если к имени команды добавлен +, для каждого объекта также выводится соответствующее описание.

\dd[S] [<pattern>]

Отображает описания объектов типов constraint, operator class, operator family, rule и trigger. Все остальные комментарии можно просмотреть с помощью соответствующих команд с обратной косой чертой для этих типов объектов.

Команда \dd отображает описания объектов, соответствующих указанному шаблону, или всех видимых объектов соответствующего типа, если аргумент не указан. При этом выводятся только объекты, для которых существует описание. По умолчанию отображаются только объекты, созданные пользователем; чтобы включить системные объекты, укажите шаблон или модификатор S.

Описания объектов можно создавать с помощью SQL-команды COMMENT.

\ddp [<pattern>]

Отображает список настроек привилегий доступа по умолчанию. Запись выводится для каждой роли (и схемы, если применимо), для которой настройки привилегий по умолчанию отличаются от встроенных значений. Если указан шаблон, отображаются только записи, имя роли или схемы которых соответствует шаблону.

Команда ALTER DEFAULT PRIVILEGES используется для задания привилегий доступа по умолчанию. Формат отображения привилегий описан в разделе GRANT.

\dD[S+] [<domain_pattern>]

Отображает список доменов. Если указан шаблон, выводятся только домены, имена которых соответствуют шаблону. По умолчанию отображаются только объекты, созданные пользователем; чтобы включить системные объекты, укажите шаблон или модификатор S. Если к имени команды добавлен +, для каждого объекта также отображаются соответствующие привилегии и описание.

\dEimstPv[S+] [<external_table> | <index> | <materialized_view> | <sequence> | <table> | <parent_table> | <view>]

Это не фактическое имя команды: буквы E, i, m, s, t, P и v обозначают соответственно внешнюю таблицу, индекс, материализованное представление, последовательность, таблицу, родительскую таблицу и представление. Можно указать любые или все эти буквы в любом порядке, чтобы получить список объектов соответствующих типов. Например, \dit выводит список индексов и таблиц. Если к имени команды добавлен +, для каждого объекта также отображаются физический размер на диске и соответствующее описание, если оно есть. Если указан шаблон, выводятся только объекты, имена которых соответствуют шаблону. По умолчанию отображаются только объекты, созданные пользователем; чтобы включить системные объекты, укажите шаблон или модификатор S.

\des[+] [<foreign_server_pattern>]

Выводит список сторонних серверов. Если указан шаблон, выводятся только те серверы, имена которых соответствуют шаблону. Если используется форма \des+, отображается полное описание каждого сервера, включая права доступа, тип, версию, параметры и описание.

\det[+] [<foreign_table_pattern>]

Выводит список всех сторонних таблиц. Если указан шаблон, выводятся только записи, имя таблицы или схемы которых соответствует шаблону. Если используется форма \det+, также отображаются общие параметры и описание сторонней таблицы.

\deu[+] [<user_mapping_pattern>]

Выводит список сопоставлений пользователей. Если указан шаблон, выводятся только те сопоставления, имена пользователей которых соответствуют шаблону. Если используется форма \deu+, отображается дополнительная информация о каждом сопоставлении.

ВНИМАНИЕ

\deu+ также может отображать имя и пароль удаленного пользователя, поэтому следует соблюдать осторожность, чтобы не раскрыть их.

\dew[+] [<foreign_data_wrapper_pattern>]

Выводит список оберток сторонних данных. Если указан шаблон, выводятся только те обертки сторонних данных, имена которых соответствуют шаблону. Если используется форма \dew+, то дополнительно выводятся права доступа, параметры и описание обработчика.

\df[antwS+] [<function_pattern>]

Выводит список функций вместе с их аргументами, типами возвращаемых значений и типами функций, которые классифицируются как "agg" (агрегатная), "normal" (обычная), "trigger" (триггер) или "window" (оконная). Чтобы отобразить только функции определенного типа (типов), добавьте соответствующие буквы a, n, t или w к команде. Если указан шаблон, отображаются только функции, имена которых соответствуют шаблону. Если используется форма \df+, отображается дополнительная информация о каждой функции: контекст безопасности, изменчивость, язык, исходный код и описание. По умолчанию отображаются только объекты, созданные пользователем; укажите шаблон или модификатор S, чтобы включить системные объекты.

\dF[+] [<pattern>]

Выводит список конфигураций текстового поиска. Если указан шаблон, отображаются только конфигурации, имена которых соответствуют шаблону. Если используется форма \dF+, отображается полное описание каждой конфигурации, включая базовый парсер текстового поиска и список словарей для каждого типа токена парсера.

\dFd[+] [<pattern>]

Выводит список словарей текстового поиска. Если указан шаблон, отображаются только словари, имена которых соответствуют шаблону. Если используется форма \dFd+, отображается дополнительная информация о каждом выбранном словаре, включая базовый шаблон текстового поиска и значения параметров.

\dFp[+] [<pattern>]

Выводит список парсеров текстового поиска. Если указан шаблон, отображаются только парсеры, имена которых соответствуют шаблону. Если используется форма \dFp+, отображается полное описание каждого парсера, включая базовые функции и список распознаваемых типов токенов.

\dFt[+] [<pattern>]

Выводит список шаблонов текстового поиска. Если указан pattern, отображаются только шаблоны, имена которых соответствуют ему. Если используется форма \dFt+, отображается дополнительная информация о каждом шаблоне, включая имена базовых функций.

\dg[+] [<role_pattern>]

Выводит список ролей базы данных. Поскольку концепции "пользователей" и "групп" объединены в "роли", эта команда эквивалентна \du. Если указан шаблон, выводятся только те роли, имена которых соответствуют шаблону. Если используется форма \dg+, отображается дополнительная информация о каждой роли.

\dl

Псевдоним для \lo_list, который отображает список больших объектов (large object).

ПРИМЕЧАНИЕ

Greengage DB не поддерживает средства работы с большими объектами PostgreSQL для потоковой передачи пользовательских данных, хранящихся в структурах больших объектов.

\dL[S+] [<pattern>]

Отображает список процедурных языков. Если указан шаблон, выводятся только языки, имена которых соответствуют шаблону. По умолчанию отображаются только языки, созданные пользователем; чтобы включить системные объекты, укажите модификатор S. Если к имени команды добавлен +, для каждого языка также отображаются обработчик вызовов, функция проверки, привилегии доступа и информация о том, является ли язык системным объектом.

\dn[S+] [<schema_pattern>]

Отображает список всех доступных схем (пространств имен). Если указан шаблон, выводятся только схемы, имена которых соответствуют шаблону. По умолчанию отображаются только объекты, созданные пользователем; чтобы включить системные объекты, укажите шаблон или модификатор S. Если к имени команды добавлен +, для каждого объекта также отображаются соответствующие привилегии и описание, если оно есть.

\do[S] [<operator_pattern>]

Отображает список доступных операторов с указанием типов их операндов и возвращаемых типов. Если указан шаблон, выводятся только операторы, имена которых соответствуют шаблону. По умолчанию отображаются только объекты, созданные пользователем; чтобы включить системные объекты, укажите шаблон или модификатор S.

\dO[S+] [<pattern>]

Отображает список сортировок (collation). Если указан шаблон, выводятся только сортировки, имена которых соответствуют шаблону. По умолчанию отображаются только объекты, созданные пользователем; чтобы включить системные объекты, укажите шаблон или модификатор S. Если к имени команды добавлен +, для каждой сортировки также отображается соответствующее описание, если оно есть. Обратите внимание, что отображаются только сортировки, применимые к кодировке текущей базы данных; поэтому результаты могут различаться в разных базах данных одной установки.

\dp [<relation_pattern_to_show_privileges>]

Отображает список таблиц, представлений и последовательностей вместе с соответствующими привилегиями доступа. Если указан шаблон, выводятся только объекты, имена которых соответствуют шаблону. Команды GRANT и REVOKE используются для задания привилегий доступа. Формат отображения привилегий описан в разделе GRANT.

\drds [<role-pattern> [<database-pattern>]]

Отображает список определенных настроек конфигурации. Эти настройки могут быть специфичными для роли, для базы данных или их комбинации. Параметры role-pattern и database-pattern используются для выбора конкретных ролей и баз данных для вывода соответственно. Если параметр не указан или задан как *, отображаются все настройки, включая те, которые не являются специфичными для роли или базы данных.

Команды ALTER ROLE и ALTER DATABASE используются для задания настроек конфигурации для отдельных ролей и баз данных.

\dT[S+] [<datatype_pattern>]

Выводит список типов данных. Если указан шаблон, выводятся только типы, имена которых соответствуют шаблону. Если к имени команды добавлен +, каждый тип выводится с внутренним именем и размером, допустимыми значениями, если это тип enum, и соответствующими привилегиями. По умолчанию отображаются только объекты, созданные пользователем; укажите шаблон или модификатор S, чтобы включить системные объекты.

\du[+] [<role_pattern>]

Выводит список ролей базы данных. Поскольку концепции "пользователей" и "групп" объединены в "роли", эта команда эквивалентна \dg. Если указан шаблон, выводятся только роли, имена которых соответствуют шаблону. Если используется форма \du+, для каждой роли отображается дополнительная информация; в настоящее время это включает комментарий для роли.

\dx[+] [<extension_pattern>]

Выводит список установленных расширений. Если указан шаблон, выводятся только те расширения, имена которых соответствуют шаблону. Если используется форма \dx+, выводятся все объекты, принадлежащие соответствующему расширению.

\dy[+] [<pattern>]

Выводит список событийных триггеров. Если указан шаблон, выводятся только те триггеры, имена которых соответствуют шаблону. Если к имени команды добавлен +, каждый объект выводится с соответствующим описанием.

ПРИМЕЧАНИЕ

Greengage DB не поддерживает пользовательские триггеры.

\e | \edit [<filename>] [<line_number>]

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

Новый буфер запросов затем повторно анализируется в соответствии с обычными правилами psql, где весь буфер рассматривается как одна строка. Таким образом, вы не можете создавать скрипты таким способом. Используйте для этого \i.

Если запрос заканчивается (или содержит) точкой с запятой, он немедленно выполняется. В противном случае он будет ожидать в буфере запросов; введите точку с запятой или \g, чтобы отправить его, или \r, чтобы отменить.

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

См. раздел Переменные окружения для получения информации о настройке и персонализации редактора.

\echo <text> [ …​ ]

Выводит аргументы в стандартный вывод, разделенные одним пробелом и за которыми следует символ новой строки. Это может быть полезно для добавления информации в вывод скриптов. Если первый аргумент — это -n без кавычек, завершающий символ новой строки не выводится.

ПРИМЕЧАНИЕ

Если вы используете команду \o для перенаправления вывода запросов, возможно, вам стоит воспользоваться командой \qecho вместо нее.

\ef [<function_description> [<line_number>]]

Извлекает и редактирует определение указанной функции в форме команды CREATE OR REPLACE FUNCTION. Редактирование выполняется так же, как для \edit. После выхода из редактора обновленная команда ожидает в буфере запросов; введите точку с запятой или \g, чтобы отправить ее, или \r, чтобы отменить.

Целевую функцию можно указать только по имени или по имени и аргументам, например, foo(integer, text). Типы аргументов должны быть указаны, если существует более одной функции с таким же именем.

Если функция не указана, для редактирования предоставляется пустой шаблон CREATE FUNCTION.

Если указан номер строки, psql позиционирует курсор на указанной строке тела функции. Обратите внимание, что тело функции обычно не начинается с первой строки файла.

См. раздел Переменные окружения для получения информации о настройке и персонализации редактора.

\encoding [<encoding>]

Устанавливает кодировку набора символов клиента. Без аргумента эта команда отображает текущую кодировку.

\f [<field_separator_string>]

Устанавливает разделитель полей для невыровненного режима вывода запросов. По умолчанию это вертикальная черта (|). См. также \pset для универсального способа установки параметров вывода.

\g [<filename>]
\g [ | <command> ]

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

\g без аргументов, по сути, эквивалентен точке с запятой. \g с аргументом — разовая альтернатива команде \o.

\gset [<prefix>]

Отправляет текущий буфер запросов на сервер и сохраняет результат запроса в переменные psql. Выполняемый запрос должен возвращать ровно одну строку. Каждый столбец этой строки сохраняется в отдельную переменную с именем, соответствующим имени столбца. Например:

=> SELECT 'hello' AS var1, 10 AS var2;
-> \gset
=> \echo :var1 :var2
hello 10

Если вы указываете префикс, эта строка добавляется в начало имен столбцов запроса для создания имен переменных:

=> SELECT 'hello' AS var1, 10 AS var2;
-> \gset result_
=> \echo :result_var1 :result_var2
hello 10

Если результат столбца равен NULL, соответствующая переменная удаляется, а не устанавливается.

Если запрос завершается с ошибкой или не возвращает одну строку, переменные не изменяются.

\h | \help [<sql_command>]

Выводит справку по синтаксису указанной SQL-команды. Если команда не указана, psql выводит список всех команд, для которых доступна справка по синтаксису. Если указана звездочка (*), отображается справка по синтаксису всех SQL-команд. Для удобства ввода многословных команд кавычки не требуются.

\H | \html

Включает HTML-формат вывода запросов. Если формат HTML уже включен, команда переключает вывод обратно на стандартный выровненный текстовый формат. Эта команда предназначена для совместимости и удобства, однако для настройки других параметров вывода используйте \pset.

\i | \include <filename>

Читает ввод из файла filename и выполняет его так, как если бы он был набран с клавиатуры.

Если filename — это - (дефис), то стандартный ввод читается до EOF или метакоманды \q. Можно использовать для чередования интерактивного ввода с вводом из файлов. Обратите внимание, что поведение Readline будет использоваться только в том случае, если оно активно на самом внешнем уровне.

Если вы хотите видеть строки в терминале по мере их чтения, установите переменную ECHO в all.

\ir | \include_relative <filename>

Команда \ir аналогична \i, но интерпретирует относительные имена файлов по-другому. При работе в интерактивном режиме обе команды ведут себя одинаково. Однако при вызове из скрипта \ir интерпретирует имена файлов относительно каталога, в котором расположен скрипт, а не относительно текущего рабочего каталога.

\l[+] | \list[+] [<pattern>]

Отображает список баз данных на сервере, включая их имена, владельцев, кодировки наборов символов и привилегии доступа. Если указан шаблон, выводятся только базы данных, имена которых соответствуют шаблону. Если к имени команды добавлен +, также отображаются размеры баз данных, табличные пространства по умолчанию и описания. Информация о размере доступна только для баз данных, к которым может подключиться текущий пользователь.

\lo_export <loid> <filename>

Считывает большой объект с OID loid из базы данных и сохраняет его в файл filename. Обратите внимание, что это отличается от серверной функции lo_export, которая выполняется с привилегиями пользователя, от имени которого работает сервер, и выполняется в файловой системе сервера. Используйте \lo_list, чтобы узнать OID большого объекта.

ПРИМЕЧАНИЕ

Большие объекты не поддерживаются в Greengage DB.

\lo_import <large_object_filename> [<comment>]

Сохраняет файл в большой объект. Опционально связывает указанный комментарий с объектом.

Пример:

mydb=> \lo_import '/home/gpadmin/pictures/photo.xcf' 'a picture of me'
lo_import 152801

Команда возвращает идентификатор большого объекта, например 152801, который следует запомнить для повторного доступа к объекту. Для удобства чтения рекомендуется всегда связывать объекты с понятными комментариями. Комментарии можно просмотреть с помощью команды \lo_list. Обратите внимание, что эта команда отличается от серверной функции lo_import: она выполняется с привилегиями локального пользователя в локальной файловой системе, а не с привилегиями пользователя и в файловой системе сервера.

ПРИМЕЧАНИЕ

Большие объекты не поддерживаются в Greengage DB.

\lo_list

Показывает список всех больших объектов, хранящихся в базе данных, вместе с предоставленными комментариями.

ПРИМЕЧАНИЕ

Большие объекты не поддерживаются в Greengage DB.

\lo_unlink <largeobject_oid>

Удаляет большой объект с указанным OID из базы данных. Используйте \lo_list, чтобы узнать OID большого объекта.

ПРИМЕЧАНИЕ

Большие объекты не поддерживаются в Greengage DB.

\o | \out [ <filename> ]
\o | \out [ | <command> ]

Сохраняет будущие результаты запросов в файл filename или передает их в команду оболочки command. Если аргумент не указан, вывод запросов возвращается в стандартный вывод. Результаты включают все таблицы, ответы команд и уведомления, полученные от сервера базы данных, а также вывод различных команд с обратной косой чертой, запрашивающих информацию о базе данных (например, \d), но не сообщения об ошибках. Чтобы вставлять текст между результатами запросов, используйте команду \qecho.

\p

Выводит текущий буфер запросов в стандартный вывод.

\password [<username>]

Изменяет пароль указанного пользователя (по умолчанию — текущего пользователя). Эта команда запрашивает новый пароль, шифрует его и отправляет на сервер в виде команды ALTER ROLE. Это гарантирует, что новый пароль не появится в открытом виде в истории команд, лог-файле сервера или где-либо еще.

\prompt [<text>] <name>

Запрашивает у пользователя текст и присваивает его переменной name. Можно указать необязательную строку приглашения text. Для многословных приглашений заключайте текст в одинарные кавычки.

По умолчанию \prompt использует терминал для ввода и вывода. Если же был указан параметр -f, \prompt использует стандартный ввод и стандартный вывод.

\pset [<print_option> [<value>]]

Задает параметры, влияющие на вывод таблиц результатов запроса. Параметр print_option определяет, какой именно параметр устанавливается. Семантика value зависит от выбранного параметра. Для некоторых параметров пропуск value приводит к переключению или сбросу параметра, как указано в описании конкретного параметра. Если такое поведение не указано, пропуск value просто отображает текущую настройку.

Команда \pset без аргументов отображает текущее состояние всех параметров печати.

Настраиваемые параметры печати:

  • border — принимает числовое значение. В общем случае, чем больше число, тем больше границ и линий будет в таблицах, но это зависит от конкретного формата. В формате HTML это значение транслируется непосредственно в атрибут border=…​; в других форматах имеют смысл только значения 0 (без границы), 1 (внутренние разделительные линии) и 2 (рамка таблицы). Форматы latex и latex-longtable также поддерживают значение border равное 3, которое добавляет разделительную линию между каждой строкой.

  • columns — задает целевую ширину для формата wrapped, а также лимит ширины для определения, требуется ли пейджер или переключение на вертикальное отображение в расширенном автоматическом режиме. По умолчанию используется значение 0. Оно означает, что целевая ширина определяется переменной окружения COLUMNS или шириной экрана, если переменная COLUMNS не установлена. Кроме того, при значении 0 формат wrapped влияет только на вывод на экран. Если columns не равен 0, это также влияет на вывод в файл или в другую команду через канал.

    После установки целевой ширины используйте команду \pset format wrapped, чтобы включить формат переноса.

  • expanded | x — если указано значение, оно должно быть on, off или auto. Если значение не указано, команда переключает режим между on и off. Когда включен расширенный режим, результаты запроса отображаются в двух столбцах: имя столбца слева и данные справа. Этот режим удобен, если данные не помещаются на экране в обычном горизонтальном режиме. В режиме auto расширенный режим используется только тогда, когда вывод запроса шире экрана; в противном случае применяется обычный режим. Режим auto действует только для форматов aligned и wrapped. В остальных форматах расширенный режим всегда считается отключенным (off).

  • fieldsep — задает разделитель полей для использования в невыровненном режиме вывода. С его помощью можно, например, формировать вывод, разделенный табуляцией или запятыми, что удобно для обработки другими программами. Чтобы установить табуляцию в качестве разделителя, используйте данную команду: \pset fieldsep '\t'. По умолчанию разделителем полей является символ '|' (вертикальная черта).

  • fieldsep_zero — устанавливает разделитель полей для невыровненного формата вывода в нулевой байт.

  • footer — принимает значения on или off, включающие или отключающие отображение результирующей строки таблицы с количеством строк (n rows). Если значение не указано, команда переключает состояние отображения результирующей строки.

  • format — устанавливает формат вывода в один из: unaligned, aligned, html, latex (использует tabular), latex-longtable, troff-ms или wrapped. Допускаются уникальные сокращения.

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

    Формат aligned — это стандартный, удобочитаемый, хорошо отформатированный текстовый вывод; используется по умолчанию.

    Форматы html, latex, latex-longtable и troff-ms создают таблицы, предназначенные для включения в документы с использованием соответствующего языка разметки. Они не являются полными документами. Для HTML это может быть не так критично, но в LaTeX необходима полная обертка документа. Формат latex-longtable также требует пакеты LaTeX longtable и booktabs.

    Формат wrapped похож на aligned, но переносит длинные значения данных на новые строки, чтобы вывод соответствовал целевой ширине. Целевая ширина определяется параметром columns. Обратите внимание, что psql не переносит заголовки столбцов; если общая ширина заголовков превышает целевую, формат wrapped ведет себя как aligned.

  • linestyle [unicode | ascii | old-ascii] — устанавливает стиль отрисовки линий границы в один из: unicode, ascii или old-ascii. Для всех стилей допускаются уникальные сокращения, включая одну букву. Значение по умолчанию — ascii. Этот параметр влияет только на форматы вывода aligned и wrapped.

    Стиль ascii использует стандартные ASCII-символы. Символ перевода строки в данных отображается как + в правом поле. Когда формат wrapped переносит данные с одной строки на другую без фактического символа перевода строки, точка (.) отображается в правом поле первой строки и в левом поле следующей строки.

    Стиль old-ascii использует стандартные ASCII-символы и применяет форматирование, использовавшееся в PostgreSQL 8.4 и ранее. Символ перевода строки в данных отображается как : вместо разделителя левого столбца. Когда данные переносятся с одной строки на другую без фактического символа перевода строки, для разделителя левого столбца используется символ ;.

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

    Когда значение параметра border больше нуля, этот параметр также определяет символы, используемые для отрисовки границ. Обычные ASCII-символы работают везде, тогда как символы Unicode выглядят лучше на терминалах, которые их поддерживают.

  • null 'string' — второй аргумент задает строку, которая будет выводиться для значений NULL в столбцах. По умолчанию ничего не выводится, что легко принять за пустую строку. Например, может быть удобно использовать \pset null '(null)'.

  • numericlocale — если указано значение, оно должно быть on или off, что активирует или деактивирует отображение специфичного для локали символа для разделения групп цифр слева от десятичного разделителя. Если значение не указано, команда переключается между обычным и специфичным для локали числовым выводом.

  • pager — управляет использованием пейджера для вывода запросов и справки psql. Если установлена переменная окружения PAGER, вывод передается в указанную программу. В противном случае используется значение по умолчанию, зависящее от платформы (например, more). При значении off пейджер не используется. При значении on пейджер применяется только когда это уместно: если вывод идет в терминал и не помещается на экране. Значение always принудительно включает использование пейджера для всего терминального вывода вне зависимости от его объема. Команда \pset pager без аргумента переключает состояние использования пейджера.

  • recordsep — задает разделитель записей (строк) для невыровненного формата вывода. По умолчанию используется символ перевода строки.

  • recordsep_zero — устанавливает разделитель записей для невыровненного формата вывода как нулевой байт.

  • tableattr | T [text] — в формате HTML задает атрибуты, которые будут добавлены в тег <table>. Примеры таких атрибутов: cellpadding или bgcolor. Обратите внимание, что указывать border обычно не требуется, так как параметр \pset border управляет этим значением. Если значение не указано, атрибуты таблицы сбрасываются.

    В формате latex-longtable управляет пропорциональной шириной каждого столбца, содержащего тип данных с выравниванием по левому краю. Указывается как разделенный пробелами список значений, например '0.2 0.2 0.6'. Для неуказанных выходных столбцов используется последнее указанное значение.

  • title [text] — устанавливает заголовок таблицы для всех последующих печатаемых таблиц. Это можно использовать для добавления описательных тегов к выводу. Если значение не указано, заголовок сбрасывается.

  • tuples_only | t [ novalue | on | off ] — если указано значение, оно должно быть on или off, что включает или отключает режим "только кортежи". Если значение не указано, команда переключает режим между обычным выводом и выводом только кортежей. В обычном режиме вывод содержит дополнительную информацию: заголовки столбцов, заголовки таблицы и результирующие строки. В режиме "только кортежи" отображаются лишь фактические данные таблицы. Команда \t эквивалентна \pset tuples_only.

РЕКОМЕНДАЦИЯ

Существуют различные команды-сокращения для \pset. См. \a, \C, \f, \H, \t, \T и \x.

\q | \quit

Завершает работу psql. При использовании в скрипте прекращает выполнение только этого скрипта.

\qecho <text> [ …​ ]

Эта команда идентична \echo, за исключением того, что вывод записывается в канал вывода запросов, заданный командой \o.

\r | \reset

Сбрасывает (очищает) буфер запросов.

\s [<filename>]

Выводит историю командной строки psql в файл filename. Если filename не указан, история записывается в стандартный вывод (с использованием пейджера, если это уместно). Эта команда недоступна, если утилита psql была собрана без поддержки readline.

\set [<name> [<value> [ …​ ]]]

Устанавливает переменную psql name в значение value или, если указано несколько значений, в их конкатенацию. Если указан только один аргумент (имя переменной), она устанавливается в пустое значение. Чтобы удалить переменную, используйте команду \unset.

\set без аргументов отображает имена и значения всех установленных в данный момент переменных psql.

Допустимые имена переменных могут содержать буквы, цифры и символы подчеркивания. См. раздел Переменные. Имена переменных чувствительны к регистру.

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

Эта команда не имеет отношения к SQL-команде SET.

\setenv <name> [<value>]

Устанавливает переменную окружения name в значение value или, если значение не указано, удаляет переменную окружения. Пример:

testdb=> \setenv PAGER less
testdb=> \setenv LESS -imx4F
\sf[+] <function_description>

Извлекает и показывает определение указанной функции в форме команды CREATE OR REPLACE FUNCTION. Определение выводится в текущий канал вывода запросов, заданный командой \o.

Целевая функция может быть указана только по имени либо по имени и списку аргументов, например, foo(integer, text). Типы аргументов необходимо указывать, если существует более одной функции с тем же именем.

Если к имени команды добавлен +, выходные строки нумеруются, причем первая строка тела функции получает номер 1.

\t [novalue | on | off]

Команда \t сама по себе переключает отображение заголовков столбцов и результирующих строк с количеством строк. Значения on и off устанавливают режим "только кортежи" независимо от текущих настроек. Команда \t является эквивалентом \pset tuples_only.

\T <table_options>

Указывает атрибуты для размещения внутри тега table в формате вывода HTML. Эта команда эквивалентна \pset tableattr table_options

\timing [novalue | on | off]

Без параметра переключает отображение времени выполнения каждой SQL-инструкции в миллисекундах. Значения on и off устанавливают отображение времени независимо от текущей настройки.

\unset <name>

Удаляет переменную psql name.

\w | \write <filename>
\w | \write | <command>

Выводит текущий буфер запросов в файл filename или передает его в команду оболочки command.

\watch [<seconds>]

Повторно выполняет текущий буфер запросов (как \g) до прерывания или пока запрос не завершится с ошибкой. Ожидает указанное количество секунд (по умолчанию 2) между выполнениями.

\x [ on | off | auto ]

Устанавливает или переключает режим расширенного форматирования таблиц. Эквивалентно \pset expanded.

\z [<pattern>]

Выводит список таблиц, представлений и последовательностей с их связанными привилегиями доступа. Если указан шаблон, выводятся только таблицы, представления и последовательности, имена которых соответствуют шаблону. Псевдоним для \dp.

\! [<command>]

Выполняет переход в отдельную оболочку или выполняет команду оболочки command. Аргументы не интерпретируются psql и передаются оболочке как есть. В частности, не применяются правила подстановки переменных и экранирования обратной косой чертой.

\?

Показывает справочную информацию о метакомандах.

Шаблоны поиска

Различные команды \d принимают параметр-шаблон для указания имен отображаемых объектов. В простейшем случае шаблон представляет собой точное имя объекта. Символы в шаблоне обычно приводятся к нижнему регистру, так же как и имена SQL; например, команда \dt FOO отобразит таблицу с именем foo. Как и в именах SQL, заключение шаблона в двойные кавычки предотвращает приведение к нижнему регистру. Если требуется включить в шаблон символ двойной кавычки, его следует записать как пару двойных кавычек внутри строки в двойных кавычках; это соответствует правилам для цитируемых идентификаторов SQL. Например, \dt "FOO""BAR" отобразит таблицу с именем FOO"BAR (а не foo"bar). В отличие от обычных правил для имен SQL, вы можете заключить в двойные кавычки только часть шаблона, например \dt FOO"FOO"BAR отобразит таблицу с именем fooFOObar.

В шаблоне * соответствует любой последовательности символов (включая пустую строку), а ? соответствует любому одиночному символу. Эта нотация аналогична шаблонам имен файлов в оболочке Unix. Например, команда \dt int* отображает все таблицы, имена которых начинаются с int. Однако внутри двойных кавычек символы * и ? теряют свое специальное значение и сопоставляются буквально.

Шаблон, содержащий точку (.), интерпретируется как шаблон имени схемы, за которым следует шаблон имени объекта. Например, \dt foo*.bar* отображает все таблицы, имена которых начинаются с bar, находящиеся в схемах, имена которых начинаются с foo. Когда точка отсутствует, шаблон соответствует только объектам, видимым в текущем пути поиска схемы. Опять же, точка внутри двойных кавычек теряет свое специальное значение и сопоставляется буквально.

Опытные пользователи могут использовать возможности регулярных выражений. Все специальные символы регулярных выражений работают так, как указано в документации PostgreSQL о регулярных выражениях, за исключением того, что . воспринимается как разделитель (см. выше), * транслируется в регулярное выражение .*, а ? транслируется в .. Вы можете эмулировать эти шаблонные символы при необходимости, используя ? для ., (R+|) для R* или (R|) для R?. Помните, что шаблон должен соответствовать всему имени, в отличие от обычной интерпретации регулярных выражений; используйте * в начале и/или конце, если не хотите, чтобы шаблон был "закреплен". Обратите внимание: внутри двойных кавычек все специальные символы регулярных выражений теряют свое специальное значение и сопоставляются буквально. Кроме того, специальные символы регулярных выражений сопоставляются буквально в шаблонах имен операторов (например, в аргументе команды \do).

Когда параметр pattern не указан, команды \d отображают все объекты, видимые в текущем пути поиска схемы — это эквивалентно использованию шаблона *. Чтобы увидеть все объекты в базе данных, используйте шаблон *.*.

Расширенные возможности

Переменные

psql поддерживает подстановку переменных, аналогичную обычным командным оболочкам Unix. Переменные представляют собой пары имя/значение, где значение может быть любой строкой любой длины. Имя переменной должно состоять из букв (включая нелатинские), цифр и символов подчеркивания.

Для установки переменной используйте метакоманду \set. Например:

testdb=> \set foo bar

устанавливает переменную foo в значение bar. Чтобы получить содержимое переменной, поставьте перед именем двоеточие, например:

testdb=> \echo :foo
bar

Это работает как в обычных SQL-командах, так и в метакомандах; см. подробности в разделе SQL-интерполяция.

Если \set вызывается без второго аргумента, переменная получает пустую строку в качестве значения. Чтобы удалить переменную, используйте команду \unset. Чтобы отобразить все переменные и их значения, вызовите \set без аргументов.

ПРИМЕЧАНИЕ

Аргументы \set подчиняются тем же правилам подстановки, что и у других команд. Таким образом, возможны такие конструкции, как \set :foo 'something', которые приводят, соответственно, к "мягким ссылкам" или "переменным переменных", известным в Perl и PHP. Обратите внимание, что такие конструкции не дают практической пользы. С другой стороны, \set bar :foo — это вполне корректный способ скопировать значение переменной.

Некоторые переменные psql обрабатывает особым образом. Они представляют собой настройки параметров, которые могут изменяться во время выполнения, или, в некоторых случаях, изменяемое состояние самого psql. Хотя такие переменные можно использовать и для других целей, это не рекомендуется, так как поведение программы может стать непредсказуемым. По соглашению, имена всех специально обрабатываемых переменных состоят из заглавных букв ASCII (возможно с цифрами и подчеркиваниями). Для обеспечения максимальной совместимости в будущем избегайте использования таких имен для собственных переменных. Ниже приведен список всех специально обрабатываемых переменных.

AUTOCOMMIT

Если включено (on, по умолчанию), каждая SQL-команда автоматически фиксируется при успешном выполнении. Чтобы отложить фиксацию, используйте SQL-команду BEGIN или START TRANSACTION. Если режим выключен (off) или не установлен, SQL-команды не фиксируются до явного выполнения COMMIT или END. Режим автоматической фиксации работает через неявное выполнение BEGIN перед любой командой, которая еще не находится внутри блока транзакции, не является самой командой BEGIN или другой командой управления транзакциями и не относится к командам, которые нельзя выполнять внутри блока транзакции (например, VACUUM).

В режиме без автоматической фиксации необходимо явно прервать неудавшуюся транзакцию с помощью ABORT или ROLLBACK. Обратите внимание, что при выходе из сессии без фиксации все несохраненные изменения будут потеряны.

Режим автоматической фиксации — это традиционное поведение PostgreSQL, тогда как режим без автоматической фиксации ближе к стандарту SQL. Если вы предпочитаете режим без автоматической фиксации, установите его в файле ~/.psqlrc.

COMP_KEYWORD_CASE

Определяет регистр букв при автодополнении SQL-ключевых слов. Если значение установлено в lower или upper, завершенное слово будет приведено к нижнему или верхнему регистру соответственно. Если значение установлено в preserve-lower или preserve-upper (по умолчанию), завершенное слово сохраняет регистр уже введенного текста, а слова, завершаемые без ввода, автоматически принимают нижний или верхний регистр соответственно.

DBNAME

Имя текущей базы данных. Устанавливается при подключении (включая запуск программы) и может быть сброшено.

ECHO

Если значение установлено в all, все непустые входные строки выводятся в стандартный вывод по мере их чтения. Не касается строк, вводимых в интерактивном режиме. Чтобы включить это поведение при запуске программы, используйте ключ -a. Если значение установлено в queries, psql выводит каждый SQL-запрос в стандартный вывод по мере его отправки на сервер. Для этого используется ключ -e.

ECHO_HIDDEN

Если переменная установлена в on, каждая команда с обратной косой чертой, выполняющая запрос к базе данных, сначала отображается. Это удобно для изучения работы Greengage DB и для воспроизведения функциональности в собственных программах. Чтобы выбрать такое поведение при запуске программы, используйте ключ -E. Если установить переменную в noexec, запросы только отображаются, но не отправляются на сервер и не выполняются.

ENCODING

Текущая кодировка набора символов клиента.

FETCH_COUNT

Если переменная установлена в целое значение > 0, результаты запросов SELECT извлекаются и отображаются группами по указанному количеству строк вместо сбора всего набора результатов перед отображением. При этом используется ограниченный объем памяти независимо от размера набора результатов. Обычно используются значения от 100 до 1000. Учтите, что запрос может завершиться с ошибкой после отображения некоторых строк.

Хотя можно использовать любой формат вывода, формат по умолчанию aligned обычно выглядит неудобно, поскольку каждая группа строк FETCH_COUNT форматируется отдельно, что может менять ширину столбцов. Другие форматы вывода воспринимаются лучше.

HISTCONTROL

Если переменная установлена в ignorespace, строки, начинающиеся с пробела, не добавляются в историю. При значении ignoredups повторяющиеся строки (совпадающие с предыдущей) не сохраняются. Значение ignoreboth объединяет оба этих поведения. Если переменная не установлена или имеет любое другое значение, все строки, введенные в интерактивном режиме, добавляются в историю.

HISTFILE

Имя файла, используемого для хранения истории команд. Значение по умолчанию — ~/.psql_history. Например, добавление:

\set HISTFILE ~/.psql_history-:DBNAME

в файл ~/.psqlrc приведет к ведению отдельной истории команд psql для каждой базы данных.

HISTSIZE

Количество команд для хранения в истории команд. Значение по умолчанию — 500.

HOST

Хост базы данных, к которому вы в данный момент подключены. Значение устанавливается при каждом подключении (включая запуск программы) и может быть сброшено.

IGNOREEOF

Если переменная не установлена, отправка символа EOF (обычно Ctrl+D) в интерактивной сессии psql завершает работу приложения. Если установлено числовое значение, то указанное количество символов EOF игнорируется перед завершением. Если переменная установлена, но не содержит числового значения, используется значение по умолчанию — 10.

LASTOID

Значение последнего затронутого OID, возвращенного командой INSERT или lo_import. Эта переменная действительна только до выполнения следующей SQL-команды.

ON_ERROR_ROLLBACK

Если значение установлено в on, при возникновении ошибки в инструкции блока транзакции ошибка игнорируется и транзакция продолжается. Если значение установлено в interactive, такие ошибки игнорируются только в интерактивных сессиях, но не при чтении файлов скриптов. Если переменная не установлена или установлена в off, инструкция в блоке транзакции, генерирующая ошибку, отменяет всю транзакцию. Режим отката ошибок работает через неявное создание SAVEPOINT перед каждой командой в блоке транзакции и откат к этой точке при ошибке.

ON_ERROR_STOP

По умолчанию обработка команд продолжается после ошибки. Если переменная установлена в on, выполнение немедленно останавливается. В интерактивном режиме psql возвращается к командной строке, иначе приложение завершится с кодом ошибки 3, чтобы отличить этот случай от фатальных ошибок, которые возвращают код 1. Во всех случаях все выполняющиеся скрипты (верхнего уровня и любые вызываемые ими) завершаются немедленно. Если командная строка верхнего уровня содержит несколько SQL-команд, обработка остановится на текущей команде.

PORT

TCP-порт базы данных, к которому вы в данный момент подключены. Значение устанавливается при каждом подключении (включая запуск программы) и может быть сброшено.

PROMPT1
PROMPT2
PROMPT3

Определяют внешний вид приглашений, отображаемых psql. Подробнее см. в разделе Приглашения.

QUIET

Установка этой переменной в on эквивалентна использованию параметра командной строки -q. В интерактивном режиме она практически не имеет смысла.

SINGLELINE

Эта переменная эквивалентна параметру командной строки -S.

SINGLESTEP

Установка этой переменной в on эквивалентна параметру командной строки -s.

USER

Имя пользователя базы данных, под которым вы в данный момент подключены. Значение устанавливается при каждом подключении (включая запуск программы) и может быть сброшено.

VERBOSITY

Определяет уровень подробности сообщений об ошибках; допустимые значения: default, verbose и terse.

SQL-интерполяция

Ключевая особенность переменных psql — возможность подставлять (интерполировать) их в обычные SQL-инструкции и аргументы метакоманд. Кроме того, psql предоставляет средства для корректного цитирования значений переменных, используемых в качестве SQL-литералов и идентификаторов. Для интерполяции значения без цитирования перед именем переменной ставится двоеточие (:). Например:

testdb=> \set foo 'my_table'
testdb=> SELECT * FROM :foo;

выполнит запрос к таблице my_table. Обратите внимание, что это может быть небезопасно: значение переменной копируется буквально и может содержать несбалансированные кавычки или даже команды с обратной косой чертой. Убедитесь, что такая подстановка подходит для конкретного контекста.

Если значение должно использоваться как SQL-литерал или идентификатор, безопаснее заключить его в кавычки. Для SQL-литерала используйте двоеточие перед именем переменной в одинарных кавычках. Для SQL-идентификатора используйте двоеточие перед именем переменной в двойных кавычках. Эти конструкции корректно обрабатывают кавычки и другие специальные символы в значении переменной. Предыдущий пример будет безопаснее переписать так:

testdb=> \set foo 'my_table'
testdb=> SELECT * FROM :"foo";

Интерполяция переменных не выполняется внутри SQL-литералов и идентификаторов, заключенных в кавычки. Поэтому конструкция ':foo' не подходит для создания литерала в кавычках из значения переменной — это было бы небезопасно, так как кавычки в значении обрабатывались бы некорректно.

Пример использования такого подхода — копирование содержимого файла в столбец таблицы. Сначала загрузите файл в переменную, затем интерполируйте ее значение как строку в кавычках:

testdb=> \set content `cat my_file.txt`
testdb=> INSERT INTO my_table VALUES (:'content');

Обратите внимание, что это все равно не сработает, если my_file.txt содержит байты NUL. psql не поддерживает встроенные байты NUL в значениях переменных.

Так как двоеточия могут встречаться в SQL-командах, попытка интерполяции (например, :name, :'name' или :"name") не выполняется для неустановленных переменных. При необходимости двоеточие можно экранировать обратной косой чертой, чтобы защитить его от подстановки.

Синтаксис с двоеточием для переменных является стандартным в SQL для встраиваемых языков запросов, таких как ECPG. Синтаксисы с двоеточием для срезов массивов и приведения типов являются расширениями Greengage DB и иногда могут конфликтовать со стандартным использованием. Синтаксис "двоеточие + кавычки" для экранирования значения переменной как SQL-литерала или идентификатора является расширением psql.

Приглашения

Приглашения psql можно настроить по собственным предпочтениям. Три переменные — PROMPT1, PROMPT2 и PROMPT3 — содержат строки с особыми escape-последовательностями, которые определяют внешний вид приглашения:

  • Приглашение 1 (PROMPT1) отображается при запросе новой команды.

  • Приглашение 2 (PROMPT2) появляется, когда требуется дополнительный ввод, например, если команда не завершена точкой с запятой или открыта кавычка.

  • Приглашение 3 (PROMPT3) используется при выполнении SQL-команды COPY FROM STDIN, когда нужно вводить строки в терминале.

Значение выбранной переменной приглашения выводится буквально, за исключением случаев, когда встречается знак процента (%). В зависимости от следующего символа вместо него подставляется определенный текст. Доступные подстановки:

%M

Полное имя хоста (с доменным именем) сервера базы данных, или [local], если используется подключение через сокет домена Unix, или [local:/dir/name], если при компиляции был изменен путь доменного сокета Unix по умолчанию.

%m

Имя хоста сервера базы данных, усеченное до первой точки, или [local], если используется подключение через сокет домена Unix.

%>

Номер порта, который прослушивает сервер баз данных.

%n

Имя пользователя сессии базы данных. Это значение может меняться в течение сессии в результате выполнения команды SET SESSION AUTHORIZATION.

%/

Имя текущей базы данных.

%~

Похоже на %/, но вывод — ~ (тильда), если текущая база данных совпадает с базой данных по умолчанию.

%#

Если пользователь сессии является суперпользователем, то #; в противном случае >. Это значение может меняться в течение сессии в результате выполнения команды SET SESSION AUTHORIZATION.

%R

В приглашении 1 обычно =, но ^, если включен однострочный режим, или !, если сессия отключена от базы данных (например, при неудачном выполнении \connect).

В приглашении 2 %R заменяется символом, который зависит от причины, по которой psql ожидает дополнительный ввод:

  • -, если команда еще не завершена;

  • *, если есть незавершенный комментарий /* …​ */;

  • одинарная кавычка, если есть незавершенная строка в одинарных кавычках;

  • двойная кавычка, если есть незавершенный идентификатор в двойных кавычках;

  • знак доллара, если есть незавершенная строка в долларовых кавычках;

  • (, если есть несовпадающая левая скобка.

В приглашении 3 %R не отображается.

%x

Статус транзакции:

  • пустая строка — не в блоке транзакции;

  • * — в блоке транзакции;

  • ! — в транзакционном блоке, в котором произошла ошибка;

  • ? — состояние транзакции не определено (например, нет подключения к базе данных).

%<digits>

Подставляется символ с указанным восьмеричным кодом.

%:<name>

Значение переменной psql name. Подробности см. в разделе Переменные.

%`<command>`

Вывод команды, аналогично обычной подстановке обратных кавычек.

%[ …​ %]

Приглашения могут содержать управляющие символы терминала, которые, например, изменяют цвет, фон или стиль текста приглашения или изменяют заголовок окна терминала. Чтобы редактирование строк работало правильно, эти непечатаемые управляющие символы должны быть обозначены как невидимые путем их окружения %[ и %]. В приглашении может встречаться несколько таких пар. Например:

testdb=> \set PROMPT1 '%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%#'

приводит к жирному (1;) желтому на черном (33;40) приглашению на VT100-совместимых цветных терминалах. Чтобы вставить знак процента в приглашение, напишите %%. Приглашения по умолчанию — '%/%R%# ' для приглашений 1 и 2, и '>> ' для приглашения 3.

Редактирование командной строки

psql использует библиотеку readline для удобного редактирования команд и работы с историей строк. История команд автоматически сохраняется при выходе из psql и загружается при его запуске. Также поддерживается автодополнение по клавише Tab, хотя оно не заменяет полноценный SQL-парсер. Запросы, сгенерированные автодополнением, иногда могут мешать выполнению других SQL-команд, например, SET TRANSACTION ISOLATION LEVEL. Если по какой-либо причине автодополнение по нажатию Tab вам не нужно, его можно отключить, добавив соответствующую настройку в файл .inputrc в вашем домашнем каталоге:

$if psql
set disable-completion on
$endif

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

COLUMNS

Если значение \pset columns равно нулю, эта настройка управляет шириной для формата с переносом и определяет, нужен ли пейджер для широкого вывода или следует использовать вертикальный формат в расширенном автоматическом режиме.

PAGER

Если результаты запроса не помещаются на экран, они выводятся через указанный пейджер. Типичными значениями являются more или less. Значение по умолчанию зависит от платформы. Использование пейджера можно отключить, установив переменную PAGER в пустое значение или с помощью параметров пейджера команды \pset.

PGDATABASE
PGHOST
PGPORT
PGUSER

Параметры подключения по умолчанию.

PSQL_EDITOR
EDITOR
VISUAL

Редактор, используемый командами \e и \ef. Переменные проверяются в указанном порядке, и используется первая найденная.

Редакторы по умолчанию: vi для Unix-систем и notepad.exe для Windows.

PSQL_EDITOR_LINENUMBER_ARG

Когда команды \e или \ef вызываются с указанием номера строки, эта переменная задает аргумент командной строки, через который передается начальный номер строки в редактор пользователя. Например, для редакторов Emacs или vi, используется плюс (+). Если между именем параметра и номером строки требуется пробел, включите его в значение переменной. Примеры:

PSQL_EDITOR_LINENUMBER_ARG='+'
PSQL_EDITOR_LINENUMBER_ARG='--line '

По умолчанию значение переменной — + в Unix-системах (что соответствует редактору vi по умолчанию и подходит для многих других распространенных редакторов); в системах Windows значение по умолчанию отсутствует.

PSQL_HISTORY

Альтернативное расположение файла истории команд. Допускается использование тильды (~).

PSQLRC

Альтернативное расположение файла .psqlrc пользователя. Допускается использование тильды (~).

SHELL

Команда, выполняемая командой \!.

TMPDIR

Каталог для хранения временных файлов. По умолчанию — /tmp.

Файлы

psqlrc и ~/.psqlrc

Если не указан параметр -X или -c, psql пытается прочитать и выполнить команды из общесистемного файла запуска (psqlrc), а затем из личного файла запуска пользователя (~/.psqlrc) после подключения к базе данных, но до обработки обычных команд. Эти файлы можно использовать для настройки клиента и/или сервера, обычно с помощью команд \set и SET.

Общесистемный файл запуска называется psqlrc и находится в каталоге "системной конфигурации" установки, который наиболее надежно определяется командой pg_config --sysconfdir. По умолчанию это каталог ../etc/ относительно каталога с исполняемыми файлами Greengage DB. Имя каталога можно явно задать через переменную окружения PGSYSCONFDIR.

Личный файл запуска пользователя называется ~/.psqlrc и находится в домашнем каталоге вызывающего пользователя. В Windows, где отсутствует концепция домашнего каталога, личный файл запуска располагается по пути %APPDATA%\postgresql\psqlrc.conf. Расположение файла можно явно указать с помощью переменной окружения PSQLRC.

Оба файла — общесистемный и пользовательский — могут быть специфичными для версии psql, если к имени файла добавить тире и основной или дополнительный номер релиза PostgreSQL, например ~/.psqlrc-9.4. Файл, наиболее точно соответствующий версии, читается с приоритетом над файлом без указания версии.

.psql_history

История команд хранится в файле ~/.psql_history или %APPDATA%\postgresql\psql_history в Windows.

Расположение файла истории можно явно задать с помощью переменной окружения PSQL_HISTORY.

Примечания

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

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

Примечания для пользователей Windows

psql создан как консольное приложение. Поскольку консольные окна Windows используют кодировку, отличную от остальной части системы, при работе с 8-битными символами в psql требуется особая осторожность. Если psql обнаружит несовместимую кодовую страницу консоли, он выдаст предупреждение при запуске. Для изменения кодовой страницы консоли необходимо выполнить два шага:

  1. Установите кодовую страницу, введя команду:

    $ cmd.exe /c chcp 1252

    1252 — кодировка символов латинского алфавита, используемая Microsoft Windows для английского и некоторых других западных языков. Если вы используете Cygwin, эту команду можно добавить в файл /etc/profile.

  2. Установите консольный шрифт в Lucida Console, поскольку растровый шрифт не поддерживает кодовую страницу ANSI.

Примеры

Запуск psql в интерактивном режиме:

$ psql -p 54321 -U sally mydatabase

В интерактивном режиме psql команда может быть распределена на несколько строк ввода. Обратите внимание на изменяющееся приглашение:

testdb=> CREATE TABLE my_table (
testdb(>  first integer not null default 0,
testdb(>  second text)
testdb-> ;
CREATE TABLE

Просмотр определения таблицы:

testdb=> \d my_table
             Table "public.my_table"
 Column    |  Type   |      Modifiers
-----------+---------+--------------------
 first     | integer | not null default 0
 second    | text    |
Distributed by: (first)

Запуск psql в неинтерактивном режиме путем передачи файла, содержащего SQL-команды:

$ psql -f /home/gpadmin/test/myscript.sql

См. также

Предыдущая
plcontainer
Следующая
reindexdb