稳定性：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 写入或从 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 都是同步执行的。

构造一个新的 DatabaseSync 实例。

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

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

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

// 使用从文件名推导出的入口点进行加载。
database.loadExtension('./decimal.dylib');

// 当推导出的名称不匹配时覆盖入口点。
database.loadExtension('./base64.dylib', 'sqlite3_base64_init');

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

启用或禁用防御性标志。当防御性标志处于活动状态时，允许普通 SQL 有意损坏数据库文件的语言特性将被禁用。 有关更多信息，请参阅 SQLite 文档中的 SQLITE_DBCONFIG_DEFENSIVE。

此方法是对 sqlite3_db_filename() 的封装。

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

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

设置一个授权器回调，当 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('操作被阻止：', err.message);
}

一个用于在运行时获取和设置 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 会将该限制重置为其编译时最大值。

将数据库序列化为二进制表示，并以 Uint8Array 形式返回。 这对于保存、克隆或传输内存数据库很有用。此方法是对 sqlite3_serialize() 的封装。

import { DatabaseSync } from 'node:sqlite';

const db = new DatabaseSync(':memory:');
db.exec('CREATE TABLE t(key INTEGER PRIMARY KEY, value TEXT)');
db.exec("INSERT INTO t VALUES (1, 'hello')");
const buffer = db.serialize();
console.log(buffer.length); // 打印数据库的字节长度

将一个已序列化的数据库加载到此连接中，替换当前数据库。反序列化后的数据库是可写的。即使操作随后失败，现有的预编译语句也会在尝试反序列化之前被终结。此方法是对 sqlite3_deserialize() 的封装。

import { DatabaseSync } from 'node:sqlite';

const original = new DatabaseSync(':memory:');
original.exec('CREATE TABLE t(key INTEGER PRIMARY KEY, value TEXT)');
original.exec("INSERT INTO t VALUES (1, 'hello')");
const buffer = original.serialize();
original.close();

const clone = new DatabaseSync(':memory:');
clone.deserialize(buffer);
console.log(clone.prepare('SELECT value FROM t').get());
// 打印： { value: 'hello' }

将 SQL 语句编译为 [预编译语句][]。此方法是对 sqlite3_prepare_v2() 的封装。

创建一个新的 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' }
// ]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

此方法进行数据库备份。此方法抽象了 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 操作常用常量的对象。

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

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

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

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

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