sqlite

Совместимость с Deno

Этот модуль добавлен в Deno v2.2.

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

import sqlite from 'node:sqlite';

Этот модуль доступен только по схеме node:. Следующий код не будет работать:

import sqlite from 'sqlite';

В следующем примере показано базовое использование модуля 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' } ]

Использование в Deno

import * as mod from "node:sqlite";

класс DatabaseSync

Использование в Deno

import { DatabaseSync } from "node:sqlite";

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

Конструкторы

DatabaseSync(

location: string,

options?: DatabaseSyncOptions,
)

новый

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

Методы

applyChangeset(

changeset: Uint8Array,

options?: ApplyChangesetOptions,
): 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.

close(): void

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

createSession(options?: CreateSessionOptions): Session

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

enableLoadExtension(allow: boolean): void

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

exec(sql: string): void

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

function(

name: string,

options: FunctionOptions,

func: (...args: SupportedValueType[]) => SupportedValueType,
): void

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

function(

name: string,

func: (...args: SupportedValueType[]) => SupportedValueType,
): void

loadExtension(path: string): void

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

open(): void

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

prepare(sql: string): StatementSync

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

класс StatementSync

Использование в Deno

import { StatementSync } from "node:sqlite";

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

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

Конструкторы

StatementSync()

новый

Свойства

expandedSQL: string

только для чтения

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

sourceSQL: string

только для чтения

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

Методы

all(...anonymousParameters: SQLInputValue[]): Record<string, SQLOutputValue>[]

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

all(

namedParameters: Record<string, SQLInputValue>,

...anonymousParameters: SQLInputValue[],
): Record<string, SQLOutputValue>[]

get(...anonymousParameters: SQLInputValue[]): Record<string, SQLOutputValue> | undefined

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

get(

namedParameters: Record<string, SQLInputValue>,

...anonymousParameters: SQLInputValue[],
): Record<string, SQLOutputValue> | undefined

iterate(...anonymousParameters: SQLInputValue[]): Iterator<Record<string, SQLOutputValue>>

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

iterate(

namedParameters: Record<string, SQLInputValue>,

...anonymousParameters: SQLInputValue[],
): Iterator<Record<string, SQLOutputValue>>

run(...anonymousParameters: SQLInputValue[]): StatementResultingChanges

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

run(

namedParameters: Record<string, SQLInputValue>,

...anonymousParameters: SQLInputValue[],
): StatementResultingChanges

setAllowBareNamedParameters(enabled: boolean): void

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

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

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

setReadBigInts(enabled: boolean): void

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

интерфейс ApplyChangesetOptions

Использование в Deno

import { type ApplyChangesetOptions } from "node:sqlite";

Свойства

filter: ((tableName: string) => boolean) | undefined

необязательный

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

onConflict: ((conflictType: number) => number) | undefined

необязательный

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

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.

интерфейс CreateSessionOptions

Использование в Deno

import { type CreateSessionOptions } from "node:sqlite";

Свойства

table: string | undefined

необязательный

Конкретная таблица, изменения в которой нужно отслеживать. По умолчанию отслеживаются изменения во всех таблицах.

db: string | undefined

необязательный

Имя отслеживаемой базы данных. Это полезно, если с помощью ATTACH DATABASE было добавлено несколько баз данных.

интерфейс DatabaseSyncOptions

Использование в Deno

import { type DatabaseSyncOptions } from "node:sqlite";

Свойства

open: boolean | undefined

необязательный

Если true, база данных открывается конструктором. Если это значение равно false, базу данных необходимо открыть с помощью метода open().

enableForeignKeyConstraints: boolean | undefined

необязательный

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

enableDoubleQuotedStringLiterals: boolean | undefined

необязательный

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

readOnly: boolean | undefined

необязательный

Если true, база данных открывается в режиме только для чтения. Если база данных не существует, открыть её не удастся.

allowExtension: boolean | undefined

необязательный

Если true, включаются функция SQL loadExtension и метод loadExtension(). Позже можно вызвать enableLoadExtension(false), чтобы отключить эту возможность.

интерфейс FunctionOptions

Использование в Deno

import { type FunctionOptions } from "node:sqlite";

Свойства

deterministic: boolean | undefined

необязательный

Если true, для созданной функции устанавливается флаг SQLITE_DETERMINISTIC.

directOnly: boolean | undefined

необязательный

Если true, для созданной функции устанавливается флаг SQLITE_DIRECTONLY.

useBigIntArguments: boolean | undefined

необязательный

Если true, целочисленные аргументы function преобразуются в значения BigInt. Если false, целочисленные аргументы передаются как числа JavaScript.

varargs: boolean | undefined

необязательный

Если true, function может принимать переменное число аргументов. Если false, function необходимо вызывать ровно с function.length аргументами.

интерфейс Session

Использование в Deno

import { type Session } from "node:sqlite";

Методы

changeset(): Uint8Array

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

patchset(): Uint8Array

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

close(): void

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

интерфейс StatementResultingChanges

Использование в Deno

import { type StatementResultingChanges } from "node:sqlite";

Свойства

changes: number | bigint

Количество строк, изменённых, добавленных или удалённых последним завершённым оператором INSERT, UPDATE или DELETE. Это поле содержит число или BigInt — в зависимости от конфигурации подготовленного оператора. Значение этого свойства соответствует результату sqlite3_changes64().

lastInsertRowid: number | bigint

Идентификатор последней вставленной строки (rowid). Это поле содержит число или BigInt — в зависимости от конфигурации подготовленного оператора. Значение этого свойства соответствует результату sqlite3_last_insert_rowid().

пространство имён constants

Использование в Deno

import { constants } from "node:sqlite";

Переменные

constants.SQLITE_CHANGESET_ABORT

Прервать выполнение при конфликте изменений и выполнить откат базы данных.

constants.SQLITE_CHANGESET_CONFLICT

Эта константа передаётся обработчику конфликтов при обработке изменения INSERT, если операция приведёт к дублированию значений первичного ключа.

constants.SQLITE_CHANGESET_DATA

Обработчик конфликтов вызывается с этой константой при обработке изменения DELETE или UPDATE, если в базе данных присутствует строка с необходимыми полями PRIMARY KEY, но одно или несколько других полей (не являющихся первичным ключом), изменённых при обновлении, содержат значения, не соответствующие ожидаемым значениям «до».

constants.SQLITE_CHANGESET_FOREIGN_KEY

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

constants.SQLITE_CHANGESET_NOTFOUND

Обработчик конфликтов вызывается с этой константой при обработке изменения DELETE или UPDATE, если в базе данных отсутствует строка с необходимыми полями PRIMARY KEY.

constants.SQLITE_CHANGESET_OMIT

Конфликтующие изменения пропускаются.

constants.SQLITE_CHANGESET_REPLACE

Конфликтующие изменения заменяют существующие значения. Обратите внимание, что это значение может быть возвращено, только если тип конфликта — SQLITE_CHANGESET_DATA или SQLITE_CHANGESET_CONFLICT.

псевдоним типа SQLInputValue

нестабильный

Использование в Deno

import { type SQLInputValue } from "node:sqlite";

Совместимость с Deno

Этот модуль добавлен в Deno v2.2.

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

import sqlite from 'node:sqlite';

Этот модуль доступен только по схеме node:. Следующий вариант не будет работать:

import sqlite from 'sqlite';

В следующем примере показано базовое использование модуля 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' } ]

Определение


null
 | number
 | bigint
 | string
 | ArrayBufferView

См. также

исходный код

псевдоним типа SQLOutputValue

Использование в Deno

import { type SQLOutputValue } from "node:sqlite";

Определение


null
 | number
 | bigint
 | string
 | Uint8Array

псевдоним типа SupportedValueType

Использование в Deno

import { type SupportedValueType } from "node:sqlite";

Устарело

Вместо этого используйте SQLInputValue или SQLOutputValue.

Определение

SQLOutputValue

переменная constants.SQLITE_CHANGESET_ABORT

Использование в Deno

import { constants } from "node:sqlite";

import { constants } from "node:sqlite";

Конфликтующие изменения пропускаются.

Тип

number

переменная constants.SQLITE_CHANGESET_REPLACE

Использование в Deno

import { constants } from "node:sqlite";

Тип

number