Редактирование: Модуль работы с БД

==Общие сведения==
Принцип работы: модуль подключается к БД по connectionString из реестра Windows. Большинство операций асинхронные.

Модуль поддерживает работу с СУБД: Access, MS SQL, Oracle и Postgres SQL: 
*для подключения к Access и к Postres используется модуль <code>@chemsoft/odbc</code>; 
*для подключения к MS SQL используется модуль <code>mssql/msnodesqlv8</code>; 
*для подключения к Oracle используется модуль <code>@chemsoft/oracledb</code>.

==Начало работы==
Можно запросить клиент для необходимой СУБД вручную:

<syntaxhighlight lang="javascript">
const {AccessClient, MssqlClient, OracleClient} = require('@chemsoft/db')

const access = new AccessClient(`connection string`)
const mssql = new MssqlClient(`connection string`)
const oracle = new OracleClient(`connection string`)
const oracle = new PostgresClient(`connection string`)
</syntaxhighlight>

Можно в полностью автоматическом режиме получить клиент для нужной СУБД, получая при этом универсальное решение для любой БД:

<syntaxhighlight lang="javascript">
const { getChemicClient } = require('@chemsoft/db')

const client = getChemicClient() 
</syntaxhighlight>

Такой трюк работает, благодаря общему интерфейсу.

===<code>client.connect()</code>===
Производит подключение к БД. Почему не реализовано в конструкторе? Для того, чтобы реализовать ленивый запрос зависимостей, таким образом, подключены будут только используемые в текущий момент пакеты для подключения к БД.

<syntaxhighlight lang="javascript">
async connect(): Promise<void>
</syntaxhighlight>

===<code>client.disconnect()</code>===
Производит отключение от БД в явном виде, таким образом не будет создаваться лишних соединений с БД, на одного пользователя будет только одно подключение. Необходимо вызвать в конце потока исполнения скрипта.

<syntaxhighlight lang="javascript">
async disconnect(): Promise<void>
</syntaxhighlight>

===<code>client.execute()</code>===
Выполняет запрос. В зависимости от типа БД ответ может различаться.

<code>IExecuteResult</code> это интерфейс для максимально общего описания возвращаемых значений. Содержит массив записей и метаданные.

<syntaxhighlight lang="javascript">
interface IExecuteResult {
  records: Array<{ [columnName: string]: any }>;
  meta: {
    rowsAffected?: number;
  }
}
</syntaxhighlight>

Тип получаемых параметров:

<syntaxhighlight lang="javascript">
type QueryParameter = null |
                      number |
                      boolean |
                      string |
                      Date |
                      { type: 'date' | 'time'; value: Date }
</syntaxhighlight>

<code>query: string</code> текст SQL запроса <code>parameters?: QueryParameter[]</code> массив параметров запроса, в тексте запроса можно ставить символ <code>?</code>, на его место будет подставляться правильно отформатированный параметр

<syntaxhighlight lang="javascript">
execute(query: string, parameters?: QueryParameter[]): Promise<IExecuteResult>
</syntaxhighlight>

===<code>client.executeScalar()</code>===
Выполняет запрос и возвращает одно скалярное значение (даже если может быть возвращено несколько колонок). Если возвращено несколько записей и колонок, то возвращает данные из первой записи и первой колонки.

<code>query: string</code> текст SQL запроса <code>parameters?: QueryParameter[]</code> массив параметров запроса, в тексте запроса можно ставить символ <code>?</code>, на его место будет подставляться правильно отформатированный параметр

<syntaxhighlight lang="javascript">
executeScalar(query: string, parameters?: QueryParameter[]): Promise<any>
</syntaxhighlight>

===<code>client.requireFromDatabase()</code>===
Выполняет запрос и срабатывает как <code>require()</code>, но код модуля получает из БД. В основном используется в планировщике.

<syntaxhighlight lang="javascript">
requireFromDatabase(name: string): Promise<any>
</syntaxhighlight>