Node.js v24.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。

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

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

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.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 更改不包含预期的 "before" 值。
    • 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() 的封装。

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> 对象的iterable迭代器。每个对象对应于执行预处理语句返回的行。每个对象的键和值对应于行的列名和值。

此方法执行预处理语句，并返回对象的迭代器。如果预处理语句未返回任何结果，则此方法返回一个空迭代器。预处理语句的参数绑定使用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.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 对象导出。