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

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

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

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

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

Установка psql

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

См. также:

Быстрый старт

Для быстрого начала работы с Picodata выполните следующие шаги:

  1. Запустите инстанс Picodata (см. Запуск)

  2. В другом терминале подключитесь к консоли администратора:

    picodata admin ./admin.sock

  3. Задайте пароль администратора и создайте пользователя:

    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";

  4. Подключитесь через psql:

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

Примечание

Новые пользователи по умолчанию создаются с методом аутентификации md5, который совместим с протоколом PostgreSQL. Метод chap-sha1 не поддерживается при подключении через psql — используйте md5 или scram-sha256.

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

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

Консоль администратора предоставляет доступ к учетной записи Администратора СУБД (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';

Требования к паролю

Пароль должен соответствовать следующим требованиям:

  • не менее 8 символов
  • минимум одна заглавная буква
  • минимум одна строчная буква
  • минимум одна цифра

См. также: Требования к паролю

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

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.pgproto.listen).

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

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

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

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

Пример подключения с явным запросом безопасного режима:

psql postgres://admin:T0psecret@127.0.0.1:4327?sslmode=require

См. также:

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

Примечание

Подключение к по протоколу PostgreSQL доступно только для пользователей, использующих методы аутентификации md5, scram-sha256 или 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;

Для перенаправления также удобно использовать команду picodata admin, которая поддерживает дополнительные параметры форматирования для вывода.

Пример:

Вывод результата в виде таплов
echo "SELECT * FROM warehouse;"  | picodata admin ./admin.sock --tuples-only
1   bricks  heavy
3   blocks  heavy
4   piles   light
2   bars    light
5   panels  light

См. также:

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

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

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

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

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

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

Примечание

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

Конвейерный режим

В конвейерном режиме (pipeline mode) клиент отправляет запросы, не дожидаясь ответов на предыдущие. Picodata выполняет запросы по одному в порядке получения и отправляет ответы вместе. Это сокращает число сетевых обменов, поэтому режим полезен, когда клиент выполняет много коротких запросов подряд, например, вставляет строки по одной.

Режим работает поверх расширенного протокола запросов (extended query). Его поддерживают библиотека libpq и утилита pgbench начиная с версии 14, psql начиная с версии 18, а также драйверы PostgreSQL, например, psycopg.

Клиент делит конвейер на сегменты точками синхронизации — сообщениями Sync (PQpipelineSync в libpq, \syncpipeline и \endpipeline в psql). В точке синхронизации Picodata отправляет накопленные ответы и закрывает порталы. Если запрос завершился ошибкой, Picodata возвращает ошибку и пропускает остальные запросы сегмента до ближайшей точки синхронизации. Следующий сегмент выполняется как обычно.

Внимание!

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

Пример в psql:

CREATE TABLE t (id INT PRIMARY KEY);
\startpipeline
INSERT INTO t VALUES (1);
INSERT INTO t VALUES (1);
INSERT INTO t VALUES (2);
\syncpipeline
INSERT INTO t VALUES (3);
\endpipeline
SELECT * FROM t ORDER BY id;

Вторая вставка завершается ошибкой Duplicate key, поэтому третья пропускается. Первая вставка остается в таблице, а следующий сегмент выполняется:

 id
----
  1
  3
(2 rows)

Именованные порталы, созданные в сегменте, существуют до точки синхронизации, а подготовленные запросы — до их закрытия или конца сессии. Их число ограничено параметрами pg_portal_max и pg_statement_max.

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

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