SQLite

新增于: v22.5.0

[稳定性: 1 - 实验性]

稳定性: 1 稳定性: 1.1 - 活跃开发中。

源代码: lib/sqlite.js

node:sqlite 模块简化了与 SQLite 数据库的交互。访问方法如下：

ESM

import sqlite from 'node:sqlite'

CJS

const sqlite = require('node:sqlite')

此模块仅在 node: 模式下可用。

以下示例演示了 node:sqlite 模块的基本用法，包括打开内存数据库、写入数据以及读取数据。

ESM

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' } ]

CJS

'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 <字符串> 数据库的位置。SQLite 数据库可以存储在文件中，也可以完全存储在内存中。要使用基于文件的数据库，位置应为文件路径。要使用内存数据库，位置应为特殊名称':memory:'。
• options <对象> 数据库连接的配置选项。支持以下选项：
  • open <布尔值> 如果为 true，则构造函数会打开数据库。如果此值为 false，则必须通过 open() 方法打开数据库。默认值： true。
  • readOnly <布尔值> 如果为 true，则以只读模式打开数据库。如果数据库不存在，则打开数据库将失败。默认值： false。
  • enableForeignKeyConstraints <布尔值> 如果为 true，则启用外键约束。这是推荐的做法，但可以为与旧版数据库模式的兼容性而禁用。可以使用 PRAGMA foreign_keys 在打开数据库后启用和禁用外键约束的强制执行。默认值： true。
  • enableDoubleQuotedStringLiterals <布尔值> 如果为 true，则 SQLite 将接受双引号字符串文字。这不推荐，但可以为与旧版数据库模式的兼容性而启用。默认值： false。
  • allowExtension <布尔值> 如果为 true，则启用 loadExtension SQL 函数和 loadExtension() 方法。您可以稍后调用 enableLoadExtension(false) 来禁用此功能。默认值： false。

构造一个新的 DatabaseSync 实例。

database.close()

新增于：v22.5.0

关闭数据库连接。如果数据库未打开，则会抛出异常。此方法是 sqlite3_close_v2() 的包装器。

database.loadExtension(path)

新增于：v23.5.0

• path <string> 要加载的共享库的路径。

将共享库加载到数据库连接中。此方法是 sqlite3_load_extension() 的包装器。构建 DatabaseSync 实例时，需要启用 allowExtension 选项。

database.enableLoadExtension(allow)

新增于：v23.5.0

• allow <boolean> 是否允许加载扩展。

启用或禁用 loadExtension SQL 函数和 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 的整数参数转换为 BigInt。如果为 false，则将整数参数作为 JavaScript 数字传递。默认值： false。
  • varargs <boolean> 如果为 true，则 function 可以接受可变数量的参数。如果为 false，则必须使用 exactly function.length 个参数调用 function。默认值： false。

• function <Function> 调用 SQLite 函数时要调用的 JavaScript 函数。

此方法用于创建 SQLite 用户定义函数。此方法是 sqlite3_create_function_v2() 的包装器。

database.open()

新增于：v22.5.0

打开DatabaseSync构造函数的location参数中指定的数据库。只有当数据库不是通过构造函数打开时才应该使用此方法。如果数据库已打开，则会抛出异常。

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> 二进制 changeset 或 patchset。

• options <Object> 应用更改的配置选项。

  • filter <Function> 跳过更改，当目标表名称提供给此函数时，返回真值。默认情况下，所有更改都会尝试。
  • onConflict <number> 确定如何处理冲突。默认: SQLITE_CHANGESET_ABORT。
  • SQLITE_CHANGESET_OMIT: 忽略冲突的更改。
  • SQLITE_CHANGESET_REPLACE: 冲突的更改替换现有值。
  • SQLITE_CHANGESET_ABORT: 冲突时中止并回滚数据库。

• 返回: <boolean> changeset 是否已成功应用而未中止。

如果数据库未打开，则会抛出异常。此方法是 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)
// 现在 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 <布尔值> 启用或禁用对不带前缀字符的命名参数绑定的支持。

SQLite 参数的名称以一个前缀字符开头。默认情况下，node:sqlite 要求在绑定参数时必须存在此前缀字符。但是，除了美元符号字符外，这些前缀字符在用作对象键时也需要额外的引号。

为了提高人体工程学，此方法也可用于允许不带前缀的命名参数，这些参数在 JavaScript 代码中不需要前缀字符。启用不带前缀的命名参数时，需要注意以下几点：

• SQL 中仍然需要前缀字符。
• JavaScript 中仍然允许使用前缀字符。事实上，带前缀的名称将具有略微更好的绑定性能。
• 在同一个预处理语句中使用模棱两可的命名参数，例如 $k 和 @k，将导致异常，因为它无法确定如何绑定不带前缀的名称。

statement.setReadBigInts(enabled)

新增于: v22.5.0

• enabled <boolean> 启用或禁用从数据库读取 INTEGER 字段时使用 BigInt。

从数据库读取时，SQLite INTEGER 默认映射到 JavaScript 数字。但是，SQLite INTEGER 可以存储大于 JavaScript 数字所能表示的值。在这种情况下，可以使用此方法使用 JavaScript BigInt 读取 INTEGER 数据。此方法对数据库写入操作没有影响，因为始终同时支持数字和 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

• <对象>

一个包含常用 SQLite 操作常量的对象。

SQLite 常量

sqlite.constants 对象导出以下常量。

冲突解决常量

以下常量用于 database.applyChangeset()。

常量	描述
SQLITE_CHANGESET_OMIT	忽略冲突的更改。
SQLITE_CHANGESET_REPLACE	冲突的更改替换现有值。
SQLITE_CHANGESET_ABORT	当更改遇到冲突时中止并回滚数据库。