# 6. Хранение состояния в Key-Value

Вы создадите бакет Key-Value, запишете значение, прочитаете его, а затем включите наблюдение за бакетом во втором терминале, чтобы видеть изменения сразу после их появления. В результате у вас будет небольшое хранилище актуального состояния, доступное для чтения, записи и наблюдения.

## Что понадобится

* Установленные `nats-server` и CLI `nats` (см. [1. Привет, NATS](/tutorials/hello-nats.md)).
* Бакет Key-Value работает поверх потока JetStream, поэтому на шаге 1 вы запустите сервер с включённым JetStream.

## Шаг 1: запустите сервер с JetStream

Бакет Key-Value хранится в JetStream, поэтому запустите сервер с флагом `-js`.

```
nats-server -js
```

В журнале запуска должна появиться строка, подтверждающая включение JetStream:

```
[INF] Starting JetStream

[INF] Server is ready
```

Оставьте сервер работающим и откройте новый терминал для следующих шагов.

## Шаг 2: создайте бакет

Создайте бакет `profiles`. В нём будут храниться ваши значения.

#### CLI

```
#!/bin/bash

# Создайте хранилище ключей и значений profiles. В нём будут храниться

# ваши значения.



nats kv add profiles



# Появится подтверждение с именем хранилища и его настройками:

#

#   Information for Key-Value Store Bucket profiles created 2026-06-09 10:13:41

#

#   Configuration:

#

#              Bucket Name: profiles

#             History Kept: 1

#                      ...

#       Backing Store Kind: JetStream
```

#### C

```
// Create a Key-Value bucket called profiles. A bucket is where your

// values live.

kvConfig cfg;



kvConfig_Init(&cfg);

cfg.Bucket = "profiles";



s = js_CreateKeyValue(&kv, js, &cfg);

if (s == NATS_OK)

    printf("Created bucket %s\n", kvStore_Bucket(kv));
```

Должно появиться подтверждение с конфигурацией бакета:

```
Information for Key-Value Store Bucket profiles created 2026-06-09 10:13:41



Configuration:



           Bucket Name: profiles

          History Kept: 1

                   ...

    Backing Store Kind: JetStream
```

## Шаг 3: запишите и прочитайте значение

Сохраните значение по ключу, затем прочитайте его. Ключ — `sue.color`, значение — `blue`.

#### CLI

```
#!/bin/bash

# Запишите значение: ключ sue.color, значение blue.



nats kv put profiles sue.color blue



# Будут выведены записанное значение и его ревизия:

#

#   blue



# Получите значение по ключу.



nats kv get profiles sue.color



# Будет выведена полная запись, включая значение:

#

#   profiles > sue.color revision: 1 created @ ...

#

#   blue
```

#### C

```
// Put a value: the key is sue.color, the value is blue. The bucket

// assigns the write a revision; the first write lands at 1.

uint64_t rev   = 0;

kvEntry  *e    = NULL;



s = kvStore_PutString(&rev, kv, "sue.color", "blue");

if (s == NATS_OK)

    printf("stored sue.color at revision %llu\n",

           (unsigned long long) rev);



// Get the value back out by its key. A get returns the full entry:

// the value together with its revision.

if (s == NATS_OK)

    s = kvStore_Get(&e, kv, "sue.color");

if (s == NATS_OK)

{

    printf("sue.color revision: %llu value: %.*s\n",

           (unsigned long long) kvEntry_Revision(e),

           kvEntry_ValueLen(e), (const char*) kvEntry_Value(e));

    kvEntry_Destroy(e);

}
```

Операция записи выводит записанное значение, а чтение возвращает полную запись:

```
blue

profiles > sue.color revision: 1 created @ ...



blue
```

Теперь у вас есть одно сохранённое и проверенное значение.

## Шаг 4: наблюдайте за бакетом из второго терминала

Наблюдение (watch) передаёт каждое изменение бакета по мере его появления. Откройте **второй терминал** и начните наблюдать за `profiles`.

#### CLI

```
#!/bin/bash

# Наблюдайте за всем хранилищем profiles. При запуске выводится текущее значение

# каждого ключа, затем команда ожидает изменения и выводит их до остановки

# сочетанием Ctrl-C. Запустите её в отдельном терминале.



nats kv watch profiles



# Сначала появится текущее значение, затем команда будет ожидать изменений:

#

#   [2026-06-09 10:14:22] PUT profiles > sue.color: blue
```

#### C

```
// Watch the whole profiles bucket. The watch first replays the

// current value of every key, then delivers each change live the

// moment it lands.

kvEntry *e = NULL;



s = kvStore_WatchAll(&w, kv, NULL);

while (s == NATS_OK)

{

    s = kvWatcher_Next(&e, w, 60000);

    if (s != NATS_OK)

        break;

    // A NULL entry marks the end of the initial replay. Skip it

    // and keep reading: everything after it is a live change.

    if (e == NULL)

        continue;

    printf("PUT %s: %.*s\n", kvEntry_Key(e),

           kvEntry_ValueLen(e), (const char*) kvEntry_Value(e));

    kvEntry_Destroy(e);

    e = NULL;

}
```

Сначала наблюдатель выводит текущее значение, затем ожидает:

```
[2026-06-09 10:14:22] PUT profiles > sue.color: blue
```

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

**Движение сообщений — Наблюдение KV: снимок и текущие изменения (анимация):** Наблюдение KV: снимок, затем текущие изменения. warehouse-dashboard открывает watch на KV\_INVENTORY, создающий временного упорядоченного потребителя базового потока. Сначала воспроизводятся текущие значения всех ключей; nil завершения начальных данных сообщает, что наблюдатель догнал поток. Далее каждый новый put передаётся в реальном времени.

* warehouse-dashboard → KV\_INVENTORY
* KV\_INVENTORY → упорядоченный потребитель
* упорядоченный потребитель → warehouse-dashboard

## Шаг 5: обновите значение и проверьте уведомление

Вернитесь в **первый терминал** и запишите новое значение по тому же ключу.

#### CLI

```
#!/bin/bash

# Запишите новое значение того же ключа. Обычная операция put перезаписывает

# предыдущее значение.



nats kv put profiles sue.color green



# Будет выведено новое значение:

#

#   green

#

# В терминале с наблюдателем новая строка появится сразу после

# записи:

#

#   [2026-06-09 10:15:03] PUT profiles > sue.color: green
```

#### C

```
// Put a new value for the same key. This is a normal put: it

// overwrites whatever was there, and the watcher in the other

// terminal sees the change the instant it lands.

uint64_t rev = 0;



s = kvStore_PutString(&rev, kv, "sue.color", "green");

if (s == NATS_OK)

    printf("stored sue.color at revision %llu\n",

           (unsigned long long) rev);
```

Операция записи возвращает новое значение:

```
green
```

Переключитесь в терминал наблюдения. Новая строка появляется сразу после изменения:

```
[2026-06-09 10:15:03] PUT profiles > sue.color: green
```

Когда закончите, остановите наблюдение с помощью `Ctrl-C`.

## Что вы создали

У вас есть бакет Key-Value с актуальным состоянием: вы записали и прочитали значение, а наблюдатель во втором терминале получал каждое изменение сразу после его появления.

## Дальше

* Итоговая работа: [7. Создание приложения](/tutorials/build-an-app.md) — объедините публикацию и подписку, запрос и ответ и поток в одной программе.
* Узнайте, как это работает: [углублённый курс Key-Value](/learn/key-value/.md) объясняет бакеты, ревизии, наблюдение и лежащий в основе поток.
