Node.js v25.0.0 文档

new DatabaseSync(path[, options])#

• path <string> | <Buffer> | <URL> 数据库的路径。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，则启用 loadExtension SQL 函数和 loadExtension() 方法。您可以稍后调用 enableLoadExtension(false) 来禁用此功能。默认值：false。
  • timeout <number> 繁忙超时时间（以毫秒为单位）。这是 SQLite 在返回错误前等待数据库锁释放的最长时间。默认值：0。
  • readBigInts <boolean> 如果为 true，整数字段将作为 JavaScript BigInt 值读取。如果为 false，整数字段将作为 JavaScript 数字读取。默认值：false。
  • returnArrays <boolean> 如果为 true，查询结果将作为数组而不是对象返回。默认值：false。
  • allowBareNamedParameters <boolean> 如果为 true，则允许绑定没有前缀字符的命名参数（例如，foo 而不是 :foo）。默认值：true。
  • allowUnknownNamedParameters <boolean> 如果为 true，绑定时将忽略未知的命名参数。如果为 false，则会对未知的命名参数抛出异常。默认值：false。

构造一个新的 DatabaseSync 实例。

database.aggregate(name, options)#

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

• name <string> 要创建的 SQLite 函数的名称。
• options <Object> 函数配置设置。
  • deterministic <boolean> 如果为 true，则在创建的函数上设置 SQLITE_DETERMINISTIC 标志。默认值：false。
  • directOnly <boolean> 如果为 true，则在创建的函数上设置 SQLITE_DIRECTONLY 标志。默认值：false。
  • useBigIntArguments <boolean> 如果为 true，则传递给 options.step 和 options.inverse 的整数参数将转换为 BigInt。如果为 false，整数参数将作为 JavaScript 数字传递。默认值：false。
  • varargs <boolean> 如果为 true，options.step 和 options.inverse 可以使用任意数量的参数调用（介于零和 SQLITE_MAX_FUNCTION_ARG 之间）。如果为 false，则 inverse 和 step 必须使用确切的 length 个参数调用。默认值：false。
  • start <number> | <string> | <null> | <Array> | <Object> | <Function> 聚合函数的初始值。该值在聚合函数初始化时使用。当传入 <Function> 时，初始值将是其返回值。
  • step <Function> 对聚合中的每一行调用的函数。该函数接收当前状态和行值。此函数的返回值应为新的状态。
  • result <Function> 用于获取聚合结果的函数。该函数接收最终状态，并应返回聚合的结果。
  • inverse <Function> 提供此函数后，aggregate 方法将作为窗口函数工作。该函数接收当前状态和被移除的行值。此函数的返回值应为新的状态。

当用作窗口函数时，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 }import { DatabaseSync } from '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 }copy

database.close()#

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

database.loadExtension(path)#

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

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

database.enableLoadExtension(allow)#

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

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

database.location([dbName])#

• dbName <string> 数据库的名称。可以是 'main'（默认主数据库）或使用 ATTACH DATABASE 添加的任何其他数据库。默认值：'main'。
• 返回：<string> | <null> 数据库文件的位置。当使用内存数据库时，此方法返回 null。

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

database.exec(sql)#

• sql <string> 要执行的 SQL 字符串。

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

database.function(name[, options], function)#

• 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 可以使用任意数量的参数调用（介于零和 SQLITE_MAX_FUNCTION_ARG 之间）。如果为 false，则 function 必须使用确切的 function.length 个参数调用。默认值：false。
• function <Function> 在调用 SQLite 函数时要调用的 JavaScript 函数。此函数的返回值应为有效的 SQLite 数据类型：请参阅JavaScript 和 SQLite 之间的类型转换。如果返回值为 undefined，则结果默认为 NULL。

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

database.setAuthorizer(callback)#

• callback <Function> | <null> 要设置的授权函数，或 null 以清除当前授权函数。

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

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

• actionCode <number> 正在执行的操作类型（例如，SQLITE_INSERT, SQLITE_UPDATE, SQLITE_SELECT）。
• arg1 <string> | <null> 第一个参数（取决于上下文，通常是表名）。
• arg2 <string> | <null> 第二个参数（取决于上下文，通常是列名）。
• dbName <string> | <null> 数据库的名称。
• triggerOrView <string> | <null> 导致访问的触发器或视图的名称。

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

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

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

// Set up an authorizer that denies all table creation
db.setAuthorizer((actionCode) => {
  if (actionCode === constants.SQLITE_CREATE_TABLE) {
    return constants.SQLITE_DENY;
  }
  return constants.SQLITE_OK;
});

// This will work
db.prepare('SELECT 1').get();

// This will throw an error due to authorization denial
try {
  db.exec('CREATE TABLE blocked (id INTEGER)');
} catch (err) {
  console.log('Operation blocked:', err.message);
}import { DatabaseSync, constants } from 'node:sqlite';
const db = new DatabaseSync(':memory:');

// Set up an authorizer that denies all table creation
db.setAuthorizer((actionCode) => {
  if (actionCode === constants.SQLITE_CREATE_TABLE) {
    return constants.SQLITE_DENY;
  }
  return constants.SQLITE_OK;
});

// This will work
db.prepare('SELECT 1').get();

// This will throw an error due to authorization denial
try {
  db.exec('CREATE TABLE blocked (id INTEGER)');
} catch (err) {
  console.log('Operation blocked:', err.message);
}copy

database.isOpen#

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

database.isTransaction#

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

database.open()#

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

database.prepare(sql)#

• sql <string> 要编译为预编译语句的 SQL 字符串。
• 返回：<StatementSync> 预编译语句。

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

database.createTagStore([maxSize])#

• maxSize <integer> 要缓存的预编译语句的最大数量。默认值：1000。
• 返回：<SQLTagStore> 用于缓存预编译语句的新 SQL 标签存储。

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

当执行一个带标签的 SQL 字面量时，SQLTagStore 会检查缓存中是否已存在该特定 SQL 字符串的预编译语句。如果存在，则使用缓存的语句。如果不存在，则创建一个新的预编译语句，执行它，然后将其存储在缓存中以备将来使用。这种机制有助于避免重复解析和准备相同 SQL 语句的开销。

import { DatabaseSync } from 'node:sqlite';

const db = new DatabaseSync(':memory:');
const sql = db.createTagStore();

db.exec('CREATE TABLE users (id INT, name TEXT)');

// Using the 'run' method to insert data.
// The tagged literal is used to identify the prepared statement.
sql.run`INSERT INTO users VALUES (1, 'Alice')`;
sql.run`INSERT INTO users VALUES (2, 'Bob')`;

// Using the 'get' method to retrieve a single row.
const id = 1;
const user = sql.get`SELECT * FROM users WHERE id = ${id}`;
console.log(user); // { id: 1, name: 'Alice' }

// Using the 'all' method to retrieve all rows.
const allUsers = sql.all`SELECT * FROM users ORDER BY id`;
console.log(allUsers);
// [
//   { id: 1, name: 'Alice' },
//   { id: 2, name: 'Bob' }
// ] copy

database.createSession([options])#

• options <Object> 会话的配置选项。
  • table <string> 要跟踪更改的特定表。默认情况下，跟踪所有表的更改。
  • db <string> 要跟踪的数据库名称。当使用 ATTACH DATABASE 添加了多个数据库时，此选项很有用。默认值：'main'。
• 返回：<Session> 会话句柄。

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

database.applyChangeset(changeset[, options])#

• changeset <Uint8Array> 二进制变更集或补丁集。
• options <Object> 应用更改方式的配置选项。

  • filter <Function> 跳过那些当目标表名提供给此函数时返回真值的更改。默认情况下，尝试所有更改。

  • onConflict <Function> 一个确定如何处理冲突的函数。该函数接收一个参数，该参数可以是以下值之一：

    • 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 的函数。

• 返回：<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. copy

database[Symbol.dispose]()#

关闭数据库连接。如果数据库连接已经关闭，则此操作无效。

session.changeset()#

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

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

session.patchset()#

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

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

session.close().#

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

sqlTagStore.all(sqlTemplate[, ...values])#

• sqlTemplate <Template Literal> 包含 SQL 查询的模板字面量。
• ...values <any> 要插入到模板字面量中的值。
• 返回：<Array> 一个表示查询返回的行的对象数组。

执行给定的 SQL 查询并以对象数组的形式返回所有结果行。

sqlTagStore.get(sqlTemplate[, ...values])#

• sqlTemplate <Template Literal> 包含 SQL 查询的模板字面量。
• ...values <any> 要插入到模板字面量中的值。
• 返回：<Object> | <undefined> 一个表示查询返回的第一行的对象，如果没有返回行，则为 undefined。

执行给定的 SQL 查询并以对象形式返回第一个结果行。

sqlTagStore.iterate(sqlTemplate[, ...values])#

• sqlTemplate <Template Literal> 包含 SQL 查询的模板字面量。
• ...values <any> 要插入到模板字面量中的值。
• 返回：<Iterator> 一个迭代器，该迭代器生成表示查询返回的行的对象。

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

sqlTagStore.run(sqlTemplate[, ...values])#

• sqlTemplate <Template Literal> 包含 SQL 查询的模板字面量。
• ...values <any> 要插入到模板字面量中的值。
• 返回：<Object> 一个包含执行信息的对象，包括 changes 和 lastInsertRowid。

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

sqlTagStore.size()#

• 返回：<integer> 缓存中当前预编译语句的数量。

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

sqlTagStore.capacity#

• 返回：<integer> 缓存可以容纳的预编译语句的最大数量。

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

sqlTagStore.db#

• <DatabaseSync> 创建此 SQLTagStore 的 DatabaseSync 实例。

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

sqlTagStore.reset()#

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

sqlTagStore.clear()#

sqlTagStore.reset() 的别名。

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

• namedParameters <Object> 一个可选对象，用于绑定命名参数。此对象的键用于配置映射。
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <TypedArray> | <DataView> 零个或多个要绑定到匿名参数的值。
• 返回：<Array> 对象数组。每个对象对应于执行预编译语句返回的一行。每个对象的键和值对应于该行的列名和值。

此方法执行一个预编译语句并以对象数组的形式返回所有结果。如果预编译语句不返回任何结果，此方法返回一个空数组。预编译语句的参数会使用 namedParameters 和 anonymousParameters 中的值进行绑定。

statement.columns()#

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

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

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

statement.expandedSQL#

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

预编译语句的源 SQL 文本，其中参数占位符被最近一次执行此预编译语句时使用的值所替换。此属性是 sqlite3_expanded_sql() 的包装器。

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

• namedParameters <Object> 一个可选对象，用于绑定命名参数。此对象的键用于配置映射。
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <TypedArray> | <DataView> 零个或多个要绑定到匿名参数的值。
• 返回：<Object> | <undefined> 一个对应于执行预编译语句返回的第一行的对象。对象的键和值对应于该行的列名和值。如果数据库没有返回任何行，则此方法返回 undefined。

此方法执行一个预编译语句并以对象形式返回第一个结果。如果预编译语句不返回任何结果，此方法返回 undefined。预编译语句的参数会使用 namedParameters 和 anonymousParameters 中的值进行绑定。

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

• namedParameters <Object> 一个可选对象，用于绑定命名参数。此对象的键用于配置映射。
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <TypedArray> | <DataView> 零个或多个要绑定到匿名参数的值。
• 返回：<Iterator> 一个可迭代的对象迭代器。每个对象对应于执行预编译语句返回的一行。每个对象的键和值对应于该行的列名和值。

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

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

• namedParameters <Object> 一个可选对象，用于绑定命名参数。此对象的键用于配置映射。
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <TypedArray> | <DataView> 零个或多个要绑定到匿名参数的值。
• 返回：<Object>
  • changes <number> | <bigint> 最近完成的 INSERT、UPDATE 或 DELETE 语句修改、插入或删除的行数。此字段是数字或 BigInt，具体取决于预编译语句的配置。此属性是 sqlite3_changes64() 的结果。
  • lastInsertRowid <number> | <bigint> 最近插入的 rowid。此字段是数字或 BigInt，具体取决于预编译语句的配置。此属性是 sqlite3_last_insert_rowid() 的结果。

此方法执行一个预编译语句并返回一个总结结果更改的对象。预编译语句的参数会使用 namedParameters 和 anonymousParameters 中的值进行绑定。

statement.setAllowBareNamedParameters(enabled)#

• enabled <boolean> 启用或禁用对不带前缀字符的命名参数绑定的支持。

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

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

• 在 SQL 中仍然需要前缀字符。
• 在 JavaScript 中仍然允许使用前缀字符。实际上，带前缀的名称会有稍好的绑定性能。
• 在同一个预编译语句中使用模糊的命名参数，如 $k 和 @k，将导致异常，因为它无法确定如何绑定裸名称。

statement.setAllowUnknownNamedParameters(enabled)#

• enabled <boolean> 启用或禁用对未知命名参数的支持。

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

statement.setReturnArrays(enabled)#

• enabled <boolean> 启用或禁用以数组形式返回查询结果。

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

statement.setReadBigInts(enabled)#

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

从数据库读取时，SQLite 的 INTEGER 默认映射为 JavaScript 数字。然而，SQLite 的 INTEGER 可以存储比 JavaScript 数字所能表示的更大的值。在这种情况下，此方法可用于使用 JavaScript 的 BigInt 读取 INTEGER 数据。此方法对数据库写入操作没有影响，因为数字和 BigInt 在任何时候都受支持。

statement.sourceSQL#

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

预编译语句的源 SQL 文本。此属性是 sqlite3_sql() 的包装器。

JavaScript 和 SQLite 之间的类型转换#

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

SQLite 常量#

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