@dieugene/ydb-serverless

Модуль для работы с Yandex Database (YDB) в serverless режиме. Предоставляет удобный интерфейс для выполнения запросов, массовых операций и управления данными в YDB.

Возможности

• 🔄 Выполнение SELECT запросов с возвратом результатов
• 💾 Выполнение DML операций (INSERT, UPDATE, DELETE, UPSERT)
• 📦 Массовые операции (bulk upsert)
• 🏗️ Структурированные операции через JSON
• 🔍 Получение записей по списку ID
• 📊 Автоматическое логирование запросов и потребления RU
• 🔧 Автоматическая типизация данных для YDB
• 🔄 Автоматический retry при ошибках

Установка

npm install @dieugene/ydb-serverless

Зависимости

Модуль использует следующие зависимости:

• @yandex-cloud/nodejs-sdk: ^2.9.0
• ydb-sdk: ^5.11.0

Переменные окружения

YDB_ADDRESS=et1...b5/database_name          # Адрес YDB базы данных
YDB_LOG=YDB                                  # Включить логирование (опционально)
YDB_LOG=QUERY_MONITORING_OFF                 # Отключить мониторинг запросов (опционально)
ADMIN_YDB_ADDRESS=et1...admin/admin_db       # Административная БД для логирования (опционально)
FUNCTION_NAME=my_function                    # Имя функции для логирования (опционально)

Переменная YDB_LOG может содержать несколько значений, разделенных любым разделителем

Использование

Инициализация

const { init } = require('@dieugene/ydb-serverless');

// Инициализация с переменной окружения YDB_ADDRESS
const ydb = init();

// Или инициализация с конкретным адресом базы
const ydb = init('et1...b5/my_database');

SELECT запросы

// Простой SELECT запрос
const users = await ydb.execute(`
    SELECT id, name, email 
    FROM users 
    WHERE status = 'active'
`);

// SELECT с параметрами
const user = await ydb.execute(`
    DECLARE $user_id AS Uint64;
    SELECT * FROM users WHERE id = $user_id
`, { 
    $user_id: 123 
});

DML операции

// INSERT/UPSERT
await ydb.apply(`
    DECLARE $name AS Utf8;
    DECLARE $email AS Utf8;
    
    UPSERT INTO users (name, email, created_at)
    VALUES ($name, $email, CurrentUtcDatetime())
`, {
    $name: 'John Doe',
    $email: '[email protected]'
});

// UPDATE
await ydb.apply(`
    DECLARE $user_id AS Uint64;
    DECLARE $status AS Utf8;
    
    UPDATE users SET status = $status 
    WHERE id = $user_id
`, {
    $user_id: 123,
    $status: 'inactive'
});

Массовые операции

// Bulk upsert для простых данных
const users = [
    { id: 1, name: 'Alice', age: 25 },
    { id: 2, name: 'Bob', age: 30 },
    { id: 3, name: 'Charlie', age: 35 }
];

await ydb.upsert('users', users);

Структурированные операции

// Upsert через JSON с описанием типов
const orders = [
    { 
        id: 1, 
        user_id: 123, 
        amount: 99.99, 
        created_at: { ydb_data_type: 'datetime', value: new Date() },
        metadata: { product: 'laptop', quantity: 1 }
    }
];

const description = {
    id: { not_null: true, type: 'Uint64' },
    amount: { type: 'Double' }
};

await ydb.upsert_struct('orders', orders, description);

Получение записей по списку ID

// Получить пользователей по списку ID
const userIds = ['user1', 'user2', 'user3'];
const users = await ydb.get_by_id_list('users', userIds, 'user_id');

// По умолчанию ищет по полю 'id'
const posts = await ydb.get_by_id_list('posts', [1, 2, 3]);

Работа с датами

// Использование специального типа для дат
const event = {
    id: 1,
    name: 'Conference',
    event_date: { 
        ydb_data_type: 'datetime', 
        value: new Date('2024-06-15T10:00:00Z') 
    }
};

await ydb.upsert_struct('events', [event]);

Хелперы

// Генерация уникального ID
const idHelper = ydb.helpers.uint64_id_definition('users');

await ydb.apply(`
    ${idHelper.declaration}
    ${idHelper.assignment}
    
    UPSERT INTO users (id, name, created_at)
    SELECT $id, $name, ${ydb.helpers.date_time}
`, {
    $name: 'New User'
});

API Reference

init(database)

Инициализирует модуль для работы с указанной базой данных.

execute(query, params, tryAgain, make_log)

Выполняет SELECT запрос и возвращает результат.

apply(query, params, tryAgain, make_log)

Выполняет DML запрос (INSERT, UPDATE, DELETE, UPSERT).

upsert(table_name, values)

Выполняет массовую вставку/обновление записей.

upsert_struct(table_name, values, description)

Выполняет UPSERT через JSON с возможностью описания типов полей.

get_by_id_list(table_name, id_list, id_field_name)

Получает записи по списку ID.

destroy()

Закрывает соединение с базой данных.

Особенности

• Автоматическая типизация: Модуль автоматически определяет типы YDB на основе JavaScript значений
• Retry механизм: При ошибках выполняется повторная попытка
• Логирование: Автоматическое логирование запросов и потребления RU
• Поддержка массивов: Специальная обработка массивов с параметром unfold_arrays
• JSON поддержка: Работа со сложными объектами через JSON типы

Примеры типов данных

// Строки
$param: 'Hello World'

// Числа  
$param: 123

// Булевы значения
$param: true

// Даты
$param: { ydb_data_type: 'datetime', value: new Date() }

// JSON объекты
$param: { key: 'value', nested: { data: 123 } }

// Массивы (с unfold_arrays: true)
$param_list: ['item1', 'item2', 'item3']

Автор

Eugene Ditkovsky

Ссылки

• GitHub Repository
• NPM Package
• Issues

Ключевые слова

YDB, Yandex, Cloud, Database, Serverless

Лицензия

ISC