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

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

Синтаксис

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

Описание

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

Параметры

-h <ХОСТ>
--host <ХОСТ>
Определяет хост сервера баз данных. Если значение начинается с косой черты, оно используется как каталог для доменного сокета Unix. [default: /var/run/postgresql/]
-d <БД>
--database <БД>
Определяет имя базы данных для подключения. [default: параметр --username]
-p <ПОРТ>
--port <ПОРТ>
Указывает порт TCP или расширение файла локального сокета Unix-домена, на котором сервер прослушивает соединения. По умолчанию используется значение 5432
-U <ПОЛЬЗОВАТЕЛЬ>
--username <ПОЛЬЗОВАТЕЛЬ>
Имя пользователя [default: Пользователь ОС]
-W <ПАРОЛЬ>
--password <ПАРОЛЬ>
Явное указание пароля [deprecated]
-l, <УРОВЕНЬ>
--log-level <УРОВЕНЬ>
Уровень логирования (Off, Error, Warn, Info, Debug, Trace) [default: Info]

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

--help
Показать справку о qsql и выйти.
-w
--no-password
Отменяет запрос пароля. В текущей версии при неудачном подключении пароль, тем не менее, будет запрошен.
--version
Распечатать версию qsql и выйти.

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

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

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

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

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

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

Ввод команд SQL

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

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

testdb=>

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

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

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

Метакоманды

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

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

help

Вывести основные команды

\q, \quit, quit

Выйти из qsql

\h, \help

Вывести команды SQL

\?

Вывести команды qsql

\l, \list

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

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

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

Когда в команде опускается имя базы данных, пользователь, компьютер или порт, для нового подключения могут использоваться значения от предыдущего. По умолчанию значения от предыдущего подключения используются повторно, если только не указывается строка подключения (строка_подключения). Если передать в первом аргументе -reuse-previous=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

\! [ команда ]

Метакоманда позволяет перейти в процесс оболочки (без указания параметра "команда") либо выполнить произвольную команду оболочки (указанную в параметре)

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

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

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

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

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

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

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

\i или \include файл

Чтение и выполнение команд из указанного файла

\password [ username ]

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

\copy { table [ ( column_list ) ] } from { 'filename' | program 'command' | stdin | pstdin } [ [ with ] ( option [, ...] ) ]

\copy { table [ ( column_list ) ] | ( query ) } to { 'filename' | program 'command' | stdout | pstdout } [ [ with ] ( option [, ...] ) ]

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

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

В остальном, данная форма команды \copy принимает те же параметры, что и SQL COPY на сервере БД

\cd [ каталог ]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

\ddp [ шаблон ]

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

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

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

\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         

Окружение

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)