⚙️ node-sqlite3

Node.js 的异步、非阻塞 SQLite3 绑定。

构建状态

特性

简单直观的查询和参数绑定接口
完整的 Buffer/Blob 支持
广泛的调试支持
查询序列化 API
扩展支持，包括内置支持 json1 扩展
大型测试套件
使用现代 C++ 编写并经过内存泄漏测试
捆绑 SQLite v3.45.0，或者您可以使用本地 SQLite 构建

安装

您可以使用 npm 或 yarn 安装 sqlite3：

（推荐）最新发布版本：

npm install sqlite3
# 或
yarn add sqlite3

GitHub 的 master 分支：npm install https://github.com/tryghost/node-sqlite3/tarball/master

预编译二进制文件

sqlite3 v5+ 重写为使用 Node-API，因此预编译二进制文件不需要为特定 Node 版本构建。sqlite3 目前为 Node-API v3 和 v6 构建。请查看 Node-API 版本矩阵以确保您的 Node 版本支持其中之一。预编译二进制文件应该支持 Node v10+。

该模块使用 prebuild-install 下载适用于您平台的预编译二进制文件（如果存在）。对于 5.0.2 以上版本的 sqlite3，这些二进制文件托管在 GitHub Releases 上，否则托管在 S3 上。目前提供以下目标：

darwin-arm64
darwin-x64
linux-arm64
linux-x64
linuxmusl-arm64
linuxmusl-x64
win32-ia32
win32-x64

不幸的是，prebuild 无法区分 armv6 和 armv7，而是使用 arm 作为 {arch}。在修复之前，您仍需要从源代码安装 sqlite3。

未来可能会添加对其他平台和架构的支持，如果 CI 支持在这些平台上构建的话。

如果您的环境不受支持，它将使用 node-gyp 构建 SQLite，但您需要安装 C++ 编译器和链接器。

其他安装方式

也可以从源代码而不是 npm 包自行构建 sqlite3（见下文）。

如果 node-webkit 包含受支持的 Node.js 引擎版本，sqlite3 模块也可以与 node-webkit 一起使用。（见下文。）

SQLite 的 SQLCipher 扩展也受支持。（见下文。）

API

请参阅 wiki 中的 API 文档。

使用

注意： 使用前必须先安装该模块。

const sqlite3 = require('sqlite3').verbose();
const db = new sqlite3.Database(':memory:');

db.serialize(() => {
    db.run("CREATE TABLE lorem (info TEXT)");

    const stmt = db.prepare("INSERT INTO lorem VALUES (?)");
    for (let i = 0; i < 10; i++) {
        stmt.run("Ipsum " + i);
    }
    stmt.finalize();

    db.each("SELECT rowid AS id, info FROM lorem", (err, row) => {
        console.log(row.id + ": " + row.info);
    });
});

db.close();

从源代码安装

要跳过搜索预编译二进制文件，并强制从源代码构建，请使用

npm install --build-from-source

sqlite3 模块只依赖于 libsqlite3。但默认情况下，将构建并静态链接内部/捆绑的 sqlite 副本，因此不需要外部安装的 sqlite3。

如果您希望安装外部 sqlite，则需要向 npm 包装器传递 --sqlite 参数：

npm install --build-from-source --sqlite=/usr/local

如果要针对外部 sqlite3 进行构建，请确保已安装开发头文件。Mac OS X 默认附带这些文件。如果您没有安装它们，请使用包管理器安装 -dev 包，例如 Debian/Ubuntu 上的 apt-get install libsqlite3-dev。确保您至少安装了 libsqlite3 >= 3.6。

请注意，如果在 OS X 上针对 homebrew 安装的 sqlite 进行构建，您可以执行：

npm install --build-from-source --sqlite=/usr/local/opt/sqlite/

自定义文件头（魔数）

默认的 sqlite 文件头是 "SQLite format 3"。您可以指定不同的魔数，但这将使标准工具和库无法使用您的文件。

npm install --build-from-source --sqlite_magic="MyCustomMagic15"

请注意，魔数必须恰好为 15 个字符长（包括空终止符共 16 字节）。

为 node-webkit 构建

由于 ABI 差异，sqlite3 必须进行自定义构建才能与 node-webkit 一起使用。

要为 node-webkit 构建 sqlite3：

全局安装 nw-gyp：npm install nw-gyp -g （除非已安装）
使用自定义标志 --runtime、--target_arch 和 --target 构建模块：

NODE_WEBKIT_VERSION="0.8.6" # 在 https://github.com/rogerwang/node-webkit#downloads 查看最新版本
npm install sqlite3 --build-from-source --runtime=node-webkit --target_arch=ia32 --target=$(NODE_WEBKIT_VERSION)

您也可以在 sqlite3 检出目录中运行此命令：

npm install --build-from-source --runtime=node-webkit --target_arch=ia32 --target=$(NODE_WEBKIT_VERSION)

请记住以下几点：

您必须提供正确的 --target_arch 标志。ia32 用于针对 32 位 node-webkit 构建，而 x64 将针对 64 位 node-webkit 构建（如果您的平台可用）。
为 node-webkit 构建的 sqlite3 包无法在普通的 Node.js 中运行（反之亦然）。
- 例如，node-webkit 包的 npm test 将失败。

有关更多详细信息，请访问 node-webkit 维基中的"使用 Node 模块"文章。

为 SQLCipher 构建

有关构建 SQLCipher 的说明，请参阅为 Node.js 构建 SQLCipher。或者，您可以使用本地包管理器安装它。

要针对 SQLCipher 运行，您需要通过传递构建选项从源代码编译 sqlite3，如：

npm install sqlite3 --build-from-source --sqlite_libname=sqlcipher --sqlite=/usr/

node -e 'require("sqlite3")'

如果您的 SQLCipher 安装在自定义位置（如果您自己编译并安装了它），您需要设置一些环境变量：

在使用 Homebrew 的 OS X 上

设置 brew 安装的位置：

export LDFLAGS="-L`brew --prefix`/opt/sqlcipher/lib"
export CPPFLAGS="-I`brew --prefix`/opt/sqlcipher/include/sqlcipher"
npm install sqlite3 --build-from-source --sqlite_libname=sqlcipher --sqlite=`brew --prefix`

node -e 'require("sqlite3")'

在大多数 Linux 系统上（包括树莓派）

设置 make 安装的位置：

export LDFLAGS="-L/usr/local/lib"
export CPPFLAGS="-I/usr/local/include -I/usr/local/include/sqlcipher"
export CXXFLAGS="$CPPFLAGS"
npm install sqlite3 --build-from-source --sqlite_libname=sqlcipher --sqlite=/usr/local --verbose

node -e 'require("sqlite3")'

自定义构建和 Electron

通过 electron-rebuild 运行 sqlite3 不会保留 SQLCipher 扩展，因此需要一些额外的标志来使此构建与 Electron 兼容。您的 npm install sqlite3 --build-from-source 命令需要这些额外的标志（请务必将目标版本替换为您正在使用的当前 Electron 版本）：

--runtime=electron --target=18.2.1 --dist-url=https://electronjs.org/headers

对于使用 Homebrew 的 MacOS，命令应该如下所示：

npm install sqlite3 --build-from-source --sqlite_libname=sqlcipher --sqlite=`brew --prefix` --runtime=electron --target=18.2.1 --dist-url=https://electronjs.org/headers