qsql

• Синтаксис
• Описание
• Параметры
  • Дополнительные параметры (флаги)
• Статус выхода
• Использование
  • Подключение к базе данных
  • Ввод команд SQL
  • Метакоманды
• Окружение
• Примеры

qsql - интерактивный терминал QHB.

Синтаксис

qsql [параметры]

Описание

qsql — это терминальный клиент QHB. Эта программа позволяет интерактивно вводить запросы, выполнять их в QHB и просматривать результаты запроса. Также запросы можно вводить из файла, из конвейера ранее запущенной программы или из аргументов командной строки. Кроме того, qsql предоставляет набор метакоманд и различные функции для облегчения написания сценариев и автоматизации широкого спектра задач.

Параметры

-d имя_БД
--database=имя_БД

Указывает имя базы данных для подключения.
Значение по умолчанию: пользователь_ОС.

-h имя_хоста
--host=имя_хоста

Указывает имя хоста сервера баз данных. Если значение начинается с косой черты, оно используется как каталог для сокета Unix-домена.
Значение по умолчанию: /var/run/postgresql/.

-l уровень
--log-level=уровень

Указывает уровень логирования: Off, Error, Warn, Info, Debug или Trace.
Значение по умолчанию: Info.

-p порт
--port=порт

Указывает порт TCP или расширение файла локального сокета Unix-домена, на котором сервер принимает подключения.
Значение по умолчанию: 5432.

-U имя_пользователя
--username=имя_пользователя

Указывает имя пользователя для подключения к базе данных.
Значение по умолчанию: пользователь_ОС

-W пароль
--password=пароль

Явное указание пароля. Этот параметр считается устаревшим и не рекомендуется к использованию.

Дополнительные параметры (флаги)

--help

Показать справку по qsql и завершить работу.

--version

Распечатать версию qsql и завершить работу.

-w
--no-password

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

Статус выхода

qsql возвращает оболочке 0, если программа завершилась нормально, или 1, если произошла ошибка.

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

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

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

Если соединение не может быть установлено по какой-либо причине (например, недостаточно прав, сервер не работает на целевом хосте и т. д.) qsql вернет ошибку и завершит работу.

Ввод команд SQL

При работе в штатном режиме в командной строке qsql отображается имя базы данных, к которой qsql в настоящее время подключен, а затем идет строка =>. Например:

$ qsql testdb
qsql (1.0)
Type "help" for help.

testdb=>

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

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

При каждом выполнении команды qsql также проверяет асинхронные уведомления о событиях, генерируемые командами LISTEN и NOTIFY.

Метакоманды

Все, что вы вводите в qsql, не заключенное в кавычки и начинающееся с обратной косой черты, является метакомандой qsql, которая обрабатывается самим qsql. Эти команды делают qsql более полезным для администрирования или написания скриптов. Метакоманды часто называют командами слэша или обратной косой черты.

Доступные метакоманды:

\c или \connect [ -reuse-previous=on|off ] [ имя_БД [ имя_пользователя ] [ хост ] [ порт ] | строка_подключения ]

Устанавливает новое подключение к серверу QHB. Параметры подключения можно указывать как позиционно (в показанном порядке), так и передавая аргумент строке_подключения. Если аргументы не указаны, новое подключение устанавливается с теми же параметрами, что и предыдущее.

Указание в параметре имя_БД, имя_пользователя, хост или порт значения - равнозначно опущению этого параметра, при этом для нового подключения также могут использоваться значения от предыдущего. По умолчанию значения от предыдущего подключения используются повторно при позиционной записи, но не когда указывается строка_подключения. Если передать в первом аргументе -reuse- revious=on или -reuse-previous=off, это поведение переопределяется.

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

Примеры:

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

\cd [ каталог ]

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

Подсказка:
Для получения значения текущего каталога (до или после команды \cd) используйте команду \!, например: \! pwd.

\copy { таблица [ ( список_столбцов ) ] } from { 'имя_файла' | program_'команда'_ | stdin | pstdin } [ [ with ] ( параметр [, ...] ) ]
\copy { table [ ( список_столбцов ) ] | ( запрос ) } to { 'имя_файла' | program 'команда' | stdout | pstdout } [ [ with ] ( параметр [, ...] ) ]

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

Доступны также источники/приемники данных запроса в виде конвейера (для параметра 'команда') или декскрипторов стандартного ввода-вывода.

В остальном данная форма команды \copy имеет схожий синтаксис и принимает те же параметры, что и SQL-команда COPY на сервере базы данных.

\da[S] [ шаблон ]

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

\dA[+] [ шаблон ]

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

\db[+] [ шаблон ]

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

\dc[S+] [ шаблон ]

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

\dC[+] [ шаблон ]

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

\dd[S] [ шаблон ]

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

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

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

\dD[S+] [ шаблон ]

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

\ddp [ шаблон ]

Выводит список прав доступа по умолчанию. Выводится строка для каждой роли (и схемы, если применимо), для которой права доступа по умолчанию отличаются от встроенных. Если указан шаблон, выводятся строки только для тех ролей и схем, имена которых соответствуют ему. Права доступа по умолчанию устанавливаются командой ALTER DEFAULT PRIVILEGES. Смысл отображаемых прав объясняется в разделе Права.

\dE[S+] [ шаблон ]
\di[S+] [ шаблон ]
\dm[S+] [ шаблон ]
\ds[S+] [ шаблон ]
\dt[S+] [ шаблон ]
\dv[S+] [ шаблон ]

ВНИМАНИЕ! В настоящий момент шаблон не поддерживается!

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

\des[+] [ шаблон ]

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

\det[+] [ шаблон ]

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

\deu[+] [ шаблон ]

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

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

\dew[+] [ шаблон ]

Выводит список оберток сторонних данных (мнемоника: «external wrappers»). Если указан шаблон, выводятся только те обертки сторонних данных, имена которых соответствуют ему. Если используется форма \dew+, то дополнительно выводятся права доступа, параметры и описание обертки.

\df[antwS+] [ шаблон ]

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

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

\dF[+] [ шаблон ]

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

\dFd[+] [ шаблон ]

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

\dFp[+] [ шаблон ]

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

\dFt[+] [ шаблон ]

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

\du

Вывести всех пользователей.

qsql

rolname  | rolsuper | rolinherit | rolcreaterole | rolcreatedb | rolcanlogin | rolconnlimit | rolvaliduntil | memberof                                                                                                                         | rolreplication | rolbypassrls
---------+----------+------------+---------------+-------------+-------------+--------------+---------------+----------------------------------------------------------------------------------------------------------------------------------+----------------+--------------
qhb      | true     | true       | true          | true        | true        | -1           | <null>        | <null>: error deserializing column 8: cannot convert between the Rust type `alloc::string::String` and the Postgres type `_name` | true           | true

\g [ имя_файла ]
\g [ |команда ]

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

Данная метакоманда может использоваться для получения эффекта, подобного команде \out, без изменения направления вывода результатов запроса на постоянной основе

\h или \help

Выводит подсказку по синтаксису всех команд SQL.

\i или \include имя_файла

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

\l или \list

Выводит список баз данных на сервере.

\o или \out [ имя_файла ]
\o или \out [|команда ]

При вводе метакоманды qsql перенаправляет результаты последующих запросов в файл имя_файла или команду оболочки команда при помощи конвейера.

Исключением являются сообщения об ошибках, на которые данный параметр не влияет.

\password [ имя_пользователя ]

Изменяет пароль для указанного пользователя. Если параметр имя_пользователя не указан, то смена пароля затрагивает текущего пользователя. Данная команда запрашивает новый пароль, шифрует его и отсылает на сервер в виде команды ALTER ROLE.

\q или \quit

Выйти из qsql.

\?

Выводит справочную информацию по командам qsql.

\! [ команда ]

Без аргументов позволяет перейти в процесс оболочки; по завершении этой оболочки qsql продолжает свою работу. Если аргумент команда указан, запускает соответствующую команду оболочки.

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

Окружение

PGHOST

Переменная отвечает за значение параметра --host, применяемое при запуске qsql по умолчанию.

Примеры

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

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

Давайте предположим, что вы заполнили таблицу данными и хотите посмотреть на нее:

testdb=> SELECT * FROM my_table;
 first | second
-------+--------
     1 | one
     2 | two
     3 | three
     4 | four
(4 rows)

или:

testdb=> SELECT first, second, first > 2 AS gt2 FROM my_table;
 first | second | gt2
-------+--------+-----
     1 | one    | f
     2 | two    | f
     3 | three  | t
     4 | four   | t
(4 rows)