Перейти к содержанию

Подключение и работа в консоли

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

По умолчанию окно терминала, в котором происходит запуск инстанса Picodata, служит для вывода отладочного журнала инстанса. Для ввода команд следует подключиться к Picodata из другого терминала. Возможны два варианта:

В последнем случае, в качестве клиента рекомендуется использовать клиентское приложение psql.

Установка psql

Клиентское приложение psql уже поставляется в составе готовых пакетов Picodata. В остальных случаях для использования psql не требуется устанавливать сам сервер баз данных PostgreSQL. В Linux достаточно установить пакет postgresql-client (Debian/Ubuntu) или postgresql (RHEL/Fedora). В macOS установите пакет libpq через Homebrew.

См. также:

Консоль администратора

Настройка и подключение

Консоль администратора предоставляет доступ к учетной записи Администратора СУБД (admin). Для запуска консоли используйте следующую команду с указанием файла unix-сокета:

picodata admin ./admin.sock

По умолчанию файл unix-сокета расположен в рабочей директории инстанса, указанной в файле конфигурации в параметре instance.instance_dir. Путь к этому файлу можно переопределить, задав параметр instance.admin_socket.

При успешном подключении отобразится приглашение:

$ picodata admin ./admin.sock
Connected to admin console by socket path "./admin.sock"
type '\help' for interactive help
(admin) sql>

По умолчанию, консоль администратора интерпретирует вводимые команды на языке SQL. Разделителем по умолчанию выступает знак ;. Для переключения в режим ввода Lua-команд введите \lua. В Lua-режиме разделитель не требуется.

Задание пароля администратора

По умолчанию у Администратора СУБД отсутствует пароль, поэтому подключиться к консоли администратора возможно только при наличии доступа к файлу сокета средствами ОС. Для того чтобы иметь возможность подключиться к инстансу по сети, задайте пароль администратора:

ALTER USER "admin" WITH PASSWORD 'T0psecret';

После этого Администратор СУБД сможет подключиться, используя следующую команду:

psql postgres://admin:T0psecret@127.0.0.1:4327

Кроме того, задать пароль администратора можно при инициализации кластера, установив переменную окружения PICODATA_ADMIN_PASSWORD для его первого инстанса. При повторных запусках данная переменная будет игнорироваться.

См. также:

Создание учетной записи пользователя

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

CREATE USER "alice" WITH PASSWORD 'T0psecret';

Чтобы новый пользователь мог создавать таблицы, выдайте ему соответствующую привилегию:

GRANT CREATE TABLE TO "alice";

Автоматизация первичной настройки

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

setup.sql 
ALTER USER "admin" WITH PASSWORD 'T0psecret';
CREATE USER "alice" WITH PASSWORD 'T0psecret';
GRANT CREATE TABLE TO "alice";
GRANT READ TABLE TO "alice";
GRANT WRITE TABLE TO "alice";

Запустите этот скрипт в консоли администратора:

picodata admin ./admin.sock < ../setup.sql

Пример вывода:

Connected to admin console by socket path "admin.sock"
type '\help' for interactive help
1
1
1
1
1
Bye

Команды будут выполнены последовательно. Числа означают количество измененных строк после каждой команды.

Подключение по протоколу PostgreSQL

После того как в системе создана пользовательская учетная запись, можно подключиться к любому локальному или удаленному инстансу и выполнять распределенные SQL-команды в рамках кластера. Picodata позволяет это делать при помощи большого числа хорошо знакомых инструментов и библиотек, написанных для PostgreSQL. Рекомендуемым способом подключения к инстансу Picodata является CLI-приложение psql. По умолчанию используется порт 4327 (его можно переопределить, задав параметр конфигурации instance.pg.listen).

Строка подключения к Picodata по протоколу PostgreSQL имеет следующий формат:

postgres://[user]:[password]@[host]:[port]/[database]?options=value1&key2=value2
  • user — имя пользователя
  • password — пароль пользователя
  • host — IP-адрес узла, к которому производится подключение
  • port — номер порта, по которому сервер принимает подключения. По умолчанию используется порт 4327 (его можно переопределить, задав параметр конфигурации instance.pg.listen)
  • database — название базы данных. В случае с Picodata допускается любое значение (включая пустое)
  • options — дополнительные параметры сессии (см. ниже)

Пример подключения к узлу 127.0.0.1:

psql postgres://admin:T0psecret@127.0.0.1:4327

В соответствии с доступными ему привилегиями, пользователь сможет работать в консоли с таблицами. Разделителем команд выступает знак ;.

Примечание

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

Для выхода из консоли введите \quit или \q.

Перенаправление команд в консоли

При работе в консоли поддерживается перенаправление ввода-вывода команд (pipe). Таким способом можно сделать как отдельный SQL-запрос, так и запустить файл со списком SQL-команд. Примеры:

Отдельная команда в консоли psql
echo "SELECT * FROM warehouse;" | psql postgres://admin:T0psecret@127.0.0.1:4327
Список команд в административной консоли
cat file.sql | picodata admin ./admin.sock
Содержимое файла file.sql 
INSERT INTO customers VALUES (1, 'customer1');
SELECT name FROM customers limit 10;
DELETE FROM customers WHERE id > 100;

Параметры сессии

Задайте параметры сессии после ?options в строке подключения. При работе с клиентом psql поддерживаются все параметры библиотеки libpq, на которой он основан, а также ряд параметров, специфичных для Picodata:

  • sql_vdbe_opcode_max — ограничение на максимальное количество команд при исполнении локального плана виртуальным движком базы данных (VDBE) на экземпляре кластера
  • sql_motion_row_max — ограничение на максимальное число строк в промежуточной виртуальной таблице, собирающей результаты отдельных локальных запросов.

Более подробно эти параметры описаны в разделе Неблокирующие запросы.

Пример подключения с указанием параметров сессии:

psql postgres://admin:Admin1234@127.0.0.1:5432/picodata?options=sql_vdbe_opcode_max%3D0,sql_motion_row_max%3D100000000

Примечание

Используйте %3D для экранирования знака равенства для параметров типа key=value.

Ограничения протокола PostgreSQL в Picodata

  • Поступающие запросы без изменений передаются в Picodata в текстовом виде, поэтому возможно выполнение только поддерживаемых в Picodata запросов
  • Системные каталоги PostgreSQL реализованы частично
  • При авторизации в пользовательской консоли не поддерживается метод аутентификации chap-sha1
  • По умолчанию подключение по протоколу PostgreSQL использует режим autocommit. Команды BEGIN, COMMIT, ROLLBACK, применяемые для управления интерактивными транзакциями, реализованы только как заглушки
  • Количество одновременно исполняемых запросов ограничено системными параметрами pg_portal_max и pg_statement_max