new DatabaseSync(path[, options])

• path <string> | <Buffer> | <URL> Путь к базе данных. Базу данных SQLite можно хранить в файле или полностью в памяти. Для работы с базой данных в файле укажите путь к файлу. Для работы с базой данных в памяти укажите специальное имя ':memory:'.
• options <Object> Параметры конфигурации подключения к базе данных. Поддерживаются следующие параметры:
  • open <boolean> Если true, база данных открывается конструктором. Если это значение равно false, базу данных необходимо открыть с помощью метода open(). По умолчанию: true.
  • readOnly <boolean> Если true, база данных открывается в режиме только для чтения. Если база данных не существует, открыть ее не удастся. По умолчанию: false.
  • enableForeignKeyConstraints <boolean> Если true, включаются ограничения внешних ключей. Это рекомендуется, однако их можно отключить для совместимости с устаревшими схемами баз данных. Применение ограничений внешних ключей можно включать и отключать после открытия базы данных с помощью PRAGMA foreign_keys. По умолчанию: true.
  • enableDoubleQuotedStringLiterals <boolean> Если true, SQLite принимает строковые литералы в двойных кавычках. Это не рекомендуется, однако такую возможность можно включить для совместимости с устаревшими схемами баз данных. По умолчанию: false.
  • allowExtension <boolean> Если true, включаются функция SQL loadExtension и метод loadExtension(). Позже можно вызвать enableLoadExtension(false), чтобы отключить эту функцию. По умолчанию: false.
  • timeout <number> Время ожидания блокировки в миллисекундах. Это максимальное время, в течение которого SQLite будет ждать снятия блокировки базы данных, прежде чем вернуть ошибку. По умолчанию: 0.
  • readBigInts <boolean> Если true, целочисленные поля считываются как значения JavaScript типа BigInt. Если false, целочисленные поля считываются как числа JavaScript. По умолчанию: false.
  • returnArrays <boolean> Если true, результаты запросов возвращаются в виде массивов, а не объектов. По умолчанию: false.
  • allowBareNamedParameters <boolean> Если true, разрешается привязывать именованные параметры без начального символа (например, foo вместо :foo). По умолчанию: true.
  • allowUnknownNamedParameters <boolean> Если true, неизвестные именованные параметры при привязке игнорируются. Если false, для неизвестных именованных параметров возникает исключение. По умолчанию: false.

Создает новый экземпляр DatabaseSync.

database.aggregate(name, options)

Регистрирует в базе данных SQLite новую агрегатную функцию. Этот метод является оберткой для sqlite3_create_window_function().

• name <string> Имя создаваемой функции SQLite.
• options <Object> Параметры конфигурации функции.
  • deterministic <boolean> Если true, для создаваемой функции устанавливается флаг SQLITE_DETERMINISTIC. По умолчанию: false.
  • directOnly <boolean> Если true, для создаваемой функции устанавливается флаг SQLITE_DIRECTONLY. По умолчанию: false.
  • useBigIntArguments <boolean> Если true, целочисленные аргументы методов options.step и options.inverse преобразуются в BigInt. Если false, целочисленные аргументы передаются как числа JavaScript. По умолчанию: false.
  • varargs <boolean> Если true, методы options.step и options.inverse можно вызывать с любым количеством аргументов (от нуля до SQLITE_MAX_FUNCTION_ARG). Если false, методы inverse и step необходимо вызывать ровно с length аргументами. По умолчанию: false.
  • start <number> | <string> | <null> | <Array> | <Object> | <Function> Начальное значение агрегатной функции. Это значение используется при инициализации агрегатной функции. Если передана функция <Function>, ее возвращаемое значение будет начальным значением.
  • step <Function> Функция, вызываемая для каждой строки агрегата. Функция получает текущее состояние и значение строки. Она должна возвращать новое состояние.
  • result <Function> Функция, вызываемая для получения результата агрегирования. Функция получает конечное состояние и должна вернуть результат агрегирования.
  • inverse <Function> Если эта функция задана, метод aggregate будет работать как оконная функция. Функция получает текущее состояние и значение удаленной строки. Она должна возвращать новое состояние.

При использовании в качестве оконной функции функция result будет вызываться несколько раз.

const { DatabaseSync } = require('node:sqlite');

const db = new DatabaseSync(':memory:');
db.exec(`
  CREATE TABLE t3(x, y);
  INSERT INTO t3 VALUES ('a', 4),
                        ('b', 5),
                        ('c', 3),
                        ('d', 8),
                        ('e', 1);
`);

db.aggregate('sumint', {
  start: 0,
  step: (acc, value) => acc + value,
});

db.prepare('SELECT sumint(y) as total FROM t3').get(); // { total: 21 }

import { DatabaseSync } from 'node:sqlite';

const db = new DatabaseSync(':memory:');
db.exec(`
  CREATE TABLE t3(x, y);
  INSERT INTO t3 VALUES ('a', 4),
                        ('b', 5),
                        ('c', 3),
                        ('d', 8),
                        ('e', 1);
`);

db.aggregate('sumint', {
  start: 0,
  step: (acc, value) => acc + value,
});

db.prepare('SELECT sumint(y) as total FROM t3').get(); // { total: 21 }

database.close()

Закрывает подключение к базе данных. Если база данных не открыта, возникает исключение. Этот метод является оберткой для sqlite3_close_v2().

database.loadExtension(path)

• path <string> Путь к загружаемой разделяемой библиотеке.

Загружает разделяемую библиотеку в подключение к базе данных. Этот метод является оберткой для sqlite3_load_extension(). При создании экземпляра DatabaseSync необходимо включить параметр allowExtension.

database.enableLoadExtension(allow)

• allow <boolean> Разрешить ли загрузку расширений.

Включает или отключает функцию SQL loadExtension и метод loadExtension(). Если при создании параметр allowExtension имеет значение false, включить загрузку расширений нельзя по соображениям безопасности.

database.location([dbName])

• dbName <string> Имя базы данных. Это может быть 'main' (основная база данных по умолчанию) или любая другая база данных, добавленная с помощью ATTACH DATABASE По умолчанию: 'main'.
• Возвращает: <string> | <null> Расположение файла базы данных. При использовании базы данных в памяти этот метод возвращает null.

Этот метод является оберткой для sqlite3_db_filename()

database.exec(sql)

• sql <string> Выполняемая строка SQL.

Этот метод позволяет выполнить один или несколько операторов SQL без возврата результатов. Он полезен для выполнения операторов SQL, считанных из файла. Этот метод является оберткой для sqlite3_exec().

database.function(name[, options], function)

• name <string> Имя создаваемой функции SQLite.
• options <Object> Необязательные параметры конфигурации функции. Поддерживаются следующие свойства:
  • deterministic <boolean> Если true, для создаваемой функции устанавливается флаг SQLITE_DETERMINISTIC. По умолчанию: false.
  • directOnly <boolean> Если true, для создаваемой функции устанавливается флаг SQLITE_DIRECTONLY. По умолчанию: false.
  • useBigIntArguments <boolean> Если true, целочисленные аргументы function преобразуются в BigInt. Если false, целочисленные аргументы передаются как числа JavaScript. По умолчанию: false.
  • varargs <boolean> Если true, function можно вызывать с любым количеством аргументов (от нуля до SQLITE_MAX_FUNCTION_ARG). Если false, function необходимо вызывать ровно с function.length аргументами. По умолчанию: false.
• function <Function> Функция JavaScript, вызываемая при вызове функции SQLite. Эта функция должна возвращать допустимый тип данных SQLite: см. раздел Преобразование типов между JavaScript и SQLite. Если возвращаемое значение равно undefined, результатом по умолчанию будет NULL.

Этот метод используется для создания пользовательских функций SQLite. Он является оберткой для sqlite3_create_function_v2().

database.isOpen

• Тип: <boolean> Открыта ли в данный момент база данных.

database.isTransaction

• Тип: <boolean> Находится ли база данных в данный момент в транзакции. Этот метод является оберткой для sqlite3_get_autocommit().

database.open()

Открывает базу данных, указанную в аргументе path конструктора DatabaseSync. Этот метод следует использовать только в том случае, если база данных не открывается конструктором. Если база данных уже открыта, возникает исключение.

database.prepare(sql)

• sql <string> Строка SQL для компиляции в подготовленный оператор.
• Возвращает: <StatementSync> Подготовленный оператор.

Компилирует оператор SQL в подготовленный оператор. Этот метод является оберткой для sqlite3_prepare_v2().

database.createSession([options])

• options <Object> Параметры конфигурации сеанса.
  • table <string> Отдельная таблица, изменения в которой будут отслеживаться. По умолчанию отслеживаются изменения во всех таблицах.
  • db <string> Имя отслеживаемой базы данных. Это полезно, если с помощью ATTACH DATABASE добавлено несколько баз данных. По умолчанию: 'main'.
• Возвращает: <Session> Дескриптор сеанса.

Создает сеанс и подключает его к базе данных. Этот метод является оберткой для sqlite3session_create() и sqlite3session_attach().

database.applyChangeset(changeset[, options])

• changeset <Uint8Array> Двоичный набор изменений или набор исправлений.
• options <Object> Параметры, определяющие способ применения изменений.

  • filter <Function> Пропускает изменения, если при передаче этой функции имени целевой таблицы она возвращает истинное значение. По умолчанию предпринимается попытка применить все изменения.

  • onConflict <Function> Функция, определяющая способ обработки конфликтов. Функция получает один аргумент, который может иметь одно из следующих значений:

    • SQLITE_CHANGESET_DATA: изменение DELETE или UPDATE не содержит ожидаемых значений «до».
    • SQLITE_CHANGESET_NOTFOUND: строка с первичным ключом изменения DELETE или UPDATE не существует.
    • SQLITE_CHANGESET_CONFLICT: изменение INSERT приводит к дублированию первичного ключа.
    • SQLITE_CHANGESET_FOREIGN_KEY: применение изменения приведет к нарушению ограничения внешнего ключа.
    • SQLITE_CHANGESET_CONSTRAINT: применение изменения приводит к нарушению ограничения UNIQUE, CHECK или NOT NULL.

    Функция должна возвращать одно из следующих значений:

    • SQLITE_CHANGESET_OMIT: пропустить конфликтующие изменения.
    • SQLITE_CHANGESET_REPLACE: заменить существующие значения конфликтующими изменениями (допустимо только при конфликтах SQLITE_CHANGESET_DATA или SQLITE_CHANGESET_CONFLICT).
    • SQLITE_CHANGESET_ABORT: прервать операцию при конфликте и выполнить откат базы данных.

    Если обработчик конфликтов выбрасывает ошибку или возвращает любое другое значение, применение набора изменений прерывается, а база данных откатывается.

    По умолчанию: функция, возвращающая SQLITE_CHANGESET_ABORT.

• Возвращает: <boolean> Успешно ли применен набор изменений без прерывания операции.

Если база данных не открыта, возникает исключение. Этот метод является оберткой для sqlite3changeset_apply().

const sourceDb = new DatabaseSync(':memory:');
const targetDb = new DatabaseSync(':memory:');

sourceDb.exec('CREATE TABLE data(key INTEGER PRIMARY KEY, value TEXT)');
targetDb.exec('CREATE TABLE data(key INTEGER PRIMARY KEY, value TEXT)');

const session = sourceDb.createSession();

const insert = sourceDb.prepare('INSERT INTO data (key, value) VALUES (?, ?)');
insert.run(1, 'hello');
insert.run(2, 'world');

const changeset = session.changeset();
targetDb.applyChangeset(changeset);
// Now that the changeset has been applied, targetDb contains the same data as sourceDb. copy

database[Symbol.dispose]()

Закрывает подключение к базе данных. Если подключение к базе данных уже закрыто, ничего не происходит.

session.changeset()

• Возвращает: <Uint8Array> Двоичный набор изменений, который можно применить к другим базам данных.

Получает набор изменений, содержащий все изменения с момента создания набора. Метод можно вызывать несколько раз. Если база данных или сеанс не открыты, возникает исключение. Этот метод является оберткой для sqlite3session_changeset().

session.patchset()

• Возвращает: <Uint8Array> Двоичный набор исправлений, который можно применить к другим базам данных.

Подобен описанному выше методу, но создает более компактный набор исправлений. См. раздел Наборы изменений и наборы исправлений в документации SQLite. Если база данных или сеанс не открыты, возникает исключение. Этот метод является оберткой для sqlite3session_patchset().

session.close().

Закрывает сеанс. Если база данных или сеанс не открыты, возникает исключение. Этот метод является оберткой для sqlite3session_delete().

statement.all([namedParameters][, ...anonymousParameters])

• namedParameters <Object> Необязательный объект для связывания именованных параметров. Ключи этого объекта используются для настройки соответствия.
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <TypedArray> | <DataView> Ноль или более значений для связывания с анонимными параметрами.
• Возвращает: <Array> Массив объектов. Каждый объект соответствует строке, возвращённой при выполнении подготовленного оператора. Ключи и значения каждого объекта соответствуют именам и значениям столбцов строки.

Этот метод выполняет подготовленный оператор и возвращает все результаты в виде массива объектов. Если подготовленный оператор не возвращает результатов, метод возвращает пустой массив. Параметры подготовленного оператора связываются с помощью значений из namedParameters и anonymousParameters.

statement.columns()

• Возвращает: <Array> Массив объектов. Каждый объект соответствует столбцу подготовленного оператора и содержит следующие свойства:

  • column <string> | <null> Не содержащие псевдонима имя столбца в исходной таблице или null, если столбец является результатом выражения или подзапроса. Это свойство соответствует результату sqlite3_column_origin_name().
  • database <string> | <null> Не содержащее псевдонима имя исходной базы данных или null, если столбец является результатом выражения или подзапроса. Это свойство соответствует результату sqlite3_column_database_name().
  • name <string> Имя, присвоенное столбцу в наборе результатов оператора SELECT. Это свойство соответствует результату sqlite3_column_name().
  • table <string> | <null> Не содержащее псевдонима имя исходной таблицы или null, если столбец является результатом выражения или подзапроса. Это свойство соответствует результату sqlite3_column_table_name().
  • type <string> Объявленный тип данных столбца или null, если столбец является результатом выражения или подзапроса. Это свойство соответствует результату sqlite3_column_decltype().

Этот метод позволяет получить сведения о столбцах, возвращаемых подготовленным оператором.

statement.expandedSQL

• Тип: <string> Исходный SQL-запрос с подставленными значениями параметров.

Исходный текст SQL-запроса подготовленного оператора, в котором заполнители параметров заменены значениями, использованными при последнем выполнении этого подготовленного оператора. Это свойство является обёрткой для sqlite3_expanded_sql().

statement.get([namedParameters][, ...anonymousParameters])

• namedParameters <Object> Необязательный объект для связывания именованных параметров. Ключи этого объекта используются для настройки соответствия.
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <TypedArray> | <DataView> Ноль или более значений для связывания с анонимными параметрами.
• Возвращает: <Object> | <undefined> Объект, соответствующий первой строке, возвращённой при выполнении подготовленного оператора. Ключи и значения объекта соответствуют именам и значениям столбцов строки. Если база данных не вернула ни одной строки, метод возвращает undefined.

Этот метод выполняет подготовленный оператор и возвращает первый результат в виде объекта. Если подготовленный оператор не возвращает результатов, метод возвращает undefined. Параметры подготовленного оператора связываются с помощью значений из namedParameters и anonymousParameters.

statement.iterate([namedParameters][, ...anonymousParameters])

• namedParameters <Object> Необязательный объект для связывания именованных параметров. Ключи этого объекта используются для настройки соответствия.
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <TypedArray> | <DataView> Ноль или более значений для связывания с анонимными параметрами.
• Возвращает: <Iterator> Итерируемый итератор объектов. Каждый объект соответствует строке, возвращённой при выполнении подготовленного оператора. Ключи и значения каждого объекта соответствуют именам и значениям столбцов строки.

Этот метод выполняет подготовленный оператор и возвращает итератор объектов. Если подготовленный оператор не возвращает результатов, метод возвращает пустой итератор. Параметры подготовленного оператора связываются с помощью значений из namedParameters и anonymousParameters.

statement.run([namedParameters][, ...anonymousParameters])

• namedParameters <Object> Необязательный объект для связывания именованных параметров. Ключи этого объекта используются для настройки соответствия.
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <TypedArray> | <DataView> Ноль или более значений для связывания с анонимными параметрами.
• Возвращает: <Object>
  • changes <number> | <bigint> Число строк, изменённых, вставленных или удалённых последним завершённым оператором INSERT, UPDATE или DELETE. Это поле содержит число или BigInt в зависимости от конфигурации подготовленного оператора. Это свойство соответствует результату sqlite3_changes64().
  • lastInsertRowid <number> | <bigint> Идентификатор строки, вставленной последней. Это поле содержит число или BigInt в зависимости от конфигурации подготовленного оператора. Это свойство соответствует результату sqlite3_last_insert_rowid().

Этот метод выполняет подготовленный оператор и возвращает объект со сводной информацией о внесённых изменениях. Параметры подготовленного оператора связываются с помощью значений из namedParameters и anonymousParameters.

statement.setAllowBareNamedParameters(enabled)

• enabled <boolean> Включает или отключает поддержку связывания именованных параметров без символа-префикса.

Имена параметров SQLite начинаются с символа-префикса. По умолчанию node:sqlite требует наличия этого префикса при связывании параметров. Однако, за исключением знака доллара, при использовании этих символов-префиксов в ключах объектов также требуется дополнительное экранирование.

Для удобства этот метод позволяет использовать также именованные параметры без префикса, который не требуется указывать в коде JavaScript. При включении именованных параметров без префикса следует учитывать несколько особенностей:

• В SQL символ-префикс по-прежнему обязателен.
• В JavaScript символ-префикс по-прежнему допустим. Более того, связывание имён с префиксом будет немного эффективнее.
• Использование неоднозначных именованных параметров, таких как $k и @k, в одном подготовленном операторе приведёт к исключению, поскольку определить способ связывания имени без префикса невозможно.

statement.setAllowUnknownNamedParameters(enabled)

• enabled <boolean> Включает или отключает поддержку неизвестных именованных параметров.

По умолчанию при обнаружении неизвестного имени во время связывания параметров выбрасывается исключение. Этот метод позволяет игнорировать неизвестные именованные параметры.

statement.setReturnArrays(enabled)

• enabled <boolean> Включает или отключает возврат результатов запросов в виде массивов.

Если этот параметр включён, методы all(), get() и iterate() будут возвращать результаты запросов в виде массивов, а не объектов.

statement.setReadBigInts(enabled)

• enabled <boolean> Включает или отключает использование BigInt при чтении из базы данных полей INTEGER.

При чтении из базы данных значения INTEGER SQLite по умолчанию преобразуются в числа JavaScript. Однако значения INTEGER SQLite могут быть больше чисел, которые способны представить числа JavaScript. В таких случаях этот метод позволяет читать данные INTEGER с помощью значений BigInt JavaScript. Этот метод не влияет на операции записи в базу данных, где числа и значения BigInt поддерживаются всегда.

statement.sourceSQL

• Тип: <string> Исходный SQL-запрос, использованный для создания этого подготовленного оператора.

Исходный текст SQL-запроса подготовленного оператора. Это свойство является обёрткой для sqlite3_sql().

Преобразование типов между JavaScript и SQLite

При чтении данных из SQLite или записи в неё средствами Node.js необходимо преобразовывать типы данных JavaScript в типы данных SQLite и обратно. Поскольку JavaScript поддерживает больше типов данных, чем SQLite, поддерживается только подмножество типов JavaScript. Попытка записать в SQLite неподдерживаемый тип данных приведёт к исключению.

Константы SQLite

Следующие константы экспортируются объектом sqlite.constants.