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, целочисленные аргументы функции преобразуются в BigInt. Если false, целочисленные аргументы передаются как числа JavaScript. По умолчанию: false.
- varargs <boolean> Если true, функция может принимать переменное количество аргументов. Если false, функция должна вызываться ровно с 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.

Класс: `Session`

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

`session.changeset()`

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

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

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

`session.patchset()`

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

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

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

`session.close()`.

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

Класс: `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([namedParameters][, ...anonymousParameters])`

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

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

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

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

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

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

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

`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

При записи в SQLite или чтении из него в Node.js необходимо преобразовывать типы данных JavaScript и типы данных SQLite data types. Поскольку 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]) ​

Класс: Session ​

session.changeset() ​

session.patchset() ​

session.close(). ​

Класс: StatementSync ​

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

statement.expandedSQL ​

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

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

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])`

Класс: `Session`

`session.changeset()`

`session.patchset()`

`session.close()`.

Класс: `StatementSync`

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

`statement.expandedSQL`

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

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

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

`statement.setAllowBareNamedParameters(enabled)`

`statement.setReadBigInts(enabled)`

`statement.sourceSQL`

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

`sqlite.constants`

Константы SQLite

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