YDB CLI - Getting started

• Prerequisites
• Installing the CLI
• Check the connection
  • Connecting to a local database
• Creating a connection profile
• Executing an YQL script
• Specialized CLI commands
• Next step

Prerequisites

To run commands via the CLI, you will need database connection settings you can get when creating a database:

• Endpoint
• Database name

You may also need a token or login/password if the database requires authentication. To execute the below scenario, you need to select an option for saving them in an environment variable.

Installing the CLI

Install the YDB CLI as described in Installing the YDB CLI.

To check that the YDB CLI has been installed, run it with --help:

ydb --help

The response includes a welcome message, a brief description of the syntax, and a list of available commands:

YDB client
Usage: ydb [options...] <subcommand>
Subcommands:
ydb
├─ config                   Manage YDB CLI configuration
│  └─ profile               Manage configuration profiles
│     ├─ activate           Activate specified configuration profile (aliases: set)
...

All the features of the YDB CLI built-in help are described in Built-in help of the YDB CLI reference.

Check the connection

To test connection, you can use the command for listing objects in the database, scheme ls:

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

If the command is successful, a list of objects in the database is shown in response. If you haven’t created anything in the database yet, the output will only contain the .sys and .sys_health system directories with diagnostic views of YDB.

For example, if:

• Endpoint: grpc://ydb.example.com:2136.
• Database name: /john/db1.
• The database doesn’t require authentication, or the proper environment variable has been set, as described here.
• A database has just been created and contains no objects.

the command will look like this:

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

The command execution result on the created empty database:

.sys_health .sys

Connecting to a local database

If you deployed a local YDB using a scenario for self-hosted deployment in Docker with the suggested configuration, you can check a YDB connection using the command:

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

Creating a connection profile

To avoid specifying connection parameters every time you call the YDB CLI, use the profile. Creating the profile described below will also let you copy subsequent commands through the clipboard without editing them regardless of which database you’re using to complete the “Getting started” scenario.

Create the profile db1 using the following command:

ydb config profile create db1

You will be interactively prompted for connection parameters to be linked with the profile. Use for them the values verified in the previous step.

Check that the profile is OK with the scheme ls command:

ydb -p db1 scheme ls

Executing an YQL script

The YDB CLI yql command lets you execute any command (both DDL and DML) in YQL, an SQL dialect supported by YDB:

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

For example:

• Creating a table:

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

  

• Adding a record:

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

  

• Data selects:

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

  

If you get the Profile db1 does not exist error, that means you neglected to create a profile in the previous step.

Specialized CLI commands

Executing commands via ydb yql is a nice and easy way to get started. However, the YQL interface supports a part of the function set provided by the YDB API, and has to sacrifice efficiency for universality.

The YDB CLI supports individual commands with complete sets of options for any existing YDB API. For a full list of commands, see the YDB CLI reference.

Next step

Go to YQL - Getting started to proceed with the ‘Getting started’ scenario.