SQLite

Модуль node:sqlite упрощает работу с базами данных SQLite. Для доступа к нему:

import sqlite from 'node:sqlite';

const sqlite = require('node:sqlite');

Этот модуль доступен только при использовании схемы node:.

В следующем примере показано базовое использование модуля node:sqlite для открытия базы данных в памяти, записи данных в базу, а затем чтения этих данных.

import { DatabaseSync } from 'node:sqlite';
const database = new DatabaseSync(':memory:');

// Execute SQL statements from strings.
database.exec(`
  CREATE TABLE data(
    key INTEGER PRIMARY KEY,
    value TEXT
  ) STRICT
`);
// Create a prepared statement to insert data into the database.
const insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)');
// Execute the prepared statement with bound values.
insert.run(1, 'hello');
insert.run(2, 'world');
// Create a prepared statement to read data from the database.
const query = database.prepare('SELECT * FROM data ORDER BY key');
// Execute the prepared statement and log the result set.
console.log(query.all());
// Prints: [ { key: 1, value: 'hello' }, { key: 2, value: 'world' } ]

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

// Execute SQL statements from strings.
database.exec(`
  CREATE TABLE data(
    key INTEGER PRIMARY KEY,
    value TEXT
  ) STRICT
`);
// Create a prepared statement to insert data into the database.
const insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)');
// Execute the prepared statement with bound values.
insert.run(1, 'hello');
insert.run(2, 'world');
// Create a prepared statement to read data from the database.
const query = database.prepare('SELECT * FROM data ORDER BY key');
// Execute the prepared statement and log the result set.
console.log(query.all());
// Prints: [ { key: 1, value: 'hello' }, { key: 2, value: 'world' } ]

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

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

У API, которые считывают значения из SQLite, есть параметр конфигурации, определяющий, преобразуются ли значения INTEGER в number или bigint в JavaScript. Например, это параметр readBigInts для инструкций и параметр useBigIntArguments для функций, определенных пользователем. Если Node.js считывает из SQLite значение INTEGER, выходящее за пределы диапазона безопасных целых чисел JavaScript, и чтение BigInt не включено, будет выброшена ошибка ERR_OUT_OF_RANGE.

Класс: DatabaseSync

Этот класс представляет собой одно подключение к базе данных SQLite. Все API, предоставляемые этим классом, выполняются синхронно.

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.
  • defensive <boolean> Если значение равно true, включается защитный флаг. При включенном защитном флаге отключаются языковые возможности, позволяющие обычному SQL намеренно повредить файл базы данных. Защитный флаг также можно установить с помощью enableDefensive(). По умолчанию: true.
  • limits <Object> Конфигурация различных ограничений SQLite. Эти ограничения можно использовать для предотвращения чрезмерного расхода ресурсов при обработке потенциально вредоносных входных данных. Подробности см. в разделах «Ограничения во время выполнения» и «Константы ограничений» документации SQLite. Значения по умолчанию определяются параметрами SQLite, заданными во время компиляции, и могут различаться в зависимости от сборки SQLite. Поддерживаются следующие свойства:
    • length <number> Максимальная длина строки или BLOB.
    • sqlLength <number> Максимальная длина инструкции SQL.
    • column <number> Максимальное количество столбцов.
    • exprDepth <number> Максимальная глубина дерева выражений.
    • compoundSelect <number> Максимальное количество выражений в составном операторе SELECT.
    • vdbeOp <number> Максимальное количество инструкций VDBE.
    • functionArg <number> Максимальное количество аргументов функции.
    • attach <number> Максимальное количество подключенных баз данных.
    • likePatternLength <number> Максимальная длина шаблона LIKE.
    • variableNumber <number> Максимальное количество переменных SQL.
    • triggerDepth <number> Максимальная глубина рекурсии триггеров.

Создает новый экземпляр 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[, entryPoint])

• path <string> Путь к загружаемой общей библиотеке.
• entryPoint <string> Имя функции точки входа расширения. Если аргумент не указан, SQLite определяет точку входа по имени файла общей библиотеки; укажите этот аргумент явно, если полученное имя не совпадает.

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

import { DatabaseSync } from 'node:sqlite';
const database = new DatabaseSync(':memory:', { allowExtension: true });

// Load using the entry point derived from the filename.
database.loadExtension('./decimal.dylib');

// Override the entry point when the derived name does not match.
database.loadExtension('./base64.dylib', 'sqlite3_base64_init');

const { DatabaseSync } = require('node:sqlite');
const database = new DatabaseSync(':memory:', { allowExtension: true });

// Load using the entry point derived from the filename.
database.loadExtension('./decimal.dylib');

// Override the entry point when the derived name does not match.
database.loadExtension('./base64.dylib', 'sqlite3_base64_init');

database.enableLoadExtension(allow)

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

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

database.enableDefensive(active)

• active <boolean> Установить ли защитный флаг.

Включает или отключает защитный флаг. Если защитный флаг активен, отключаются языковые возможности, позволяющие обычному SQL намеренно повредить файл базы данных. Подробности см. в SQLITE_DBCONFIG_DEFENSIVE документации SQLite.

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], fn)

• 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.
• fn <Function> Функция JavaScript, вызываемая при вызове функции SQLite. Эта функция должна возвращать допустимый тип данных SQLite: см. раздел «Преобразование типов между JavaScript и SQLite». Если возвращаемое значение равно undefined, результатом по умолчанию будет NULL.

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

database.setAuthorizer(callback)

• callback <Function> | <null> Функция авторизации, которую нужно установить, или null для сброса текущей функции авторизации.

Задает функцию обратного вызова авторизации, которую SQLite будет вызывать при каждой попытке доступа к данным или изменения схемы базы данных с помощью подготовленных инструкций. Это можно использовать для реализации политик безопасности, аудита доступа или ограничения определенных операций. Этот метод является оберткой для sqlite3_set_authorizer().

При вызове функция обратного вызова получает пять аргументов:

• actionCode <number> Тип выполняемой операции (например, SQLITE_INSERT, SQLITE_UPDATE, SQLITE_SELECT).
• arg1 <string> | <null> Первый аргумент (зависит от контекста, часто это имя таблицы).
• arg2 <string> | <null> Второй аргумент (зависит от контекста, часто это имя столбца).
• dbName <string> | <null> Имя базы данных.
• triggerOrView <string> | <null> Имя триггера или представления, вызвавшего обращение.

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

• SQLITE_OK — разрешить операцию.
• SQLITE_DENY — запретить операцию (вызывает ошибку).
• SQLITE_IGNORE — игнорировать операцию (без уведомления).

const { DatabaseSync, constants } = require('node:sqlite');
const db = new DatabaseSync(':memory:');

// Set up an authorizer that denies all table creation
db.setAuthorizer((actionCode) => {
  if (actionCode === constants.SQLITE_CREATE_TABLE) {
    return constants.SQLITE_DENY;
  }
  return constants.SQLITE_OK;
});

// This will work
db.prepare('SELECT 1').get();

// This will throw an error due to authorization denial
try {
  db.exec('CREATE TABLE blocked (id INTEGER)');
} catch (err) {
  console.log('Operation blocked:', err.message);
}

import { DatabaseSync, constants } from 'node:sqlite';
const db = new DatabaseSync(':memory:');

// Set up an authorizer that denies all table creation
db.setAuthorizer((actionCode) => {
  if (actionCode === constants.SQLITE_CREATE_TABLE) {
    return constants.SQLITE_DENY;
  }
  return constants.SQLITE_OK;
});

// This will work
db.prepare('SELECT 1').get();

// This will throw an error due to authorization denial
try {
  db.exec('CREATE TABLE blocked (id INTEGER)');
} catch (err) {
  console.log('Operation blocked:', err.message);
}

database.isOpen

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

database.isTransaction

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

database.limits

• Тип: <Object>

Объект для получения и задания ограничений базы данных SQLite во время выполнения. Каждое свойство соответствует ограничению SQLite и может быть прочитано или изменено.

const db = new DatabaseSync(':memory:');

// Read current limit
console.log(db.limits.length);

// Set a new limit
db.limits.sqlLength = 100000;

// Reset a limit to its compile-time maximum
db.limits.sqlLength = Infinity;
jscopy

Доступные свойства: length, sqlLength, column, exprDepth, compoundSelect, vdbeOp, functionArg, attach, likePatternLength, variableNumber, triggerDepth.

Установка для свойства значения Infinity сбрасывает ограничение до максимального значения, заданного во время компиляции.

database.open()

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

database.serialize([dbName])

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

Сериализует базу данных в двоичное представление, возвращаемое как Uint8Array. Это полезно для сохранения, клонирования или передачи базы данных в памяти. Этот метод является обёрткой для sqlite3_serialize().

import { DatabaseSync } from 'node:sqlite';

const db = new DatabaseSync(':memory:');
db.exec('CREATE TABLE t(key INTEGER PRIMARY KEY, value TEXT)');
db.exec("INSERT INTO t VALUES (1, 'hello')");
const buffer = db.serialize();
console.log(buffer.length); // Prints the byte length of the database

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

const db = new DatabaseSync(':memory:');
db.exec('CREATE TABLE t(key INTEGER PRIMARY KEY, value TEXT)');
db.exec("INSERT INTO t VALUES (1, 'hello')");
const buffer = db.serialize();
console.log(buffer.length); // Prints the byte length of the database

database.deserialize(buffer[, options])

• buffer <Uint8Array> Двоичное представление базы данных, например результат вызова database.serialize().
• options <Object> Необязательная конфигурация десериализации.
  • dbName <string> Имя базы данных, в которую выполняется десериализация. По умолчанию: 'main'.

Загружает сериализованную базу данных в это подключение, заменяя текущую базу данных. Десериализованная база данных доступна для записи. Существующие подготовленные инструкции завершаются до начала десериализации, даже если впоследствии операция завершается ошибкой. Этот метод является обёрткой для sqlite3_deserialize().

import { DatabaseSync } from 'node:sqlite';

const original = new DatabaseSync(':memory:');
original.exec('CREATE TABLE t(key INTEGER PRIMARY KEY, value TEXT)');
original.exec("INSERT INTO t VALUES (1, 'hello')");
const buffer = original.serialize();
original.close();

const clone = new DatabaseSync(':memory:');
clone.deserialize(buffer);
console.log(clone.prepare('SELECT value FROM t').get());
// Prints: { value: 'hello' }

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

const original = new DatabaseSync(':memory:');
original.exec('CREATE TABLE t(key INTEGER PRIMARY KEY, value TEXT)');
original.exec("INSERT INTO t VALUES (1, 'hello')");
const buffer = original.serialize();
original.close();

const clone = new DatabaseSync(':memory:');
clone.deserialize(buffer);
console.log(clone.prepare('SELECT value FROM t').get());
// Prints: { value: 'hello' }

database.prepare(sql[, options])

• sql <string> Строка SQL для компиляции в подготовленную инструкцию.
• options <Object> Необязательная конфигурация подготовленной инструкции.
  • readBigInts <boolean> Если true, целочисленные поля считываются как значения типа BigInt. По умолчанию: наследуется из параметров базы данных или равно false.
  • returnArrays <boolean> Если true, результаты возвращаются в виде массивов. По умолчанию: наследуется из параметров базы данных или равно false.
  • allowBareNamedParameters <boolean> Если true, разрешает связывать именованные параметры без символа префикса. По умолчанию: наследуется из параметров базы данных или равно true.
  • allowUnknownNamedParameters <boolean> Если true, неизвестные именованные параметры игнорируются. По умолчанию: наследуется из параметров базы данных или равно false.
• Возвращает: <StatementSync> Подготовленную инструкцию.

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

database.createTagStore([maxSize])

• maxSize <integer> Максимальное количество подготовленных инструкций для кэширования. По умолчанию: 1000.
• Возвращает: {SQLTagStore} Новое хранилище SQL-тегов для кэширования подготовленных инструкций.

Создаёт новое SQLTagStore — кэш подготовленных инструкций, работающий по алгоритму «наименее недавно использовавшийся» (LRU). Это позволяет эффективно повторно использовать подготовленные инструкции, помечая их уникальным идентификатором.

При выполнении SQL-литерала с тегом SQLTagStore проверяет, существует ли в кэше подготовленная инструкция для соответствующей строки SQL-запроса. Если существует, используется кэшированная инструкция. Если нет, создаётся и выполняется новая подготовленная инструкция, а затем сохраняется в кэше для дальнейшего использования. Этот механизм помогает избежать затрат на повторный разбор и подготовку одних и тех же инструкций SQL.

Инструкции с тегами связывают значения-заполнители из шаблонного литерала как параметры базовой подготовленной инструкции. Например:

sqlTagStore.get`SELECT ${value}`;
jscopy

эквивалентно следующему:

db.prepare('SELECT ?').get(value);
jscopy

Однако в первом примере хранилище тегов кэширует базовую подготовленную инструкцию для дальнейшего использования.

Примечание: Синтаксис ${value} в инструкциях с тегами связывает параметр с подготовленной инструкцией. Это отличается от его поведения в литералах шаблонных строк без тегов, где он выполняет интерполяцию строк.

// This a safe example of binding a parameter to a tagged statement.
sqlTagStore.run`INSERT INTO t1 (id) VALUES (${id})`;

// This is an *unsafe* example of an untagged template string.
// `id` is interpolated into the query text as a string.
// This can lead to SQL injection and data corruption.
db.run(`INSERT INTO t1 (id) VALUES (${id})`);
jscopy

Хранилище тегов найдёт инструкцию в кэше, если строки запроса (включая позиции всех связанных заполнителей) идентичны.

// The following statements will match in the cache:
sqlTagStore.get`SELECT * FROM t1 WHERE id = ${id} AND active = 1`;
sqlTagStore.get`SELECT * FROM t1 WHERE id = ${12345} AND active = 1`;

// The following statements will not match, as the query strings
// and bound placeholders differ:
sqlTagStore.get`SELECT * FROM t1 WHERE id = ${id} AND active = 1`;
sqlTagStore.get`SELECT * FROM t1 WHERE id = 12345 AND active = 1`;

// The following statements will not match, as matches are case-sensitive:
sqlTagStore.get`SELECT * FROM t1 WHERE id = ${id} AND active = 1`;
sqlTagStore.get`select * from t1 where id = ${id} and active = 1`;
jscopy

Единственный способ связать параметры в инструкциях с тегами — использовать синтаксис ${value}. Не добавляйте заполнители для связывания параметров (например, ?) непосредственно в строку SQL-запроса.

import { DatabaseSync } from 'node:sqlite';

const db = new DatabaseSync(':memory:');
const sql = db.createTagStore();

db.exec('CREATE TABLE users (id INT, name TEXT)');

// Using the 'run' method to insert data.
// The tagged literal is used to identify the prepared statement.
sql.run`INSERT INTO users VALUES (1, 'Alice')`;
sql.run`INSERT INTO users VALUES (2, 'Bob')`;

// Using the 'get' method to retrieve a single row.
const name = 'Alice';
const user = sql.get`SELECT * FROM users WHERE name = ${name}`;
console.log(user); // { id: 1, name: 'Alice' }

// Using the 'all' method to retrieve all rows.
const allUsers = sql.all`SELECT * FROM users ORDER BY id`;
console.log(allUsers);
// [
//   { id: 1, name: 'Alice' },
//   { id: 2, name: 'Bob' }
// ]

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

const db = new DatabaseSync(':memory:');
const sql = db.createTagStore();

db.exec('CREATE TABLE users (id INT, name TEXT)');

// Using the 'run' method to insert data.
// The tagged literal is used to identify the prepared statement.
sql.run`INSERT INTO users VALUES (1, 'Alice')`;
sql.run`INSERT INTO users VALUES (2, 'Bob')`;

// Using the 'get' method to retrieve a single row.
const name = 'Alice';
const user = sql.get`SELECT * FROM users WHERE name = ${name}`;
console.log(user); // { id: 1, name: 'Alice' }

// Using the 'all' method to retrieve all rows.
const allUsers = sql.all`SELECT * FROM users ORDER BY id`;
console.log(allUsers);
// [
//   { id: 1, name: 'Alice' },
//   { id: 2, name: 'Bob' }
// ]

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> для каждой таблицы, затронутой хотя бы одним изменением из набора изменений, вызывается функция обратного вызова filter с именем таблицы в качестве первого аргумента. Если возвращаемое значение является ложным, попытка применить изменения к таблице не выполняется. В противном случае, если возвращаемое значение является истинным или функция обратного вызова filter не задана, выполняется попытка применить все изменения, относящиеся к таблице.

  • 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().

import { DatabaseSync } from 'node:sqlite';

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.

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

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.

database[Symbol.dispose]()

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

Класс: Session

session.changeset()

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

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

session.patchset()

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

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

session.close()

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

session[Symbol.dispose]()

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

Класс: StatementSync

Этот класс представляет одну подготовленную инструкцию. Экземпляр этого класса нельзя создать с помощью конструктора. Вместо этого экземпляры создаются методом database.prepare(). Все API, предоставляемые этим классом, выполняются синхронно.

Подготовленная инструкция — это эффективное двоичное представление SQL-кода, использованного для её создания. В подготовленные инструкции можно передавать параметры, и их можно вызывать несколько раз с разными связанными значениями. Параметры также обеспечивают защиту от атак типа SQL-инъекция. Поэтому при обработке пользовательского ввода предпочтительно использовать подготовленные инструкции, а не составленные вручную строки SQL.

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> Объявленный тип данных столбца или 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 по умолчанию преобразуются в числа JavaScript. Однако значения INTEGER могут превышать диапазон представимых чисел JavaScript. В таких случаях этот метод можно использовать для чтения данных INTEGER с помощью BigInt JavaScript. Этот метод не влияет на операции записи в базу данных, при которых числа и BigInt поддерживаются всегда.

statement.sourceSQL

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

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

Класс: SQLTagStore

Этот класс представляет собой отдельный кэш LRU (Least Recently Used — вытеснение давно не использовавшихся элементов) для хранения подготовленных выражений.

Экземпляры этого класса создаются с помощью метода database.createTagStore(), а не конструктора. Хранилище кэширует подготовленные выражения на основе предоставленной строки SQL-запроса. При повторном появлении того же запроса хранилище извлекает кэшированное выражение и безопасно применяет новые значения посредством связывания параметров, предотвращая такие атаки, как внедрение SQL-кода.

По умолчанию максимальный размер кэша составляет 1000 выражений, но можно указать пользовательский размер (например, database.createTagStore(100)). Все API этого класса выполняются синхронно.

sqlTagStore.all(stringElements[, ...boundParameters])

• stringElements <string[]> Элементы шаблонного литерала, содержащие SQL-запрос.
• ...boundParameters <null> | <number> | <bigint> | <string> | <Buffer> | <TypedArray> | <DataView> Значения параметров, которые будут связаны с заполнителями в шаблонной строке.
• Возвращает: <Array> Массив объектов, представляющих строки, возвращённые запросом.

Выполняет указанный SQL-запрос и возвращает все полученные строки в виде массива объектов.

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

sqlTagStore.get(stringElements[, ...boundParameters])

• stringElements <string[]> Элементы шаблонного литерала, содержащие SQL-запрос.
• ...boundParameters <null> | <number> | <bigint> | <string> | <Buffer> | <TypedArray> | <DataView> Значения параметров, которые будут связаны с заполнителями в шаблонной строке.
• Возвращает: <Object> | <undefined> Объект, представляющий первую строку, возвращённую запросом, или undefined, если строки не возвращены.

Выполняет указанный SQL-запрос и возвращает первую полученную строку в виде объекта.

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

sqlTagStore.iterate(stringElements[, ...boundParameters])

• stringElements <string[]> Элементы шаблонного литерала, содержащие SQL-запрос.
• ...boundParameters <null> | <number> | <bigint> | <string> | <Buffer> | <TypedArray> | <DataView> Значения параметров, которые будут связаны с заполнителями в шаблонной строке.
• Возвращает: <Iterator> Итератор, возвращающий объекты, представляющие строки, полученные в результате запроса.

Выполняет указанный SQL-запрос и возвращает итератор по полученным строкам.

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

sqlTagStore.run(stringElements[, ...boundParameters])

• stringElements <string[]> Элементы шаблонного литерала, содержащие SQL-запрос.
• ...boundParameters <null> | <number> | <bigint> | <string> | <Buffer> | <TypedArray> | <DataView> Значения параметров, которые будут связаны с заполнителями в шаблонной строке.
• Возвращает: <Object> Объект со сведениями о выполнении, включая changes и lastInsertRowid.

Выполняет указанный SQL-запрос, который не должен возвращать строки (например, INSERT, UPDATE, DELETE).

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

sqlTagStore.size

• Тип: <integer>

Свойство только для чтения, возвращающее количество подготовленных выражений, находящихся в кэше.

sqlTagStore.capacity

• Тип: <integer>

Свойство только для чтения, возвращающее максимальное количество подготовленных выражений, которое может храниться в кэше.

sqlTagStore.db

• Тип: <DatabaseSync>

Свойство только для чтения, возвращающее объект DatabaseSync, связанный с этим SQLTagStore.

sqlTagStore.clear()

Сбрасывает кэш LRU, удаляя все сохранённые подготовленные выражения.

sqlite.backup(sourceDb, path[, options])

• sourceDb <DatabaseSync> База данных для резервного копирования. Исходная база данных должна быть открыта.
• path <string> | <Buffer> | <URL> Путь, по которому будет создана резервная копия. Если файл уже существует, его содержимое будет перезаписано.
• options <Object> Необязательные параметры резервного копирования. Поддерживаются следующие свойства:
  • source <string> Имя исходной базы данных. Это может быть 'main' (основная база данных по умолчанию) или любая другая база данных, добавленная с помощью ATTACH DATABASE По умолчанию: 'main'.
  • target <string> Имя целевой базы данных. Это может быть 'main' (основная база данных по умолчанию) или любая другая база данных, добавленная с помощью ATTACH DATABASE По умолчанию: 'main'.
  • rate <number> Количество страниц, передаваемых в каждой порции резервной копии. По умолчанию: 100.
  • progress <Function> Необязательная функция обратного вызова, вызываемая после каждого шага резервного копирования. В эту функцию передаётся <Object> со свойствами remainingPages и totalPages, описывающими текущий ход операции резервного копирования.
• Возвращает: <Promise> Промис, который при успешном завершении возвращает общее количество страниц резервной копии или отклоняется при возникновении ошибки.

Этот метод создаёт резервную копию базы данных. Метод является абстракцией над функциями sqlite3_backup_init(), sqlite3_backup_step() и sqlite3_backup_finish().

Базу данных, для которой создаётся резервная копия, можно использовать в обычном режиме во время процесса копирования. Изменения, внесённые через то же соединение — тот же объект <DatabaseSync>, — сразу же отразятся в резервной копии. Однако изменения из других соединений приведут к перезапуску процесса резервного копирования.

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

(async () => {
  const sourceDb = new DatabaseSync('source.db');
  const totalPagesTransferred = await backup(sourceDb, 'backup.db', {
    rate: 1, // Copy one page at a time.
    progress: ({ totalPages, remainingPages }) => {
      console.log('Backup in progress', { totalPages, remainingPages });
    },
  });

  console.log('Backup completed', totalPagesTransferred);
})();

import { backup, DatabaseSync } from 'node:sqlite';

const sourceDb = new DatabaseSync('source.db');
const totalPagesTransferred = await backup(sourceDb, 'backup.db', {
  rate: 1, // Copy one page at a time.
  progress: ({ totalPages, remainingPages }) => {
    console.log('Backup in progress', { totalPages, remainingPages });
  },
});

console.log('Backup completed', totalPagesTransferred);

sqlite.constants

• Тип: <Object>

Объект, содержащий часто используемые константы для операций SQLite.

Константы SQLite

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

Константы разрешения конфликтов

Одна из следующих констант передаётся в качестве аргумента обработчику разрешения конфликтов onConflict, переданному в database.applyChangeset(). См. также раздел Константы, передаваемые обработчику конфликтов в документации SQLite.

Из обработчика разрешения конфликтов onConflict, переданного в database.applyChangeset(), необходимо вернуть одну из следующих констант. См. также раздел Константы, возвращаемые обработчиком конфликтов в документации SQLite.

Константы авторизации

Следующие константы используются с методом database.setAuthorizer().

Коды результата авторизации

Функция обратного вызова авторизатора, переданная в database.setAuthorizer(), должна возвращать одну из следующих констант.

Коды действий авторизации

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