YDB CLI - Getting started
To run commands via the CLI, you will need database connection settings you can get when creating a database:
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
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,
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_health system directories with diagnostic views of YDB.
For example, if:
- Database name:
- 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:
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 -e <endpoint> -d <database>
Use the values checked at the previous step as parameters. For example, to create a connection profile to a local YDB database created using the self-hosted deployment scenario in Docker, run the following command:
ydb config profile create db1 -e grpc://localhost:2136 -d /local
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>
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)"
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.
Go to YQL - Getting started.