SQLite

Добавлено в версии: v22.5.0

[Стабильность: 1 - Экспериментальный]

Стабильность: 1 Стабильность: 1.1 - Активная разработка.

Исходный код: lib/sqlite.js

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

ESMCJS

import sqlite from 'node:sqlite';

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

Этот модуль доступен только по схеме node:.

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

ESMCJS

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

// Выполнение SQL-запросов из строк.
database.exec(`
  CREATE TABLE data(
    key INTEGER PRIMARY KEY,
    value TEXT
  ) STRICT
`);
// Создание подготовленного запроса для вставки данных в базу данных.
const insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)');
// Выполнение подготовленного запроса со связанными значениями.
insert.run(1, 'hello');
insert.run(2, 'world');
// Создание подготовленного запроса для чтения данных из базы данных.
const query = database.prepare('SELECT * FROM data ORDER BY key');
// Выполнение подготовленного запроса и вывод результирующего набора.
console.log(query.all());
// Выводит: [ { key: 1, value: 'hello' }, { key: 2, value: 'world' } ]

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

// Выполнение SQL-запросов из строк.
database.exec(`
  CREATE TABLE data(
    key INTEGER PRIMARY KEY,
    value TEXT
  ) STRICT
`);
// Создание подготовленного запроса для вставки данных в базу данных.
const insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)');
// Выполнение подготовленного запроса со связанными значениями.
insert.run(1, 'hello');
insert.run(2, 'world');
// Создание подготовленного запроса для чтения данных из базы данных.
const query = database.prepare('SELECT * FROM data ORDER BY key');
// Выполнение подготовленного запроса и вывод результирующего набора.
console.log(query.all());
// Выводит: [ { key: 1, value: 'hello' }, { key: 2, value: 'world' } ]

Класс: `DatabaseSync`

Добавлено в версии: v22.5.0

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

`new DatabaseSync(location[, options])`

Добавлено в версии: v22.5.0

location <string> Расположение базы данных. База данных 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.

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

`database.close()`

Добавлено в: v22.5.0

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

`database.loadExtension(path)`

Добавлено в: v23.5.0

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

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

`database.enableLoadExtension(allow)`

Добавлено в: v23.5.0

allow <boolean> Определяет, разрешена ли загрузка расширений.

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

`database.exec(sql)`

Добавлено в: v22.5.0

sql <string> SQL-строка для выполнения.

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

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

Добавлено в: v23.5.0

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

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

`database.open()`

Добавлено в: v22.5.0

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

`database.prepare(sql)`

Добавлено в: v22.5.0

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

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

`database.createSession([options])`

Добавлено в: v23.3.0

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

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

`database.applyChangeset(changeset[, options])`

Добавлено в: v23.3.0

changeset <Uint8Array> Бинарный набор изменений или патчсет.
options <Object> Параметры конфигурации для применения изменений.
- filter <Function> Пропускает изменения, которые, когда имя целевой таблицы передается в эту функцию, возвращают истинное значение. По умолчанию предпринимаются все изменения.
- onConflict <number> Определяет, как обрабатываются конфликты. По умолчанию: SQLITE_CHANGESET_ABORT.
- SQLITE_CHANGESET_OMIT: конфликтующие изменения опускаются.
- SQLITE_CHANGESET_REPLACE: конфликтующие изменения заменяют существующие значения.
- 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);
// Теперь, когда набор изменений был применен, targetDb содержит те же данные, что и sourceDb.

Class: `Session`

Добавлено в версии: v23.3.0

`session.changeset()`

Добавлено в версии: v23.3.0

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

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

`session.patchset()`

Добавлено в версии: v23.3.0

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

Аналогичен методу выше, но генерирует более компактный набор патчей. См. Changesets and Patchsets в документации SQLite. Исключение выбрасывается, если база данных или сессия не открыты. Этот метод является оберткой вокруг sqlite3session_patchset().

`session.close()`.

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

Class: `StatementSync`

Добавлено в версии: v22.5.0

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

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

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

Добавлено в версии: v22.5.0

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

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

`statement.expandedSQL`

Добавлено в версии: v22.5.0

<string> Исходный SQL, расширенный для включения значений параметров.

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

`statement.get([именованныеПараметры][, ...анонимныеПараметры])`

Добавлено в версии: v22.5.0

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

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

`statement.iterate([именованныеПараметры][, ...анонимныеПараметры])`

Добавлено в версии: v23.4.0

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

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

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

Добавлено в: v22.5.0

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

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

`statement.setAllowBareNamedParameters(enabled)`

Добавлено в версии: v22.5.0

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

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

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

Префиксный символ по-прежнему требуется в SQL.
Префиксный символ по-прежнему разрешен в JavaScript. Фактически, имена с префиксами будут иметь немного лучшую производительность привязки.
Использование неоднозначных именованных параметров, таких как $k и @k, в одном и том же подготовленном операторе приведет к исключению, поскольку невозможно определить, как привязать "голое" имя.

`statement.setReadBigInts(enabled)`

Добавлено в версии: v22.5.0

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

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

`statement.sourceSQL`

Добавлено в версии: v22.5.0

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

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

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

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

SQLite	JavaScript
`NULL`	<null>
`INTEGER`	<number> или <bigint>
`REAL`	<number>
`TEXT`	<string>
`BLOB`	<Uint8Array>

`sqlite.constants`

Добавлено в: v23.5.0

<Object>

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

Константы SQLite

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

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

Следующие константы предназначены для использования с database.applyChangeset().

Константа	Описание
`SQLITE_CHANGESET_OMIT`	Конфликтующие изменения игнорируются.
`SQLITE_CHANGESET_REPLACE`	Конфликтующие изменения заменяют существующие значения.
`SQLITE_CHANGESET_ABORT`	Прервать работу при возникновении конфликта и откатить базу данных.

SQLite ​

Класс: DatabaseSync ​

new DatabaseSync(location[, options]) ​

database.close() ​

database.loadExtension(path) ​

database.enableLoadExtension(allow) ​

database.exec(sql) ​

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

database.open() ​

database.prepare(sql) ​

database.createSession([options]) ​

database.applyChangeset(changeset[, options]) ​

Class: Session ​

session.changeset() ​

session.patchset() ​

session.close(). ​

Class: StatementSync ​

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

statement.expandedSQL ​

statement.get([именованныеПараметры][, ...анонимныеПараметры]) ​

statement.iterate([именованныеПараметры][, ...анонимныеПараметры]) ​

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

statement.setAllowBareNamedParameters(enabled) ​

statement.setReadBigInts(enabled) ​

statement.sourceSQL ​

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

sqlite.constants ​

Константы SQLite ​

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

SQLite

Класс: `DatabaseSync`

`new DatabaseSync(location[, options])`

`database.close()`

`database.loadExtension(path)`

`database.enableLoadExtension(allow)`

`database.exec(sql)`

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

`database.open()`

`database.prepare(sql)`

`database.createSession([options])`

`database.applyChangeset(changeset[, options])`

Class: `Session`

`session.changeset()`

`session.patchset()`

`session.close()`.

Class: `StatementSync`

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

`statement.expandedSQL`

`statement.get([именованныеПараметры][, ...анонимныеПараметры])`

`statement.iterate([именованныеПараметры][, ...анонимныеПараметры])`

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

`statement.setAllowBareNamedParameters(enabled)`

`statement.setReadBigInts(enabled)`

`statement.sourceSQL`

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

`sqlite.constants`

Константы SQLite

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