YDB CLI - Начало работы

Предварительные требования

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

Также вам может потребоваться токен или логин/пароль, если база данных требует аутентификации. Для успешного исполнения сценария ниже вам нужно выбрать вариант их сохранения в переменной окружения.

Установка CLI

Установите YDB CLI, как описано в статье Установка YDB CLI.

Проверьте успешность установки YDB CLI запуском с параметром --help:

ydb --help

В ответ должно быть выведено приветственное сообщение, краткое описание синтаксиса, и перечень доступных команд:

YDB client

Usage: ydb [options...] <subcommand>

Subcommands:
ydb
├─ config                   Manage YDB CLI configuration
│  └─ profile               Manage configuration profiles
│     ├─ activate           Activate specified configuration profile (aliases: set)
...

Все возможности работы со встроенной справкой YDB CLI описаны в статье Встроенная справка справочника по YDB CLI.

Проверьте успешность соединения

Для проверки успешности соединения можно использовать команду получения перечня объектов в базе данных scheme ls:

ydb -e <endpoint> -d <database> scheme ls

При успешном выполнении команды в ответ будет выведен перечень объектов в базе данных. Если вы еще не создавали ничего в БД, то вывод будет содержать только системные каталоги .sys и .sys_health, в которых находятся диагностические представления YDB.

Например, если:

  • Эндпоинт: grpc://ydb.example.com:2136;
  • Имя базы данных: /john/db1;
  • База данных не требует аутентификации, или задана нужная переменная окружения, как описано здесь;
  • База данных только что создана и не содержит объектов;

то команда будет выглядеть следующим образом:

ydb -e grpc://ydb.example.com:2136 -d /john/db1 scheme ls

Результат выполнения на только что созданной пустой базе данных:

.sys_health .sys

Соединение с локальной БД

Если вы развернули локальную YDB по сценарию самостоятельного развертывания в Docker с предложенной конфигурацией, то соединение с ней можно проверить командой:

ydb -e grpc://localhost:2136 -d /local scheme ls

Создание профиля соединения

Чтобы не писать параметры соединения каждый раз при вызове YDB CLI, воспользуйтесь профилем. Создание предложенного ниже профиля позволит вам также копировать дальнейшие команды через буфер обмена без их редактирования, вне зависимости от того, на какой базе данных вы проходите сценарий начала работы.

Создайте профиль db1 следующей командой:

ydb config profile create db1 -e <endpoint> -d <database>

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

ydb config profile create db1 -e grpc://localhost:2136 -d /local

Проверьте работоспособность профиля командой scheme ls:

ydb -p db1 scheme ls

Исполнение YQL скрипта

Команда YDB CLI yql позволяет выполнить любую команду (как DDL, так и DML) на языке YQL - диалекте SQL, поддерживаемом YDB:

ydb -p <profile_name> yql -s <yql_request>

Например:

  • Создание таблицы:

    ydb -p db1 yql -s "create table t1( id uint64, primary key(id))"

  • Добавление записи:

    ydb -p db1 yql -s "insert into t1(id) values (1)"

  • Выборка данных:

    ydb -p db1 yql -s "select * from t1"

Если вы получаете ошибку Profile db1 does not exist, значит вы не создали его на предыдущем шаге.

Специализированные команды CLI

Исполнение команд через ydb yql является хорошим простым способом начать работу. Однако, YQL-интерфейс поддерживает неполный набор возможных функций, доступных на YDB API, а также работает не самым эффективным образом из-за своей универсальности.

YDB CLI поддерживает отдельные команды с полным набором опций для всех существующих YDB API. Описание полного перечня команд находится в справочнике по YDB CLI.

Продолжение знакомства с YDB

Перейдите к статье YQL - Начало работы для продолжения знакомства с YDB.

В этой статье: