umbot-ydb-adapter 1.0.0

package/dist/YdbAdapter.js

@@ -0,0 +1,457 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.YdbAdapter = void 0;
+const plugins_1 = require("umbot/plugins");
+const umbot_1 = require("umbot");
+const core_1 = require("@ydbjs/core");
+const query_1 = require("@ydbjs/query");
+const anonymous_1 = require("@ydbjs/auth/anonymous");
+const environ_1 = require("@ydbjs/auth/environ");
+const metadata_1 = require("@ydbjs/auth/metadata");
+const static_1 = require("@ydbjs/auth/static");
+const yql_1 = require("./yql");
+const DEFAULT_CONNECT_TIMEOUT = 10000;
+const DEFAULT_QUERY_TIMEOUT = 5000;
+// Создание таблицы или индекса в serverless YDB может идти дольше обычного запроса
+const MIN_DDL_TIMEOUT = 30000;
+const CONNECTION_STRING_ENV = 'YDB_CONNECTION_STRING';
+/**
+ * Адаптер umbot для YDB (Yandex Database).
+ *
+ * Хранит `UsersData`, `ImageTokens`, `SoundTokens` и данные своих моделей. Таблицы
+ * встроенных моделей создаёт сам (`ensureSchema`). Все значения уходят в запрос
+ * параметрами (`$p0`, `$p1`, ...): конкатенации пользовательских данных в YQL нет.
+ *
+ * @example
+ * ```ts
+ * import { Bot } from 'umbot';
+ * import { YdbAdapter } from 'umbot-ydb-adapter';
+ *
+ * // Строка подключения — из YDB_CONNECTION_STRING, авторизация — из окружения
+ * const bot = new Bot().use(new YdbAdapter());
+ * ```
+ */
+class YdbAdapter extends plugins_1.BaseDbAdapter {
+    dbFormat = 'ydb';
+    #driver;
+    #sql;
+    #tables = new Map();
+    /**
+     * @param config Параметры подключения (см. {@link IYdbAdapterConfig}). Без них строка подключения
+     *   берётся из `appConfig.db` или из `YDB_CONNECTION_STRING`.
+     */
+    constructor(config) {
+        // Пустые host/database не мешают: при выборе строки подключения пустое значение пропускается
+        super(config
+            ? { host: '', database: '', ...config, options: config.options }
+            : undefined);
+        // Схема встроенных таблиц нужна и без ensureSchema: по ней выбираются типы и индексы
+        for (const schema of umbot_1.DB_TABLES_SCHEMA) {
+            this.#tables.set(schema.tableName, (0, yql_1.tableInfoFromSchema)(schema));
+        }
+    }
+    /**
+     * Опции адаптера из параметров конструктора или из `appConfig.db.options`.
+     */
+    #getOptions() {
+        const options = this._dbOptions?.options ?? this._appContext.appConfig.db?.options;
+        return (options ?? {});
+    }
+    /**
+     * Строка подключения: `options.connectionString`, затем `host` + `database`,
+     * затем переменная окружения `YDB_CONNECTION_STRING`.
+     */
+    #getConnectionString() {
+        const options = this.#getOptions();
+        if (options.connectionString) {
+            return options.connectionString;
+        }
+        const host = this._dbOptions?.host || this._appContext.appConfig.db?.host;
+        const database = this._dbOptions?.database || this._appContext.appConfig.db?.database;
+        if (host && database) {
+            const base = host.replace(/\/+$/, '');
+            return `${base}/?database=${encodeURIComponent(database)}`;
+        }
+        return process.env[CONNECTION_STRING_ENV] || undefined;
+    }
+    /**
+     * Провайдер авторизации и TLS-опции для драйвера.
+     */
+    #getCredentials(connectionString) {
+        const credentials = this.#getOptions().credentials;
+        if (credentials && typeof credentials === 'object') {
+            return { provider: credentials };
+        }
+        switch (credentials) {
+            case 'metadata':
+                return { provider: new metadata_1.MetadataCredentialsProvider() };
+            case 'anonymous':
+                return { provider: new anonymous_1.AnonymousCredentialsProvider() };
+        }
+        const user = this._dbOptions?.user || this._appContext.appConfig.db?.user;
+        const pass = this._dbOptions?.pass || this._appContext.appConfig.db?.pass;
+        if (credentials !== 'environ' && user && pass) {
+            // Без TLS-контекста провайдер открыл бы незащищённый канал и для grpcs
+            const secureOptions = connectionString.startsWith('grpcs:') ? {} : undefined;
+            return {
+                provider: new static_1.StaticCredentialsProvider({ username: user, password: pass }, connectionString, secureOptions),
+            };
+        }
+        const environ = new environ_1.EnvironCredentialsProvider(connectionString);
+        return { provider: environ, secureOptions: environ.secureOptions };
+    }
+    /**
+     * Подключается к YDB: создаёт драйвер и ждёт discovery не дольше `connectTimeout`.
+     * Повторный вызов закрывает предыдущее подключение.
+     * @returns true при успешном подключении
+     */
+    async connect() {
+        await this.#closeDriver();
+        const connectionString = this.#getConnectionString();
+        if (!connectionString) {
+            this._saveLog(`Не задана строка подключения: укажите host и database, options.connectionString или переменную ${CONNECTION_STRING_ENV}.`);
+            return false;
+        }
+        const options = this.#getOptions();
+        const connectTimeout = options.connectTimeout ?? DEFAULT_CONNECT_TIMEOUT;
+        let driver;
+        try {
+            for (const info of this.#customTables()) {
+                this.#tables.set(info.tableName, info);
+            }
+            const { provider, secureOptions } = this.#getCredentials(connectionString);
+            driver = new core_1.Driver(connectionString, {
+                credentialsProvider: provider,
+                secureOptions,
+                'ydb.sdk.ready_timeout_ms': connectTimeout,
+            });
+            await driver.ready(AbortSignal.timeout(connectTimeout));
+            const sql = options.poolSize === undefined
+                ? (0, query_1.query)(driver)
+                : (0, query_1.query)(driver, { poolOptions: { maxSize: options.poolSize } });
+            this.#driver = driver;
+            this.#sql = sql;
+            const databaseInfo = (this._appContext.database.databaseInfo ??= {});
+            databaseInfo.driver = driver;
+            databaseInfo.sql = sql;
+            this._appContext.log('YDB: подключение установлено');
+            return true;
+        }
+        catch (error) {
+            driver?.close();
+            // Строку подключения не логируем целиком: в query-параметрах бывают служебные данные
+            this._saveLog('Не удалось подключиться к базе данных', error);
+            return false;
+        }
+    }
+    /**
+     * Описания своих таблиц из опции `tables`.
+     * @returns Описания таблиц; бросает YqlBuildError, если описание некорректно
+     */
+    #customTables() {
+        return (this.#getOptions().tables ?? []).map(yql_1.tableInfoFromDefinition);
+    }
+    /**
+     * Создаёт недостающие таблицы, колонки и индексы встроенных моделей и таблиц из опции `tables`.
+     *
+     * Сначала выполняется один запрос-проверка (`SELECT ... LIMIT 0` по всем таблицам и индексам).
+     * Если схема уже готова — на этом всё: в Cloud Functions метод вызывается на каждом холодном
+     * старте, и DDL на каждый старт стоил бы заметного времени.
+     * @param tables Описание таблиц (`DB_TABLES_SCHEMA`)
+     * @returns true, если схема готова
+     */
+    async ensureSchema(tables) {
+        let infos;
+        try {
+            infos = [...tables.map(yql_1.tableInfoFromSchema), ...this.#customTables()];
+        }
+        catch (error) {
+            this._saveLog('ensureSchema: некорректное описание таблицы', error);
+            return false;
+        }
+        for (const info of infos) {
+            this.#tables.set(info.tableName, info);
+        }
+        if (this.#getOptions().ensureSchema === false || !infos.length) {
+            return true;
+        }
+        if (!this.#sql) {
+            this._saveLog('ensureSchema: нет подключения к базе данных');
+            return false;
+        }
+        const check = infos.map(yql_1.buildSchemaCheck).join('\n');
+        if (await this.#tryExecute(check)) {
+            return true;
+        }
+        try {
+            for (const info of infos) {
+                await this.#prepareTable(info);
+            }
+            return true;
+        }
+        catch (error) {
+            this._saveLog('ensureSchema: не удалось подготовить таблицы', error);
+            return false;
+        }
+    }
+    /**
+     * Создаёт таблицу, если её нет, и добавляет недостающие колонки и индексы.
+     */
+    async #prepareTable(info) {
+        await this.#executeDdl((0, yql_1.buildCreateTable)(info));
+        for (const [column, type] of info.columns) {
+            if (!(await this.#tryExecute((0, yql_1.buildColumnCheck)(info.tableName, column)))) {
+                await this.#executeDdl((0, yql_1.buildAddColumn)(info.tableName, column, type));
+            }
+        }
+        for (const index of info.indexes) {
+            if (!(await this.#tryExecute((0, yql_1.buildIndexCheck)(info.tableName, index)))) {
+                await this.#executeDdl((0, yql_1.buildAddIndex)(info.tableName, index));
+            }
+        }
+    }
+    /**
+     * Выполняет DDL-запрос с таймаутом не меньше 30 с и без повторов SDK.
+     */
+    async #executeDdl(text) {
+        const timeout = Math.max(this.#getQueryTimeout(), MIN_DDL_TIMEOUT);
+        await this.#execute({ text, params: {} }, { idempotent: false, timeout });
+    }
+    /**
+     * Таймаут обычного запроса из опций.
+     */
+    #getQueryTimeout() {
+        return this.#getOptions().queryTimeout ?? DEFAULT_QUERY_TIMEOUT;
+    }
+    /**
+     * Выполняет запрос-проверку схемы.
+     * @returns true, если запрос прошёл без ошибок
+     */
+    async #tryExecute(text) {
+        try {
+            await this.#execute({ text, params: {} });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Выполняет запрос с ограничением по времени (вместе с повторами SDK).
+     * @param statement Текст и параметры
+     * @param options `idempotent` — можно ли SDK повторить запрос (по умолчанию да);
+     *   `timeout` — мс, по умолчанию `queryTimeout`; `write` — изменение данных
+     * @returns Наборы строк результата
+     */
+    async #execute(statement, options = {}) {
+        const sql = this.#sql;
+        if (!sql) {
+            throw new Error('Нет подключения к базе данных');
+        }
+        let q = sql(statement.text);
+        for (const name of Object.keys(statement.params)) {
+            q = q.parameter(name, statement.params[name]);
+        }
+        if (options.write) {
+            // YDB меняет таблицы с вторичными индексами только в Serializable-транзакции
+            q = q.isolation('serializableReadWrite');
+        }
+        const timeout = options.timeout ?? this.#getQueryTimeout();
+        return (await q.idempotent(options.idempotent ?? true).timeout(timeout));
+    }
+    /**
+     * Контекст сборки запроса: схема таблицы и правила модели.
+     */
+    #context(data) {
+        return { table: this.#tables.get(data.tableName), rules: data.rules };
+    }
+    /**
+     * Выполняет SELECT.
+     *
+     * Контракт umbot: при `isOne` в `data` — сама запись (не массив); пустая выборка —
+     * `{ status: false }` без `error`; сбой — `{ status: false, error }`.
+     * @param selectData Информация о таблице
+     * @param where Условия выборки
+     * @param isOne Вернуть только одну запись
+     * @returns Результат выборки
+     */
+    async _select(selectData, where, isOne) {
+        try {
+            const statement = (0, yql_1.buildSelect)(selectData.tableName, where, isOne, this.#context(selectData));
+            const [rows = []] = await this.#execute(statement);
+            if (!rows.length) {
+                return { status: false };
+            }
+            const data = rows.map(yql_1.normalizeRow);
+            return { status: true, data: isOne ? data[0] : data };
+        }
+        catch (error) {
+            this._saveLog(`Ошибка SELECT из таблицы "${selectData.tableName}"`, error);
+            return { status: false, error: getErrorMessage(error) };
+        }
+    }
+    /**
+     * Добавляет запись (UPSERT): повторная запись с тем же ключом перезаписывает строку,
+     * поэтому SDK может безопасно повторить запрос после временной ошибки сети.
+     * @param insertData Запрос с данными в `data`
+     * @returns true при успехе
+     */
+    async _insert(insertData) {
+        try {
+            const statement = (0, yql_1.buildUpsert)(insertData.tableName, insertData.data ?? {}, this.#context(insertData));
+            await this.#execute(statement, { write: true });
+            return true;
+        }
+        catch (error) {
+            this._saveLog(`Ошибка записи в таблицу "${insertData.tableName}"`, error);
+            return false;
+        }
+    }
+    /**
+     * Обновляет записи по условию `query`. Без условий запрос не выполняется.
+     * @param updateData Запрос: условия в `query`, новые значения в `data`
+     * @returns true при успехе (в том числе если под условие не попало ни одной записи)
+     */
+    async _update(updateData) {
+        try {
+            const statement = (0, yql_1.buildUpdate)(updateData.tableName, updateData.data ?? {}, updateData.query, this.#context(updateData));
+            if (statement) {
+                await this.#execute(statement, { write: true });
+            }
+            return true;
+        }
+        catch (error) {
+            this._saveLog(`Ошибка UPDATE таблицы "${updateData.tableName}"`, error);
+            return false;
+        }
+    }
+    /**
+     * Удаляет записи по условию `query`. Без условий запрос не выполняется.
+     * @param removeData Запрос: условия в `query`
+     * @returns true при успехе
+     */
+    async _remove(removeData) {
+        try {
+            const statement = (0, yql_1.buildDelete)(removeData.tableName, removeData.query, this.#context(removeData));
+            await this.#execute(statement, { write: true });
+            return true;
+        }
+        catch (error) {
+            this._saveLog(`Ошибка DELETE из таблицы "${removeData.tableName}"`, error);
+            return false;
+        }
+    }
+    /**
+     * Выполняет произвольный запрос: callback получает клиент запросов и драйвер.
+     *
+     * @example
+     * ```ts
+     * const count = await usersData.query(async (sql) => {
+     *     const [[row]] = await sql`SELECT COUNT(*) AS cnt FROM UsersData`;
+     *     return { status: true, data: row };
+     * });
+     * ```
+     * @param callback Функция с запросом
+     * @returns `data` из результата callback или null при ошибке
+     */
+    async _query(callback) {
+        if (!this.#sql || !this.#driver) {
+            this._saveLog('Нет подключения к базе данных');
+            return null;
+        }
+        try {
+            const res = await callback(this.#sql, this.#driver);
+            if (res.status) {
+                return res.data;
+            }
+            this._saveLog(String(res.error));
+            return null;
+        }
+        catch (error) {
+            this._saveLog('Ошибка в query()', error);
+            return null;
+        }
+    }
+    /**
+     * Выполняет произвольный запрос (см. `_query`).
+     * @param callback Функция с запросом
+     * @returns `data` из результата callback или null при ошибке
+     */
+    query(callback) {
+        return this._query(callback);
+    }
+    /**
+     * Экранирует строку для своего запроса: результат можно поставить внутрь `'...'` в YQL.
+     * Адаптер этим методом не пользуется — значения уходят параметрами; для своих запросов
+     * тоже лучше параметры (`` sql`... ${value}` `` в `query()`).
+     * @param str Значение
+     * @returns Экранированная строка
+     */
+    escapeString(str) {
+        return (0, yql_1.escapeYqlString)(str);
+    }
+    /**
+     * Проверяет соединение запросом `SELECT 1`.
+     * @returns true, если база отвечает
+     */
+    async isConnected() {
+        if (!this.#sql) {
+            return false;
+        }
+        try {
+            await this.#execute({ text: 'SELECT 1', params: {} });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Закрывает драйвер и очищает `databaseInfo`. Безопасен к повторному вызову.
+     */
+    async destroy() {
+        await super.destroy();
+        await this.#closeDriver();
+    }
+    /**
+     * Закрывает пул сессий и драйвер, убирает ссылки на них из контекста приложения.
+     */
+    async #closeDriver() {
+        const driver = this.#driver;
+        const sql = this.#sql;
+        this.#driver = undefined;
+        this.#sql = undefined;
+        const databaseInfo = this._appContext?.database?.databaseInfo;
+        if (databaseInfo) {
+            delete databaseInfo.driver;
+            delete databaseInfo.sql;
+        }
+        try {
+            // Пул сессий закрывается до драйвера: иначе сессии на сервере живут до своего таймаута
+            await sql?.[Symbol.asyncDispose]();
+        }
+        catch (error) {
+            this._saveLog('Ошибка при закрытии пула сессий', error);
+        }
+        driver?.close();
+    }
+    /**
+     * Пишет ошибку в лог umbot (секреты маскирует логгер фреймворка).
+     * @param message Текст ошибки
+     * @param error Исключение
+     */
+    _saveLog(message, error) {
+        const text = error === undefined ? message : `${message}: ${getErrorMessage(error)}`;
+        this._appContext?.logError(`YDB: ${text}`, error === undefined ? {} : { error });
+    }
+}
+exports.YdbAdapter = YdbAdapter;
+/**
+ * Текст ошибки для лога и поля `error` результата.
+ */
+function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { YdbAdapter } from './YdbAdapter';
+export type { IYdbAdapterConfig, IYdbDbInfo, IYdbOptions, TYdbCredentials } from './YdbAdapter';
+export { SUPPORTED_OPERATORS, YDB_COLUMN_TYPES } from './yql';
+export type { IYdbTableDefinition, TYdbColumnType } from './yql';

package/dist/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.YDB_COLUMN_TYPES = exports.SUPPORTED_OPERATORS = exports.YdbAdapter = void 0;
+var YdbAdapter_1 = require("./YdbAdapter");
+Object.defineProperty(exports, "YdbAdapter", { enumerable: true, get: function () { return YdbAdapter_1.YdbAdapter; } });
+var yql_1 = require("./yql");
+Object.defineProperty(exports, "SUPPORTED_OPERATORS", { enumerable: true, get: function () { return yql_1.SUPPORTED_OPERATORS; } });
+Object.defineProperty(exports, "YDB_COLUMN_TYPES", { enumerable: true, get: function () { return yql_1.YDB_COLUMN_TYPES; } });

package/dist/yql.d.ts

@@ -0,0 +1,196 @@
+import type { IDbTableSchema, IModelRules, IQueryData } from 'umbot';
+import type { Value } from '@ydbjs/value';
+/**
+ * Типы колонок YDB, которые понимает адаптер.
+ */
+export declare const YDB_COLUMN_TYPES: readonly ["Utf8", "Int64", "Double", "Bool"];
+/**
+ * Тип колонки YDB: в него адаптер приводит значение параметра.
+ */
+export type TYdbColumnType = (typeof YDB_COLUMN_TYPES)[number];
+/**
+ * Вторичный индекс таблицы.
+ */
+export interface IYdbIndexInfo {
+    /** Имя индекса (`idx_<поля>`) */
+    name: string;
+    /** Поля индекса в порядке объявления */
+    fields: readonly string[];
+}
+/**
+ * Что адаптер знает о таблице: ключ, типы колонок и индексы.
+ */
+export interface IYdbTableInfo {
+    /** Имя таблицы */
+    tableName: string;
+    /** Колонки первичного ключа: `primaryKeyName` и `uniqueKeys` из схемы umbot */
+    primaryKey: readonly string[];
+    /** Типы колонок */
+    columns: ReadonlyMap<string, TYdbColumnType>;
+    /** Вторичные индексы (кроме тех, что совпадают с началом первичного ключа) */
+    indexes: readonly IYdbIndexInfo[];
+}
+/**
+ * Готовый к выполнению запрос: текст YQL и параметры `$pN`.
+ */
+export interface IYqlStatement {
+    /** Текст запроса без `DECLARE`: SDK добавляет их сам по типам параметров */
+    text: string;
+    /** Параметры запроса */
+    params: Record<string, Value>;
+}
+/**
+ * Ошибка сборки запроса: некорректное имя, условие или значение.
+ * Адаптер не отправляет такой запрос в базу, а возвращает ошибку вызывающему коду.
+ */
+export declare class YqlBuildError extends Error {
+    constructor(message: string);
+}
+/**
+ * Контекст сборки запроса: схема таблицы (если известна) и правила модели.
+ */
+export interface IYqlContext {
+    /** Схема таблицы, если таблица встроенная или передана в `ensureSchema` */
+    table?: IYdbTableInfo | undefined;
+    /** Правила валидации модели (`IQuery.rules`) */
+    rules?: readonly IModelRules[] | undefined;
+}
+/**
+ * Операторы условий, которые понимает адаптер.
+ */
+export declare const SUPPORTED_OPERATORS: readonly ["$gt", "$gte", "$lt", "$lte", "$ne", "$in", "$nin", "$like", "$null"];
+/**
+ * Описание своей таблицы для опции `tables`: адаптер создаст её вместе со встроенными
+ * и будет искать по её индексам через `VIEW`.
+ *
+ * @example
+ * ```ts
+ * const orders: IYdbTableDefinition = {
+ *     tableName: 'Orders',
+ *     primaryKey: ['orderId'],
+ *     columns: { orderId: 'Utf8', userId: 'Utf8', total: 'Double', paid: 'Bool' },
+ *     indexes: [['userId']],
+ * };
+ * ```
+ */
+export interface IYdbTableDefinition {
+    /** Имя таблицы (можно с директорией: `bots/Orders`) */
+    tableName: string;
+    /** Колонки первичного ключа; каждая должна быть в `columns` */
+    primaryKey: readonly string[];
+    /** Колонки и их типы */
+    columns: Readonly<Record<string, TYdbColumnType>>;
+    /** Наборы колонок, по которым нужен вторичный индекс */
+    indexes?: readonly (readonly string[])[];
+}
+/**
+ * Собирает описание таблицы из схемы umbot (`DB_TABLES_SCHEMA`).
+ * Все поля встроенных таблиц строковые, поэтому колонки получают тип `Utf8`.
+ * @param schema Описание таблицы
+ * @returns Описание таблицы для адаптера
+ */
+export declare function tableInfoFromSchema(schema: IDbTableSchema): IYdbTableInfo;
+/**
+ * Собирает описание своей таблицы из опции `tables` и проверяет его.
+ * @param definition Описание таблицы
+ * @returns Описание таблицы для адаптера
+ */
+export declare function tableInfoFromDefinition(definition: IYdbTableDefinition): IYdbTableInfo;
+/**
+ * Проверяет имя таблицы и возвращает его в обратных кавычках.
+ * @param name Имя таблицы
+ * @returns Имя для подстановки в YQL
+ */
+export declare function quoteTable(name: string): string;
+/**
+ * Проверяет имя колонки (или индекса) и возвращает его в обратных кавычках.
+ * @param name Имя колонки
+ * @returns Имя для подстановки в YQL
+ */
+export declare function quoteColumn(name: string): string;
+/**
+ * Выбирает вторичный индекс для SELECT. YDB не использует индекс без явного `VIEW`,
+ * поэтому поиск по (platform, path) в таблицах токенов без него шёл бы полным перебором.
+ * @returns Имя индекса или undefined, если поиск идёт по первичному ключу или индекса нет
+ */
+export declare function chooseIndex(table: IYdbTableInfo | undefined, where: IQueryData | null): string | undefined;
+/**
+ * Собирает SELECT.
+ * @param tableName Имя таблицы
+ * @param where Условия выборки
+ * @param isOne Нужна только одна запись
+ * @param ctx Контекст запроса
+ * @returns Запрос
+ */
+export declare function buildSelect(tableName: string, where: IQueryData | null, isOne: boolean, ctx: IYqlContext): IYqlStatement;
+/**
+ * Собирает UPSERT одной записи. Поля со значением undefined пропускаются,
+ * null записывается как NULL.
+ * @param tableName Имя таблицы
+ * @param data Данные записи
+ * @param ctx Контекст запроса
+ * @returns Запрос
+ */
+export declare function buildUpsert(tableName: string, data: IQueryData, ctx: IYqlContext): IYqlStatement;
+/**
+ * Собирает UPDATE. Колонки первичного ключа из SET убираются: YDB не меняет ключ
+ * записи, а модель umbot передаёт `uniqueKeys` и в данных, и в условии.
+ * @param tableName Имя таблицы
+ * @param data Новые значения
+ * @param where Условия (обязательны)
+ * @param ctx Контекст запроса
+ * @returns Запрос или null, если менять нечего
+ */
+export declare function buildUpdate(tableName: string, data: IQueryData, where: IQueryData | null, ctx: IYqlContext): IYqlStatement | null;
+/**
+ * Собирает DELETE.
+ * @param tableName Имя таблицы
+ * @param where Условия (обязательны: удаление всей таблицы этим методом запрещено)
+ * @param ctx Контекст запроса
+ * @returns Запрос
+ */
+export declare function buildDelete(tableName: string, where: IQueryData | null, ctx: IYqlContext): IYqlStatement;
+/**
+ * Собирает CREATE TABLE IF NOT EXISTS. Колонки ключа объявляются NOT NULL.
+ * @param table Описание таблицы
+ * @returns Текст запроса
+ */
+export declare function buildCreateTable(table: IYdbTableInfo): string;
+/**
+ * Собирает запрос-проверку: выполняется без ошибок, только если таблица, все её колонки
+ * и индексы уже есть. Данные не читаются (`LIMIT 0`).
+ * @param table Описание таблицы
+ * @returns Текст запроса (несколько SELECT через `;`)
+ */
+export declare function buildSchemaCheck(table: IYdbTableInfo): string;
+/**
+ * Собирает проверку наличия одной колонки.
+ */
+export declare function buildColumnCheck(tableName: string, column: string): string;
+/**
+ * Собирает ALTER TABLE ... ADD COLUMN.
+ */
+export declare function buildAddColumn(tableName: string, column: string, type: TYdbColumnType): string;
+/**
+ * Собирает проверку наличия индекса.
+ */
+export declare function buildIndexCheck(tableName: string, index: IYdbIndexInfo): string;
+/**
+ * Собирает ALTER TABLE ... ADD INDEX.
+ */
+export declare function buildAddIndex(tableName: string, index: IYdbIndexInfo): string;
+/**
+ * Экранирует строку для подстановки внутрь строкового литерала YQL (`'...'` или `"..."`).
+ * Адаптер сам так не делает — все значения уходят параметрами; функция нужна тем,
+ * кто собирает свой запрос через `model.escapeString()`.
+ * @param value Значение
+ * @returns Строка с экранированными обратным слешем, кавычками и управляющими символами
+ */
+export declare function escapeYqlString(value: string | number): string;
+/**
+ * Приводит значение из ответа YDB к виду, который понимают модели umbot:
+ * Int64 приходит как bigint, а JSON.stringify и сравнения с числами на нём ломаются.
+ * @param row Строка результата
+ * @returns Строка с bigint, переведёнными в number (или в строку, если не помещаются)
+ */
+export declare function normalizeRow(row: Record<string, unknown>): Record<string, unknown>;