Getting started

1. Pull the current version of the Docker image:

   docker pull cr.yandex/yc/yandex-docker-local-ydb:latest
   

   Make sure that the pull operation was successful:

   docker image list | grep cr.yandex/yc/yandex-docker-local-ydb
   

   Result:

   cr.yandex/yc/yandex-docker-local-ydb   latest    c37f967f80d8   6 weeks ago     978MB
   

2. Run the Docker container:

   docker run -d --rm --name ydb-local -h localhost \
     -p 2135:2135 -p 2136:2136 -p 8765:8765 \
     -v $(pwd)/ydb_certs:/ydb_certs -v $(pwd)/ydb_data:/ydb_data \
     -e YDB_DEFAULT_LOG_LEVEL=NOTICE \
     -e GRPC_TLS_PORT=2135 -e GRPC_PORT=2136 -e MON_PORT=8765 \
     cr.yandex/yc/yandex-docker-local-ydb:latest
   

   If the container starts successfully, you'll see the container's ID. The container might take a few minutes to initialize. The database will not be available until the initialization completes.

1. Install the YDB CLI:

   • For Linux or macOS:

     curl -sSL https://storage.yandexcloud.net/yandexcloud-ydb/install.sh | bash
     

     Note

     The script will update the PATH variable only if you run it in the bash or zsh command shell. If you run the script in a different shell, add the CLI path to the PATH variable yourself.

   • For Windows:

     @"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://storage.yandexcloud.net/yandexcloud-ydb/install.ps1'))"
     

     Specify whether to add the executable file path to the PATH environment variable:

     Add ydb installation dir to your PATH? [Y/n]
     

     Note

     Some YDB CLI commands may use Unicode characters in their results. If these characters aren't displayed correctly in the Windows console, switch the encoding to UTF-8:

     chcp 65001
     

   To update the environment variables, restart the command shell session.

2. Save the DB connection parameters in the YDB CLI profile:

   ydb config profile create quickstart --endpoint grpc://localhost:2136 --database <path_database>
   

   • path_database: Database path. Specify one of these values:

     • /Root/test: If you used an executable to deploy your cluster.
     • /local: If you deployed your cluster from a Docker image.

3. Check your database connection:

   ydb --profile quickstart scheme ls
   

   Result:

   .sys_health .sys
   

1. Create tables in the database:

   Write the query text to the create-table.sql file:

   CREATE TABLE series (
       series_id Uint64 NOT NULL,
       title Utf8,
       series_info Utf8,
       release_date Date,
       PRIMARY KEY (series_id)
   );
   
   CREATE TABLE seasons (
       series_id Uint64,
       season_id Uint64,
       title Utf8,
       first_aired Date,
       last_aired Date,
       PRIMARY KEY (series_id, season_id)
   );
   
   CREATE TABLE episodes (
       series_id Uint64,
       season_id Uint64,
       episode_id Uint64,
       title Utf8,
       air_date Date,
       PRIMARY KEY (series_id, season_id, episode_id)
   );
   

   Run the following query:

   ydb --profile quickstart yql --file create-table.sql
   

2. Populate the resulting tables with data:

   Write the query text to the upsert.sql file:

   UPSERT INTO series (series_id, title, release_date, series_info)
   VALUES
       (
           1,
           "IT Crowd",
           Date("2006-02-03"),
           "The IT Crowd is a British sitcom produced by Channel 4, written by Graham Linehan, produced by Ash Atalla and starring Chris O'Dowd, Richard Ayoade, Katherine Parkinson, and Matt Berry."),
       (
           2,
           "Silicon Valley",
           Date("2014-04-06"),
           "Silicon Valley is an American comedy television series created by Mike Judge, John Altschuler and Dave Krinsky. The series focuses on five young men who founded a startup company in Silicon Valley."
       )
       ;
   
   UPSERT INTO seasons (series_id, season_id, title, first_aired, last_aired)
   VALUES
       (1, 1, "Season 1", Date("2006-02-03"), Date("2006-03-03")),
       (1, 2, "Season 2", Date("2007-08-24"), Date("2007-09-28")),
       (2, 1, "Season 1", Date("2014-04-06"), Date("2014-06-01")),
       (2, 2, "Season 2", Date("2015-04-12"), Date("2015-06-14"))
   ;
   
   UPSERT INTO episodes (series_id, season_id, episode_id, title, air_date)
   VALUES
       (1, 1, 1, "Yesterday's Jam", Date("2006-02-03")),
       (1, 1, 2, "Calamity Jen", Date("2006-02-03")),
       (2, 1, 1, "Minimum Viable Product", Date("2014-04-06")),
       (2, 1, 2, "The Cap Table", Date("2014-04-13"))
   ;
   

   Run the following query:

   ydb --profile quickstart yql --file upsert.sql
   

3. Select data from the series table:

   Write the query text to the select.sql file:

   SELECT
       series_id,
       title AS series_title,
       release_date
   FROM series;
   

   Run the following query:

   ydb --profile quickstart yql --file select.sql
   

   Result:

   ┌───────────┬──────────────────┬──────────────┐
   | series_id | series_title     | release_date |
   ├───────────┼──────────────────┼──────────────┤
   | 1         | "IT Crowd"       | "2006-02-03" |
   ├───────────┼──────────────────┼──────────────┤
   | 2         | "Silicon Valley" | "2014-04-06" |
   └───────────┴──────────────────┴──────────────┘
   

4. Delete data from the episodes table.

   Write the query text to the delete.sql file:

   DELETE
   FROM episodes
   WHERE
       series_id = 2
       AND season_id = 1
       AND episode_id = 2
   ;
   

   Run the following query:

   ydb --profile quickstart yql --file delete.sql
   

   View the episodes table:

   ydb --profile quickstart yql --script "SELECT * FROM episodes;"
   

   Result:

   ┌──────────────┬────────────┬───────────┬───────────┬──────────────────────────┐
   | air_date     | episode_id | season_id | series_id | title                    |
   ├──────────────┼────────────┼───────────┼───────────┼──────────────────────────┤
   | "2006-02-03" | 1          | 1         | 1         | "Yesterday's Jam"        |
   ├──────────────┼────────────┼───────────┼───────────┼──────────────────────────┤
   | "2006-02-03" | 2          | 1         | 1         | "Calamity Jen"           |
   ├──────────────┼────────────┼───────────┼───────────┼──────────────────────────┤
   | "2014-04-06" | 1          | 1         | 2         | "Minimum Viable Product" |
   └──────────────┴────────────┴───────────┴───────────┴──────────────────────────┘
   

   You've deleted The Cap Table series row from the table.

To stop the Docker container with the cluster, run this command:

docker kill ydb-local