SQLite

稳定性：1.2 - 发布候选版本。

node:sqlite 模块用于方便地操作 SQLite 数据库。 要访问它：

import sqlite from 'node:sqlite';

此模块仅在 node: 方案下可用。

以下示例展示了 node:sqlite 模块的基本用法，用于打开 一个内存数据库，向数据库写入数据，然后读回数据。

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

当 Node.js 写入或读取 SQLite 时，需要在 JavaScript 数据类型和 SQLite 的 [数据类型][] 之间进行转换。因为 JavaScript 支持 比 SQLite 更多的数据类型，所以只支持 JavaScript 类型的子集。 尝试将不支持的数据类型写入 SQLite 将导致 异常。

从 SQLite 读取值的 API 有一个配置选项，用于确定 INTEGER 值在 JavaScript 中是转换为 number 还是 bigint， 例如语句的 readBigInts 选项和用户定义函数的 useBigIntArguments 选项。如果 Node.js 从 SQLite 读取的 INTEGER 值超出 JavaScript [安全整数][] 范围，且未启用读取 BigInt 的选项，则将抛出 ERR_OUT_OF_RANGE 错误。

此类表示到 SQLite 数据库的单个 [连接][]。此类暴露的所有 API 均同步执行。

new DatabaseSync(path, options?): void

构造一个新的 DatabaseSync 实例。

database.aggregate(name, options): void

向 SQLite 数据库注册一个新的聚合函数。此方法是 sqlite3_create_window_function() 的包装器。

当用作窗口函数时，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 }

database.close(): void

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

database.loadExtension(path): void

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

database.enableLoadExtension(allow): void

启用或禁用 loadExtension SQL 函数和 loadExtension() 方法。当构造时 allowExtension 为 false 时，出于安全原因无法启用 加载扩展。

database.enableDefensive(active): void

启用或禁用防御标志。当防御标志激活时， 允许普通 SQL 故意破坏数据库文件的语言功能将被禁用。 详见 SQLite 文档中的 SQLITE_DBCONFIG_DEFENSIVE。

database.location(dbName?): void

此方法是 sqlite3_db_filename() 的包装器。

database.exec(sql): void

此方法允许执行一个或多个 SQL 语句而不返回 任何结果。当执行从文件读取的 SQL 语句时，此方法很有用。此方法是 sqlite3_exec() 的包装器。

database.function(name, options?, fn): void

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

database.setAuthorizer(callback): void

设置一个授权器回调，每当 SQLite 尝试通过预准备语句 访问数据或修改数据库模式时，将调用该回调。 这可用于实施安全策略、审计访问或限制某些操作。 此方法是 sqlite3_set_authorizer() 的包装器。

调用时，回调接收五个参数：

回调必须返回以下常量之一：

• SQLITE_OK - 允许操作。
• SQLITE_DENY - 拒绝操作（导致错误）。
• SQLITE_IGNORE - 忽略操作（静默跳过）。

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

// 设置一个拒绝所有表创建的授权器
db.setAuthorizer((actionCode) => {
  if (actionCode === constants.SQLITE_CREATE_TABLE) {
    return constants.SQLITE_DENY;
  }
  return constants.SQLITE_OK;
});

// 这将正常工作
db.prepare('SELECT 1').get();

// 由于授权拒绝，这将抛出错误
try {
  db.exec('CREATE TABLE blocked (id INTEGER)');
} catch (err) {
  console.log('Operation blocked:', err.message);
}

• 类型：<boolean> 数据库当前是否打开。

• 类型：<boolean> 数据库当前是否在事务中。此方法 是 sqlite3_get_autocommit() 的包装器。

• 类型：<Object>

一个用于在运行时获取和设置 SQLite 数据库限制的对象。 每个属性对应一个 SQLite 限制，可以读取或写入。

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

// 读取当前限制
console.log(db.limits.length);

// 设置新限制
db.limits.sqlLength = 100000;

// 将限制重置为其编译时最大值
db.limits.sqlLength = Infinity;

可用属性：length、sqlLength、column、exprDepth、 compoundSelect、vdbeOp、functionArg、attach、likePatternLength、 variableNumber、triggerDepth。

将属性设置为 Infinity 会将限制重置为其编译时最大值。

database.open(): void

打开 DatabaseSync 构造函数的 path 参数中指定的数据库。 此方法仅应在数据库未通过构造函数打开时使用。如果数据库已打开，则抛出异常。

database.prepare(sql, options?): void

将 SQL 语句编译为 [预准备语句][]。此方法是 sqlite3_prepare_v2() 的包装器。

database.createTagStore(maxSize?): void

创建一个新的 SQLTagStore，它是一个最近最少使用 (LRU) 缓存， 用于存储预准备语句。这允许通过为预准备语句标记唯一标识符来高效地重用它们。

当执行标记的 SQL 字面量时，SQLTagStore 检查缓存中是否已存在 相应 SQL 查询字符串的预准备语句。如果存在，则使用缓存的语句。如果不存在，则创建 一个新的预准备语句，执行它，然后存储在缓存中供将来使用。此机制 有助于避免重复解析和准备相同 SQL 语句的开销。

标记语句将模板字面量中的占位符值绑定为 底层预准备语句的参数。例如：

sqlTagStore.get`SELECT ${value}`;

等价于：

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

但是，在第一个示例中，标签存储将缓存底层预准备 语句供将来使用。

注意： 标记语句中的 ${value} 语法将参数 绑定 到 预准备语句。这与 未标记 模板字面量中的行为不同，后者执行字符串插值。

// 这是一个将参数绑定到标记语句的安全示例。
sqlTagStore.run`INSERT INTO t1 (id) VALUES (${id})`;

// 这是一个未标记模板字符串的 *不安全* 示例。
// `id` 作为字符串插值到查询文本中。
// 这可能导致 SQL 注入和数据损坏。
db.run(`INSERT INTO t1 (id) VALUES (${id})`);

JavaScriptCopy to clipboard

如果查询字符串（包括任何绑定占位符的位置）相同，则标签存储将从缓存中匹配语句。

// 以下语句将在缓存中匹配：
sqlTagStore.get`SELECT * FROM t1 WHERE id = ${id} AND active = 1`;
sqlTagStore.get`SELECT * FROM t1 WHERE id = ${12345} AND active = 1`;

// 以下语句将不匹配，因为查询字符串
// 和绑定的占位符不同：
sqlTagStore.get`SELECT * FROM t1 WHERE id = ${id} AND active = 1`;
sqlTagStore.get`SELECT * FROM t1 WHERE id = 12345 AND active = 1`;

// 以下语句将不匹配，因为匹配是区分大小写的：
sqlTagStore.get`SELECT * FROM t1 WHERE id = ${id} AND active = 1`;
sqlTagStore.get`select * from t1 where id = ${id} and active = 1`;

在标记语句中绑定参数的唯一方法是使用 ${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)');

// 使用 'run' 方法插入数据。
// 标记字面量用于标识预准备语句。
sql.run`INSERT INTO users VALUES (1, 'Alice')`;
sql.run`INSERT INTO users VALUES (2, 'Bob')`;

// 使用 'get' 方法检索单行。
const name = 'Alice';
const user = sql.get`SELECT * FROM users WHERE name = ${name}`;
console.log(user); // { id: 1, name: 'Alice' }

// 使用 'all' 方法检索所有行。
const allUsers = sql.all`SELECT * FROM users ORDER BY id`;
console.log(allUsers);
// [
//   { id: 1, name: 'Alice' },
//   { id: 2, name: 'Bob' }
// ]

database.createSession(options?): void

创建并将会话附加到数据库。此方法是 sqlite3session_create() 和 sqlite3session_attach() 的包装器。

database.applyChangeset(changeset, options?): void

如果数据库未 打开，则抛出异常。此方法是 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);
// 现在已应用变更集，targetDb 包含与 sourceDb 相同的数据。

database[Symbol.dispose](): void

关闭数据库连接。如果数据库连接已关闭， 则此操作为空操作。

session.changeset(): void

• 返回值：<Uint8Array> 可应用于其他数据库的二进制变更集。

检索自变更集创建以来包含所有变更的变更集。可以被多次调用。 如果数据库或会话未打开，则抛出异常。此方法是对 sqlite3session_changeset() 的封装。

session.patchset(): void

• 返回值：<Uint8Array> 可应用于其他数据库的二进制补丁集。

与上述方法类似，但生成更紧凑的补丁集。请参阅 SQLite 文档中的 [变更集和补丁集][] 。如果数据库或会话未打开，则抛出异常。此方法是 对 sqlite3session_patchset() 的封装。

session.close(): void

关闭会话。如果数据库或会话未打开，则抛出异常。此方法是 对 sqlite3session_delete() 的封装。

session[Symbol.dispose](): void

关闭会话。如果会话已关闭，则不执行任何操作。

此类表示单个 [预准备语句][]。此类不能 通过其构造函数实例化。相反，实例是通过 database.prepare() 方法创建的。此类暴露的所有 API 均执行 同步。

预准备语句是用于创建它的 SQL 的高效二进制表示。预准备语句是可参数化的， 并且可以使用不同的绑定值多次调用。参数还提供针对 SQL 注入 攻击的保护。出于这些原因，在处理用户输入时，预准备语句优于 手工编写的 SQL 字符串。

statement.all(namedParameters?, ...anonymousParameters?): void

此方法执行预准备语句并将所有结果作为对象数组返回。如果预准备语句 不返回任何结果，此方法返回一个空数组。预准备语句 [参数被绑定][] 使用 namedParameters 和 anonymousParameters 中的值。

statement.columns(): void

• 返回值：<Array> 对象数组。每个对象对应于预准备语句中的一列， 并包含以下属性：

  Attributes

  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() 的结果。

此方法用于检索有关预准备语句返回的列的信息。

• 类型：<string> 扩展为包含参数值的源 SQL。

预准备语句的源 SQL 文本，其中参数 占位符已被此预准备语句最近一次执行期间使用的值替换。此属性是 对 sqlite3_expanded_sql() 的封装。

statement.get(namedParameters?, ...anonymousParameters?): void

此方法执行预准备语句并将第一个结果作为对象返回。如果预准备语句 不返回任何结果，此方法返回 undefined。预准备语句 [参数被绑定][] 使用 namedParameters 和 anonymousParameters 中的值。

statement.iterate(namedParameters?, ...anonymousParameters?): void

此方法执行预准备语句并返回对象的迭代器。如果预准备语句 不返回任何结果，此方法返回一个空迭代器。预准备语句 [参数被绑定][] 使用 namedParameters 和 anonymousParameters 中的值。

statement.run(namedParameters?, ...anonymousParameters?): void

此方法执行预准备语句并返回一个总结结果变更的对象。预准备语句 [参数被绑定][] 使用 namedParameters 和 anonymousParameters 中的值。

statement.setAllowBareNamedParameters(enabled): void

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

为了提高易用性，此方法也可用于允许裸命名参数， 即在 JavaScript 代码中不需要前缀字符。启用裸命名参数时有几个 注意事项需要注意：

• SQL 中仍然需要前缀字符。
• JavaScript 中仍然允许前缀字符。事实上，前缀名称 将具有稍好的绑定性能。
• 在同一预准备语句中使用歧义的命名参数，例如 $k 和 @k， 将导致异常，因为无法确定如何绑定 裸名称。

statement.setAllowUnknownNamedParameters(enabled): void

默认情况下，如果在绑定参数时遇到未知名称，则 抛出异常。此方法允许忽略未知的命名参数。

statement.setReturnArrays(enabled): void

启用时，all()、get() 和 iterate() 方法返回的查询结果将作为数组返回，而不是 对象。

statement.setReadBigInts(enabled): void

从数据库读取时，SQLite INTEGER 默认映射到 JavaScript 数字。但是，SQLite INTEGER 可以存储比 JavaScript 数字能够表示的值更大的值。在这种情况下，此方法可用于 使用 JavaScript BigInt 读取 INTEGER 数据。此方法对数据库写入操作 没有影响，其中数字和 BigInt 始终都受支持。

• 类型：<string> 用于创建此预准备语句的源 SQL。

预准备语句的源 SQL 文本。此属性是 对 sqlite3_sql() 的封装。

此类表示一个用于存储预编译语句的单 LRU（最近最少使用）缓存。

此类的实例是通过 database.createTagStore() 方法创建的，而不是使用构造函数。该存储基于提供的 SQL 查询字符串缓存预编译语句。当再次看到相同的查询时，存储会检索缓存的语句并通过参数绑定安全地应用新值，从而防止 SQL 注入等攻击。

缓存有一个默认为 1000 条语句的 maxSize，但可以提供自定义大小（例如，database.createTagStore(100)）。此类暴露的所有 API 均同步执行。

sqlTagStore.all(stringElements, ...boundParameters?): void

执行给定的 SQL 查询并将所有结果行作为对象数组返回。

此函数旨在用作模板字面量标签，而不是直接调用。

sqlTagStore.get(stringElements, ...boundParameters?): void

执行给定的 SQL 查询并将第一行结果作为对象返回。

此函数旨在用作模板字面量标签，而不是直接调用。

sqlTagStore.iterate(stringElements, ...boundParameters?): void

执行给定的 SQL 查询并返回结果行的迭代器。

此函数旨在用作模板字面量标签，而不是直接调用。

sqlTagStore.run(stringElements, ...boundParameters?): void

执行给定的 SQL 查询，预期不返回任何行（例如，INSERT、UPDATE、DELETE）。

此函数旨在用作模板字面量标签，而不是直接调用。

• 类型：<integer>

一个只读属性，返回缓存中当前预编译语句的数量。

• 类型：<integer>

一个只读属性，返回缓存可以容纳的最大预编译语句数量。

• 类型：{DatabaseSync}

一个只读属性，返回与此 SQLTagStore 关联的 DatabaseSync 对象。

sqlTagStore.clear(): void

重置 LRU 缓存，清除所有存储的预编译语句。

sqlite.backup(sourceDb, path, options?): void

• sourceDb {DatabaseSync} 要备份的数据库。源数据库必须处于打开状态。
• path <string> | <URL> 创建备份的路径。如果文件已存在，内容将被覆盖。
• options <Object> 备份的可选配置。支持以下属性：
  Attributes

  source:<string>

  源数据库的名称。可以是  'main' （默认主数据库）或任何已通过 ATTACH DATABASE 添加的其他数据库 默认值： 'main' 。

  target:<string>

  目标数据库的名称。可以是  'main' （默认主数据库）或任何已通过 ATTACH DATABASE 添加的其他数据库 默认值： 'main' 。

  rate:<number>

  每批备份中传输的页数。  默认值： 100 。

  progress:<Function>

  一个可选的回调函数，将在每个备份步骤后调用。传递给此回调的参数是一个 <Object> ，具有  remainingPages 和 totalPages 属性，描述备份操作的当前进度。
• 返回：<Promise> 一个 Promise，完成时 fulfilled 值为备份的总页数，如果发生错误则 rejected。

此方法进行数据库备份。此方法抽象了 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, // 一次复制一页。
    progress: ({ totalPages, remainingPages }) => {
      console.log('Backup in progress', { totalPages, remainingPages });
    },
  });

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

• 类型：<Object>

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

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

以下常量之一可作为传递给 database.applyChangeset() 的 onConflict 冲突解决处理程序的参数。另请参阅 SQLite 文档中的 传递给冲突处理程序的常量。

以下常量之一必须从传递给 database.applyChangeset() 的 onConflict 冲突解决处理程序返回。另请参阅 SQLite 文档中的 从冲突处理程序返回的常量。

以下常量与 database.setAuthorizer() 方法一起使用。

以下常量之一必须从传递给 database.setAuthorizer() 的授权回调函数返回。

以下常量作为第一个参数传递给授权回调函数，以指示正在授权的操作类型。