SQLite

稳定性: 1.1 - 活跃开发。使用 --experimental-sqlitecli.md#--experimental-sqlite CLI 标志启用此 API。

node:sqlite 模块简化了与 SQLite 数据库的交互。要访问它，可以使用以下方式：

import sqlite from 'node:sqlite';

const sqlite = require('node:sqlite');

此模块仅在 node: 方案下可用。以下方式将无法工作：

import sqlite from 'sqlite';

const sqlite = require('sqlite');

以下示例展示了如何使用 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' } ]

'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

此类表示与 SQLite 数据库的单个 连接https://www.sqlite.org/c3ref/sqlite3.html。该类暴露的所有 API 都是同步执行的。

new DatabaseSync(location[, options])

• location {string} 数据库的位置。SQLite 数据库可以存储在文件中或完全 在内存中https://www.sqlite.org/inmemorydb.html. 要使用文件支持的数据库，location 应该是一个文件路径。要使用内存数据库，location 应该是特殊名称 ':memory:'。
• options {Object} 数据库连接的配置选项。支持以下选项：
  • open {boolean} 如果为 true，构造函数会打开数据库。当该值为 false 时，必须通过 open() 方法打开数据库。默认值: true。

构造一个新的 DatabaseSync 实例。

database.close()

关闭数据库连接。如果数据库未打开，将抛出异常。该方法是 sqlite3_close_v2()https://www.sqlite.org/c3ref/close.html 的封装。

database.exec(sql)

• sql {string} 要执行的 SQL 字符串。

此方法允许执行一个或多个 SQL 语句而不返回任何结果。此方法在执行从文件读取的 SQL 语句时非常有用。该方法是 sqlite3_exec()https://www.sqlite.org/c3ref/exec.html 的封装。

database.open()

打开 DatabaseSync 构造函数中指定位置的数据库。当数据库未通过构造函数打开时，应该使用此方法。数据库已打开时，抛出异常。

database.prepare(sql)

• sql {string} 要编译为准备好的语句的 SQL 字符串。
• 返回: {StatementSync} 准备好的语句。

将 SQL 语句编译为 准备好的语句https://www.sqlite.org/c3ref/stmt.html. 此方法是 sqlite3_prepare_v2()https://www.sqlite.org/c3ref/prepare.html 的封装。

类: StatementSync

此类表示单个 准备好的语句https://www.sqlite.org/c3ref/stmt.html. 该类不能通过其构造函数实例化。相反，实例是通过 database.prepare() 方法创建的。该类暴露的所有 API 都是同步执行的。

准备好的语句是创建它们的 SQL 的高效二进制表示。准备好的语句是可参数化的，并且可以多次使用不同的绑定值。参数还提供了防止 SQL 注入https://en.wikipedia.org/wiki/SQL_injection 攻击的保护。因此，在处理用户输入时，推荐使用准备好的语句而不是手工编写的 SQL 字符串。

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

• namedParameters {Object} 可选对象，用于绑定命名参数。该对象的键用于配置映射。
• ...anonymousParameters {null|number|bigint|string|Buffer|Uint8Array} 一个或多个值，用于绑定匿名参数。
• 返回: {Array} 一个对象数组。每个对象对应于执行准备好的语句返回的一行。每个对象的键和值对应于行的列名和值。

此方法执行准备好的语句并将所有结果作为对象数组返回。如果准备好的语句没有返回任何结果，则此方法返回一个空数组。准备好的语句 参数被绑定https://www.sqlite.org/c3ref/bind_blob.html 使用 namedParameters 和 anonymousParameters 中的值。

statement.expandedSQL()

• 返回: {string} 扩展到包含参数值的源 SQL。

此方法返回准备好的语句的源 SQL，其中参数占位符被最近执行该准备好的语句时使用的值替换。该方法是 sqlite3_expanded_sql()https://www.sqlite.org/c3ref/expanded_sql.html 的封装。

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

• namedParameters {Object} 可选对象，用于绑定命名参数。该对象的键用于配置映射。
• ...anonymousParameters {null|number|bigint|string|Buffer|Uint8Array} 一个或多个值，用于绑定匿名参数。
• 返回: {Object|undefined} 一个对象，代表执行准备好的语句返回的第一行。对象的键和值对应于行的列名和值。如果数据库没有返回任何行，则此方法返回 undefined。

此方法执行准备好的语句并返回第一条结果作为对象。如果准备好的语句没有返回任何结果，则此方法返回 undefined。准备好的语句 参数被绑定https://www.sqlite.org/c3ref/bind_blob.html 使用 namedParameters 和 anonymousParameters 中的值。

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

• namedParameters {Object} 可选对象，用于绑定命名参数。该对象的键用于配置映射。
• ...anonymousParameters {null|number|bigint|string|Buffer|Uint8Array} 一个或多个值，用于绑定匿名参数。
• 返回: {Object}
  • changes: {number|bigint} 最近完成的 INSERT、UPDATE 或 DELETE 语句修改、插入或删除的行数。此字段是一个数字或 BigInt，取决于准备好的语句的配置。此属性是 sqlite3_changes64()https://www.sqlite.org/c3ref/changes.html 的结果。
  • lastInsertRowid: {number|bigint} 最近插入的行的 rowid。此字段是一个数字或 BigInt，取决于准备好的语句的配置。此属性是 sqlite3_last_insert_rowid()https://www.sqlite.org/c3ref/last_insert_rowid.html 的结果。

此方法执行准备好的语句并返回一个总结结果的对象。准备好的语句 参数被绑定https://www.sqlite.org/c3ref/bind_blob.html 使用 namedParameters 和 anonymousParameters 中的值。

statement.setAllowBareNamedParameters(enabled)

• enabled {boolean} 启用或禁用对未带前缀字符的命名参数的支持。

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

为了改善易用性，可以使用此方法来允许裸命名参数，这些参数在 JavaScript 代码中不需要前

缀字符。但要注意以下几个问题：

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

statement.setReadBigInts(enabled)

• enabled {boolean} 启用或禁用在读取 INTEGER 字段时使用 BigInt。

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

statement.sourceSQL()

• 返回: {string} 用于创建此准备好的语句的源 SQL。

此方法返回准备好的语句的源 SQL。该方法是 sqlite3_sql()https://www.sqlite.org/c3ref/expanded_sql.html 的封装。

JavaScript 和 SQLite 之间的类型转换

在 Node.js 写入或读取 SQLite 时，需要在 JavaScript 数据类型和 SQLite 的 数据类型https://www.sqlite.org/datatype3.html. 由于 JavaScript 支持比 SQLite 更多的数据类型，因此仅支持子集 JavaScript 类型。尝试将不受支持的数据类型写入 SQLite 将导致异常。