YDB CLI - Getting started

• Prerequisites
• Check the connection
• Creating a connection profile
• Next step

• Database name

You may also need a token or login/password if the database requires . 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 .

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

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

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

To test connection, you can use the command for 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 .
• A database has just been created and contains no objects.

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

The command execution result on the created empty 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:

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.

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

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

If you get the error, that means you neglected to create a profile in the .

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 .