Skip to content

Commit 2a89b43

Browse files
polRkpolRk
committed
refactor: remove outdated examples and add new YDB query and serverless examples
- Deleted old example files: package.json and query.js. - Added new query example with improved structure and error handling. - Created README.md for the query example detailing usage and best practices. - Introduced a new serverless example demonstrating proper driver management in serverless environments. - Updated package.json files for both examples to reflect new dependencies and scripts. - Removed retry.js example as it was deemed unnecessary. Signed-off-by: Vladislav Polyakov <[email protected]>
1 parent 38ab787 commit 2a89b43

17 files changed

+845
-727
lines changed

‎examples/README.MD

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
# YDB JavaScript SDK Examples
2+
3+
Эта папка содержит примеры использования YDB JavaScript SDK. Каждый пример оформлен как отдельный npm-пакет, который можно легко скопировать и использовать в качестве стартового шаблона для ваших проектов.
4+
5+
## 📦 Доступные примеры
6+
7+
### 📁 **[api/](./api/)**
8+
9+
Пример использования низкоуровневого API для работы с YDB:
10+
11+
- Подключение к базе данных
12+
- Использование Discovery Service
13+
- Проверка соединения с помощью WhoAmI
14+
15+
```bash
16+
cd examples/api
17+
npm install && npm start
18+
```
19+
20+
### 📁 **[query/](./query/)**
21+
22+
Пример выполнения SQL-запросов:
23+
24+
- Создание и выполнение SQL-запросов
25+
- Работа с параметрами запросов
26+
- Создание таблиц и индексов
27+
- Обработка результатов
28+
29+
```bash
30+
cd examples/query
31+
npm install && npm start
32+
```
33+
34+
### 📁 **[sls/](./sls/)**
35+
36+
Примеры для Serverless функций (AWS Lambda, Yandex Cloud Functions, Vercel Functions и подобных):
37+
38+
- Правильная работа с HTTP/2 соединениями в serverless
39+
- Создание драйвера внутри handler функции
40+
- Корректное управление жизненным циклом соединений
41+
42+
```bash
43+
cd examples/sls
44+
npm install && npm start
45+
```
46+
47+
## 🚀 Быстрый старт с DevContainer
48+
49+
Самый простой способ попробовать примеры — использовать DevContainer. Он автоматически настроит окружение с YDB и всеми необходимыми зависимостями.
50+
51+
### Требования
52+
53+
- [Visual Studio Code](https://code.visualstudio.com/)
54+
- [Docker](https://www.docker.com/)
55+
- Расширение [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) для VS Code
56+
57+
### Запуск
58+
59+
1. Откройте проект в VS Code
60+
2. Нажмите `Ctrl+Shift+P` (или `Cmd+Shift+P` на Mac)
61+
3. Выберите **"Dev Containers: Reopen in Container"**
62+
4. Дождитесь окончания сборки контейнера (это может занять несколько минут при первом запуске)
63+
64+
После запуска DevContainer у вас будет:
65+
66+
- ✅ Локальная база данных YDB
67+
- ✅ Все необходимые зависимости
68+
- ✅ Правильно настроенные переменные окружения
69+
70+
## 🔧 Ручная настройка
71+
72+
Если вы предпочитаете запускать примеры локально без DevContainer:
73+
74+
### 1. Установите YDB
75+
76+
```bash
77+
# Создайте директорию для YDB (опционально, для сохранения данных)
78+
mkdir ~/ydbd && cd ~/ydbd
79+
mkdir ydb_data
80+
mkdir ydb_certs
81+
82+
# Запустите YDB в Docker контейнере
83+
docker run -d --rm --name ydb-local -h localhost \
84+
--platform linux/amd64 \
85+
-p 2135:2135 -p 2136:2136 -p 8765:8765 -p 9092:9092 \
86+
-v $(pwd)/ydb_certs:/ydb_certs -v $(pwd)/ydb_data:/ydb_data \
87+
-e GRPC_TLS_PORT=2135 -e GRPC_PORT=2136 -e MON_PORT=8765 \
88+
-e YDB_KAFKA_PROXY_PORT=9092 \
89+
ydbplatform/local-ydb:latest
90+
```
91+
92+
> **Примечание:** Если вам не нужно сохранять данные между перезапусками контейнера, можно запустить YDB без volume:
93+
>
94+
> ```bash
95+
> docker run -d --rm --name ydb-local -h localhost \
96+
> --platform linux/amd64 \
97+
> -p 2135:2135 -p 2136:2136 -p 8765:8765 -p 9092:9092 \
98+
> -e GRPC_TLS_PORT=2135 -e GRPC_PORT=2136 -e MON_PORT=8765 \
99+
> -e YDB_KAFKA_PROXY_PORT=9092 \
100+
> ydbplatform/local-ydb:latest
101+
> ```
102+
103+
### 2. Выберите пример и установите зависимости
104+
105+
```bash
106+
# Перейдите в папку с нужным примером
107+
cd examples/query # или api, retry, sls
108+
109+
# Установите зависимости
110+
npm install
111+
```
112+
113+
### 3. Настройте переменные окружения
114+
115+
```bash
116+
export YDB_CONNECTION_STRING="grpc://localhost:2136/local"
117+
```
118+
119+
## ▶️ Запуск примеров
120+
121+
После настройки окружения вы можете запускать любой пример:
122+
123+
```bash
124+
# Перейдите в папку с примером и запустите
125+
cd examples/api && npm start
126+
127+
# Или с отладочной информацией
128+
cd examples/query && npm run dev
129+
130+
# Serverless пример
131+
cd examples/sls && npm start
132+
```
133+
134+
## 📋 Использование как шаблон
135+
136+
Каждый пример можно легко скопировать и использовать как основу для вашего проекта:
137+
138+
```bash
139+
# Скопируйте нужный пример
140+
cp -r examples/query my-ydb-project
141+
cd my-ydb-project
142+
143+
# Настройте под ваши нужды
144+
npm install
145+
# Отредактируйте index.js
146+
npm start
147+
```
148+
149+
### Отладка
150+
151+
Каждый пример поддерживает отладочный режим через npm script:
152+
153+
```bash
154+
# Перейдите в нужный пример и запустите с отладкой
155+
cd examples/query
156+
npm run dev # эквивалентно DEBUG=ydbjs:* npm start
157+
```
158+
159+
## 📖 Дополнительная информация
160+
161+
- [Официальная документация YDB](https://ydb.tech/docs/)
162+
- [YDB JavaScript SDK документация](https://github.com/ydb-platform/ydb-js-sdk)
163+
- [Примеры использования](https://ydb.tech/docs/en/reference/ydb-sdk/example/)
164+
165+
## 💡 Советы
166+
167+
- Начните с `examples/query/` — это наиболее распространенный сценарий использования
168+
- Используйте `npm run dev` для отладки проблем с подключением
169+
- В DevContainer YDB доступна по адресу `grpc://localhost:2136/local`
170+
- Web UI YDB доступен по адресу http://localhost:8765 (в DevContainer)
171+
- Каждый пример имеет собственный README.md с подробными инструкциями
172+
- Вы можете легко копировать любой пример как стартовый шаблон для своего проекта

‎examples/api.js

Lines changed: 0 additions & 35 deletions
This file was deleted.

‎examples/api/README.md

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# YDB API Example
2+
3+
Простой пример работы с низкоуровневым gRPC API YDB JavaScript SDK.
4+
5+
## Что демонстрирует
6+
7+
### 🔌 **Подключение и аутентификация**
8+
- Создание драйвера с настройками подключения
9+
- Использование StaticCredentialsProvider для аутентификации
10+
11+
### 📡 **Discovery Service**
12+
- `listEndpoints()` - получение списка доступных endpoint'ов
13+
- `whoAmI()` - информация о текущем пользователе
14+
15+
### � **Scheme Service**
16+
- `listDirectory()` - просмотр структуры базы данных
17+
- Сортировка и отображение объектов с пометкой системных таблиц 🔧
18+
19+
## Запуск
20+
21+
```bash
22+
# Запустите пример
23+
npm start
24+
25+
# Или напрямую через node
26+
node index.js
27+
28+
# С отладочной информацией
29+
DEBUG=ydbjs:* node index.js
30+
```
31+
32+
## Переменные окружения
33+
34+
- `YDB_CONNECTION_STRING` - строка подключения к YDB (по умолчанию: `grpc://localhost:2136/local`)
35+
36+
## Пример вывода
37+
38+
```
39+
🔗 Подключение к YDB: grpc://localhost:2136/local
40+
✅ Подключение установлено
41+
42+
📡 Доступные endpoint'ы:
43+
Всего: 1
44+
1. localhost:2136
45+
46+
🆔 Информация о пользователе:
47+
Пользователь: root
48+
Группы: нет
49+
50+
📁 Содержимое базы данных:
51+
Путь: /local
52+
Владелец: root
53+
Объектов: 3
54+
1. .sys (тип: 1) 🔧
55+
2. .sys_health (тип: 1) 🔧
56+
3. test_table (тип: 2)
57+
58+
✅ Готово!
59+
```
60+
61+
## Структура кода
62+
63+
```javascript
64+
// Создание драйвера с аутентификацией
65+
let driver = new Driver(connectionString, {
66+
credentialsProvider: new StaticCredentialsProvider(
67+
{ username: 'root', password: '1234' },
68+
connectionStringForAuth
69+
)
70+
})
71+
72+
// Создание клиента для сервиса
73+
let discovery = driver.createClient(DiscoveryServiceDefinition)
74+
75+
// Вызов метода API
76+
let response = await discovery.listEndpoints({ database: driver.database })
77+
78+
// Распаковка результата
79+
let endpoints = anyUnpack(response.operation?.result, ListEndpointsResultSchema)
80+
```
81+
82+
## Особенности
83+
84+
- **Happy Path подход** - код фокусируется на успешном сценарии
85+
- **Минимум проверок** - убраны избыточные try/catch и assert
86+
- **Читаемый вывод** - структурированная информация с эмодзи
87+
- **Сортировка объектов** - алфавитный порядок для лучшей читаемости
88+
89+
## Использование
90+
91+
Скопируйте этот пример в свой проект:
92+
93+
```bash
94+
cp -r examples/api my-ydb-project
95+
cd my-ydb-project
96+
npm install
97+
npm start
98+
```
99+
100+
## Полезные ссылки
101+
102+
- [YDB JavaScript SDK](https://github.com/ydb-platform/ydb-js-sdk)
103+
- [YDB Documentation](https://ydb.tech/docs/)
104+
- [gRPC API Reference](https://ydb.tech/docs/reference/ydb-sdk/)
105+
- [Protocol Buffers](https://protobuf.dev/)

‎examples/api/index.js

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
/**
2+
* YDB API Example
3+
*
4+
* Демонстрирует основные возможности низкоуровневого gRPC API YDB:
5+
* - Подключение и аутентификация
6+
* - Discovery сервис (endpoint'ы и информация о пользователе)
7+
* - Scheme сервис (просмотр структуры базы данных)
8+
*
9+
* Для запуска:
10+
* 1. Убедитесь, что YDB запущена локально
11+
* 2. Запустите: npm start
12+
*/
13+
14+
import { anyUnpack } from '@bufbuild/protobuf/wkt'
15+
import { DiscoveryServiceDefinition, ListEndpointsResultSchema, WhoAmIResultSchema } from '@ydbjs/api/discovery'
16+
import { ListDirectoryResultSchema, SchemeServiceDefinition } from '@ydbjs/api/scheme'
17+
import { StaticCredentialsProvider } from '@ydbjs/auth/static'
18+
import { Driver } from '@ydbjs/core'
19+
20+
let connectionString = process.env.YDB_CONNECTION_STRING || 'grpc://localhost:2136/local'
21+
22+
let driver = new Driver(connectionString, {
23+
credentialsProvider: new StaticCredentialsProvider({ username: 'root', password: '1234' }, connectionString),
24+
})
25+
26+
console.log('🔗 Подключение к YDB:', connectionString)
27+
28+
await driver.ready()
29+
console.log('✅ Подключение установлено')
30+
31+
let discovery = driver.createClient(DiscoveryServiceDefinition)
32+
33+
// Получаем endpoint'ы
34+
console.log("\n📡 Доступные endpoint'ы:")
35+
{
36+
let response = await discovery.listEndpoints({ database: driver.database })
37+
let endpoints = anyUnpack(response.operation.result, ListEndpointsResultSchema)
38+
39+
console.log(` Всего: ${endpoints?.endpoints?.length || 0}`)
40+
endpoints?.endpoints?.forEach((endpoint, index) => {
41+
let ssl = endpoint?.ssl ? ' (SSL)' : ''
42+
console.log(` ${index + 1}. ${endpoint?.address}:${endpoint?.port}${ssl}`)
43+
})
44+
}
45+
46+
// Получаем информацию о пользователе
47+
console.log('\n🆔 Информация о пользователе:')
48+
{
49+
let response = await discovery.whoAmI({})
50+
let whoAmI = anyUnpack(response.operation.result, WhoAmIResultSchema)
51+
52+
console.log(` Пользователь: ${whoAmI?.user || 'анонимный'}`)
53+
console.log(` Группы: ${whoAmI?.groups?.join(', ') || 'нет'}`)
54+
}
55+
56+
// Просматриваем структуру базы данных
57+
console.log('\n📁 Содержимое базы данных:')
58+
{
59+
let scheme = driver.createClient(SchemeServiceDefinition)
60+
let response = await scheme.listDirectory({ path: driver.database })
61+
let directoryResult = anyUnpack(response.operation.result, ListDirectoryResultSchema)
62+
63+
console.log(` Путь: ${driver.database}`)
64+
console.log(` Владелец: ${directoryResult?.self?.owner || 'неизвестно'}`)
65+
console.log(` Объектов: ${directoryResult?.children?.length || 0}`)
66+
67+
if (directoryResult?.children) {
68+
let sortedChildren = [...directoryResult.children].sort((a, b) => (a?.name || '').localeCompare(b?.name || ''))
69+
70+
sortedChildren.forEach((child, index) => {
71+
let name = child?.name || 'неизвестно'
72+
let isSystem = name.startsWith('.sys') ? ' 🔧' : ''
73+
console.log(` ${index + 1}. ${name} (тип: ${child?.type || 'неизвестно'})${isSystem}`)
74+
})
75+
}
76+
}
77+
78+
driver.close()
79+
console.log('\n✅ Готово!')

0 commit comments

Comments
 (0)