gms1/node-sqlite3

Note: This repository is forked from TryGhost/node-sqlite3 which was marked as deprecated/unmaintained.

Note: Fortunately, there is already another well maintained fork: AppThreat/node-sqlite3. Unfortunately, this fork didn't appear in the list of forks of TryGhost/node-sqlite3, which is why I created this fork here.

⛔ [DEPRECATED] in favour of @appthreat/sqlite3

---

Asynchronous, non-blocking SQLite3 bindings for Node.js.

Features

• Straightforward query and parameter binding interface
• Full Buffer/Blob support
• Extensive debugging support via verbose mode
• Query serialization API
• Extension support, including bundled support for the json1 extension
• Big test suite
• Written in modern C++
• Bundles SQLite v3.53.0, or you can build using a local SQLite

Installing

You can use npm or yarn to install @homeofthings/sqlite3:

• (recommended) Latest published package:

npm install @homeofthings/sqlite3
# or
yarn add @homeofthings/sqlite3

Prebuilt binaries

@homeofthings/sqlite3 uses Node-API so prebuilt binaries do not need to be built for specific Node versions. Prebuilt binaries are built as NAPI-version-agnostic (@homeofthings+sqlite3.*.node) using the --napi flag, and work on any Node.js version that supports the NAPI version used at compile time. Requires Node.js v20.17.0 or later.

Prebuilt binaries are bundled inside the npm package using prebuildify and loaded at runtime by node-gyp-build. No separate download step is needed — npm install just works. The following targets are currently provided:

• darwin-arm64
• darwin-x64
• linux-arm64 (glibc)
• linux-x64 (glibc)
• linux-arm64 (musl)
• linux-x64 (musl)
• win32-x64

Support for other platforms and architectures may be added in the future if CI supports building on them.

If your platform isn't supported, node-gyp-build automatically falls back to building from source using node-gyp.

Other ways to install

It is also possible to make your own build of sqlite3 from its source instead of its npm package (See below.).

The sqlite3 module also works with node-webkit if node-webkit contains a supported version of Node.js engine. (See below.)

SQLite's SQLCipher extension is also supported. (See below.)

API

See the API documentation for detailed documentation of both the callback-based and Promise-based APIs.

Quick Example

Callback-based API (Traditional)

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

db.serialize(() => {
    db.run("CREATE TABLE lorem (info TEXT)");
    db.run("INSERT INTO lorem VALUES (?)", ['test']);
    db.each("SELECT * FROM lorem", (err, row) => {
        console.log(row);
    });
});

db.close();

Promise-based API (Modern)

const { SqliteDatabase } = require('@homeofthings/sqlite3');

async function main() {
    const db = await SqliteDatabase.open(':memory:');
    
    await db.run("CREATE TABLE lorem (info TEXT)");
    await db.run("INSERT INTO lorem VALUES (?)", ['test']);
    
    const rows = await db.all("SELECT * FROM lorem");
    console.log(rows);
    
    await db.close();
}

main().catch(console.error);

Usage

Note: the module must be installed before use.

const sqlite3 = require('@homeofthings/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();

Source install

To build from source, use

cd node_modules/@homeofthings/sqlite3
npx node-gyp rebuild --sqlite=/usr/local

If building against an external sqlite3 make sure to have the development headers available. Mac OS X ships with these by default. If you don't have them installed, install the -dev package with your package manager, e.g. apt-get install libsqlite3-dev for Debian/Ubuntu. Make sure that you have at least libsqlite3 >= 3.6.

Note, if building against homebrew-installed sqlite on OS X you can do:

cd node_modules/@homeofthings/sqlite3
npx node-gyp rebuild --sqlite=/usr/local/opt/sqlite/

Custom file header (magic)

The default sqlite file header is "SQLite format 3". You can specify a different magic, though this will make standard tools and libraries unable to work with your files.

cd node_modules/@homeofthings/sqlite3
npx node-gyp rebuild --sqlite_magic="MyCustomMagic15"

Note that the magic must be exactly 15 characters long (16 bytes including null terminator).

Building for node-webkit

Because of ABI differences, sqlite3 must be built in a custom to be used with node-webkit.

To build sqlite3 for node-webkit:

1. Install nw-gyp globally: npm install nw-gyp -g (unless already installed)

2. Build the module with the custom flags of --runtime, --target_arch, and --target:

NODE_WEBKIT_VERSION="0.8.6" # see latest version at https://github.com/rogerwang/node-webkit#downloads
cd node_modules/@homeofthings/sqlite3
npx node-gyp rebuild --runtime=node-webkit --target_arch=ia32 --target=$(NODE_WEBKIT_VERSION)

You can also run this command from within a @homeofthings/sqlite3 checkout:

cd node_modules/@homeofthings/sqlite3
npx node-gyp rebuild --runtime=node-webkit --target_arch=ia32 --target=$(NODE_WEBKIT_VERSION)

Remember the following:

• You must provide the right --target_arch flag. ia32 is needed to target 32bit node-webkit builds, while x64 will target 64bit node-webkit builds (if available for your platform).

• After the sqlite3 package is built for node-webkit it cannot run in the vanilla Node.js (and vice versa).

  • For example, npm test of the node-webkit's package would fail.

Visit the “Using Node modules” article in the node-webkit's wiki for more details.

Building for SQLCipher

For instructions on building SQLCipher, see Building SQLCipher for Node.js. Alternatively, you can install it with your local package manager.

To run against SQLCipher, you need to compile sqlite3 from source by passing build options like:

cd node_modules/@homeofthings/sqlite3
npx node-gyp rebuild --sqlite_libname=sqlcipher --sqlite=/usr/

node -e 'require("@homeofthings/sqlite3")'

If your SQLCipher is installed in a custom location (if you compiled and installed it yourself), you'll need to set some environment variables:

On OS X with Homebrew

Set the location where brew installed it:

export LDFLAGS="-L`brew --prefix`/opt/sqlcipher/lib"
export CPPFLAGS="-I`brew --prefix`/opt/sqlcipher/include/sqlcipher"
cd node_modules/@homeofthings/sqlite3
npx node-gyp rebuild --sqlite_libname=sqlcipher --sqlite=`brew --prefix`

node -e 'require("@homeofthings/sqlite3")'

On most Linuxes (including Raspberry Pi)

Set the location where make installed it:

export LDFLAGS="-L/usr/local/lib"
export CPPFLAGS="-I/usr/local/include -I/usr/local/include/sqlcipher"
export CXXFLAGS="$CPPFLAGS"
cd node_modules/@homeofthings/sqlite3
npx node-gyp rebuild --sqlite_libname=sqlcipher --sqlite=/usr/local --verbose

node -e 'require("@homeofthings/sqlite3")'

Custom builds and Electron

Running sqlite3 through electron-rebuild does not preserve the SQLCipher extension, so some additional flags are needed to make this build Electron compatible. So your command needs these additional flags (be sure to replace the target version with the current Electron version you are working with):

cd node_modules/@homeofthings/sqlite3
npx node-gyp rebuild --runtime=electron --target=18.2.1 --dist-url=https://electronjs.org/headers

In the case of MacOS with Homebrew, the command should look like the following:

cd node_modules/@homeofthings/sqlite3
npx node-gyp rebuild --sqlite_libname=sqlcipher --sqlite=`brew --prefix` --runtime=electron --target=18.2.1 --dist-url=https://electronjs.org/headers

Testing

npm test

Benchmarks

Driver Comparison

The tools/benchmark-drivers directory contains a comprehensive benchmark suite comparing different SQLite drivers for Node.js:

cd tools/benchmark-drivers
npm install
node index.js

This compares @homeofthings/sqlite3 against other popular SQLite drivers:

• better-sqlite3 - Synchronous, high-performance
• node:sqlite - Built-in Node.js SQLite (v22.6.0+)

See tools/benchmark-drivers/README.md for details.

Key insight: Async drivers like @homeofthings/sqlite3 show lower raw throughput but provide better event loop availability, allowing other operations to proceed concurrently. Sync drivers block the event loop completely.

Internal Benchmarks

Internal performance benchmarks are available in tools/benchmark-internal:

node tools/benchmark-internal/run.js

Contributors

• Daniel Lockyer
• Konstantin Käfer
• Dane Springmeyer
• Will White
• Orlando Vazquez
• Artem Kustikov
• Eric Fredricksen
• John Wright
• Ryan Dahl
• Tom MacWright
• Carter Thaxton
• Audrius Kažukauskas
• Johannes Schauer
• Mithgol
• Kewde

Acknowledgments

Thanks to Orlando Vazquez, Eric Fredricksen and Ryan Dahl for their SQLite bindings for node, and to mraleph on Freenode's #v8 for answering questions.

This module was originally created by Mapbox, then it was taken over by Ghost, but was then deprecated without prior notice, so that the original is no longer maintained. See TryGhost/node-sqlite3

Changelog

We use GitHub releases for notes on the latest versions. See CHANGELOG.md in git history for details on older versions.

Copyright & license

Copyright (c) 2013-2026 Mapbox & Ghost Foundation

node-sqlite3 is BSD licensed.