@homeofthings/sqlite3 6.3.1 → 7.0.0

package/README.md

@@ -2,25 +2,33 @@
 
 **Note:** This repository is forked from [TryGhost/node-sqlite3](https://github.com/TryGhost/node-sqlite3) which was marked as deprecated/unmaintained.
 
+**Note:** Fortunately, there is already another well maintained fork: [AppThreat/node-sqlite3](https://github.com/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.
+
+**So you have the choice**
+
 ---
 Asynchronous, non-blocking [SQLite3](https://sqlite.org/) bindings for [Node.js](http://nodejs.org/).
 
 [![npm version](https://badge.fury.io/js/%40homeofthings%2Fsqlite3.svg)](https://badge.fury.io/js/%40homeofthings%2Fsqlite3)
+![NPM Downloads](https://img.shields.io/npm/dm/%40homeofthings%2Fsqlite3)
 [![Build Status](https://github.com/gms1/node-sqlite3/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/gms1/node-sqlite3/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/gms1/node-sqlite3/graph/badge.svg?token=6H0X94BL3X)](https://codecov.io/gh/gms1/node-sqlite3)
 [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmapbox%2Fnode-sqlite3.svg?type=shield)](https://app.fossa.io/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmapbox%2Fnode-sqlite3?ref=badge_shield)
-[![N-API v3 Badge](https://img.shields.io/badge/N--API-v3-green.svg)](https://nodejs.org/dist/latest/docs/api/n-api.html#n_api_n_api)
-[![N-API v6 Badge](https://img.shields.io/badge/N--API-v6-green.svg)](https://nodejs.org/dist/latest/docs/api/n-api.html#n_api_n_api)
+![Node-API v9 Badge](https://raw.githubusercontent.com/nodejs/abi-stable-node/doc/assets/Node-API%20v9%20Badge.svg)
 
 # Features
 
+ - Bundles SQLite v3.53.0, or you can build using a local SQLite (or SqlCipher,...)
  - Straightforward query and parameter binding interface
  - Full Buffer/Blob support
- - Extensive [debugging support](https://github.com/gms1/node-sqlite3/wiki/Debugging)
- - [Query serialization](https://github.com/gms1/node-sqlite3/wiki/Control-Flow) API
- - [Extension support](https://github.com/gms1/node-sqlite3/wiki/API#databaseloadextensionpath-callback), including bundled support for the [json1 extension](https://www.sqlite.org/json1.html)
+ - Extensive debugging support via [verbose mode](docs/API.md#verbose-mode)
+ - [Query serialization](docs/API.md#databaseserialize) API
+ - [Extension support](docs/API.md#databaseloadextension), including bundled support for the [json1 extension](https://www.sqlite.org/json1.html)
  - Big test suite
- - Written in modern C++ and tested for memory leaks
- - Bundles SQLite v3.51.3, or you can build using a local SQLite
+ - Written in modern C++
+ - Is built using hardening flags
+ - Promise-based API
+ - supports ESM and CJS
 
 # Installing
 
@@ -32,27 +40,24 @@ npm install @homeofthings/sqlite3
 # or
 yarn add @homeofthings/sqlite3
 ```
-* GitHub's `main` branch: `npm install https://github.com/gms1/node-sqlite3/tarball/main`
 
 ### Prebuilt binaries
 
-`@homeofthings/sqlite3` uses [Node-API](https://nodejs.org/api/n-api.html) so prebuilt binaries do not need to be built for specific Node versions. Prebuilt binaries are available for Node-API v3 and v6. Check the [Node-API version matrix](https://nodejs.org/api/n-api.html#node-api-version-matrix) to ensure your Node version supports one of these. Requires Node.js v20.17.0 or later.
+`@homeofthings/sqlite3` uses [Node-API](https://nodejs.org/api/n-api.html) 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.
 
-The module uses [`prebuild-install`](https://github.com/prebuild/prebuild-install) to download the prebuilt binary for your platform, if it exists. These binaries are hosted on GitHub Releases. The following targets are currently provided:
+Prebuilt binaries are bundled inside the npm package using [`prebuildify`](https://github.com/prebuild/prebuildify) and loaded at runtime by [`node-gyp-build`](https://github.com/prebuild/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`
-* `linux-x64`
-* `linuxmusl-arm64`
-* `linuxmusl-x64`
+* `linux-arm64` (glibc)
+* `linux-x64` (glibc)
+* `linux-arm64` (musl)
+* `linux-x64` (musl)
 * `win32-x64`
 
-Unfortunately, [prebuild](https://github.com/prebuild/prebuild/issues/174) cannot differentiate between `armv6` and `armv7`, and instead uses `arm` as the `{arch}`. Until that is fixed, you will still need to install `sqlite3` from [source](#source-install).
-
 Support for other platforms and architectures may be added in the future if CI supports building on them.
 
-If your environment isn't supported, it'll use `node-gyp` to build SQLite, but you will need to install a C++ compiler and linker.
+If your platform isn't supported, `node-gyp-build` automatically falls back to building from source using `node-gyp`. 
 
 ### Other ways to install
 
@@ -105,6 +110,37 @@ async function main() {
 main().catch(console.error);
 ```
 
+## ESM and CJS Support
+
+This package supports both CommonJS (CJS) and ECMAScript Modules (ESM):
+
+### CJS (CommonJS)
+
+```js
+// Default import
+const sqlite3 = require('@homeofthings/sqlite3');
+
+// Destructured import
+const { Database, SqliteDatabase } = require('@homeofthings/sqlite3');
+
+// Promise subpath import
+const { SqliteDatabase } = require('@homeofthings/sqlite3/promise');
+```
+
+### ESM (ECMAScript Modules)
+
+```js
+// Default import
+import sqlite3 from '@homeofthings/sqlite3';
+
+// Named imports
+import { Database, OPEN_CREATE, SqliteDatabase } from '@homeofthings/sqlite3';
+
+// Promise subpath import
+import { SqliteDatabase } from '@homeofthings/sqlite3/promise';
+```
+
+
 # Usage
 
 **Note:** the module must be [installed](#installing) before use.
@@ -132,10 +168,11 @@ db.close();
 
 ## Source install
 
-To skip searching for pre-compiled binaries, and force a build from source, use
+To build from source, use
 
 ```bash
-npm install --build-from-source --sqlite=/usr/local
+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.
@@ -143,7 +180,8 @@ If building against an external sqlite3 make sure to have the development header
 Note, if building against homebrew-installed sqlite on OS X you can do:
 
 ```bash
-npm install --build-from-source --sqlite=/usr/local/opt/sqlite/
+cd node_modules/@homeofthings/sqlite3
+npx node-gyp rebuild --sqlite=/usr/local/opt/sqlite/
 ```
 
 ## Custom file header (magic)
@@ -151,7 +189,8 @@ npm install --build-from-source --sqlite=/usr/local/opt/sqlite/
 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.
 
 ```bash
-npm install --build-from-source --sqlite_magic="MyCustomMagic15"
+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).
@@ -168,13 +207,15 @@ To build `sqlite3` for node-webkit:
 
 ```bash
 NODE_WEBKIT_VERSION="0.8.6" # see latest version at https://github.com/rogerwang/node-webkit#downloads
-npm install @homeofthings/sqlite3 --build-from-source --runtime=node-webkit --target_arch=ia32 --target=$(NODE_WEBKIT_VERSION)
+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:
 
 ```bash
-npm install --build-from-source --runtime=node-webkit --target_arch=ia32 --target=$(NODE_WEBKIT_VERSION)
+cd node_modules/@homeofthings/sqlite3
+npx node-gyp rebuild --runtime=node-webkit --target_arch=ia32 --target=$(NODE_WEBKIT_VERSION)
 ```
 
 Remember the following:
@@ -193,7 +234,8 @@ For instructions on building SQLCipher, see [Building SQLCipher for Node.js](htt
 To run against SQLCipher, you need to compile `sqlite3` from source by passing build options like:
 
 ```bash
-npm install @homeofthings/sqlite3 --build-from-source --sqlite_libname=sqlcipher --sqlite=/usr/
+cd node_modules/@homeofthings/sqlite3
+npx node-gyp rebuild --sqlite_libname=sqlcipher --sqlite=/usr/
 
 node -e 'require("@homeofthings/sqlite3")'
 ```
@@ -207,7 +249,8 @@ Set the location where `brew` installed it:
 ```bash
 export LDFLAGS="-L`brew --prefix`/opt/sqlcipher/lib"
 export CPPFLAGS="-I`brew --prefix`/opt/sqlcipher/include/sqlcipher"
-npm install @homeofthings/sqlite3 --build-from-source --sqlite_libname=sqlcipher --sqlite=`brew --prefix`
+cd node_modules/@homeofthings/sqlite3
+npx node-gyp rebuild --sqlite_libname=sqlcipher --sqlite=`brew --prefix`
 
 node -e 'require("@homeofthings/sqlite3")'
 ```
@@ -220,23 +263,26 @@ 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"
-npm install @homeofthings/sqlite3 --build-from-source --sqlite_libname=sqlcipher --sqlite=/usr/local --verbose
+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](https://github.com/electron/electron-rebuild) does not preserve the SQLCipher extension, so some additional flags are needed to make this build Electron compatible. Your `npm install @homeofthings/sqlite3 --build-from-source` command needs these additional flags (be sure to replace the target version with the current Electron version you are working with):
+Running `sqlite3` through [electron-rebuild](https://github.com/electron/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):
 
 ```bash
-npm install @homeofthings/sqlite3 --build-from-source --runtime=electron --target=18.2.1 --dist-url=https://electronjs.org/headers
+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:
 
 ```bash
-npm install @homeofthings/sqlite3 --build-from-source --sqlite_libname=sqlcipher --sqlite=`brew --prefix` --runtime=electron --target=18.2.1 --dist-url=https://electronjs.org/headers
+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
@@ -245,6 +291,34 @@ npm install @homeofthings/sqlite3 --build-from-source --sqlite_libname=sqlcipher
 npm test
 ```
 
+# Benchmarks
+
+## Driver Comparison
+
+The `tools/benchmark-drivers` directory contains a comprehensive benchmark suite comparing different SQLite drivers for Node.js:
+
+```bash
+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](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`:
+
+```bash
+node tools/benchmark-internal/run.js
+```
+
 # Contributors
 
 * [Daniel Lockyer](https://github.com/daniellockyer)
@@ -269,7 +343,7 @@ Thanks to [Orlando Vazquez](https://github.com/orlandov),
 [Eric Fredricksen](https://github.com/grumdrig) and
 [Ryan Dahl](https://github.com/ry) for their SQLite bindings for node, and to mraleph on Freenode's #v8 for answering questions.
 
-This module was originally created by [Mapbox](https://mapbox.com/) & is now maintained by [Ghost](https://ghost.org).
+This module was originally created by [Mapbox](https://mapbox.com/), then it was taken over by [Ghost](https://ghost.org), but was then deprecated without prior notice, so that the original is no longer maintained. See [TryGhost/node-sqlite3](https://github.com/TryGhost/node-sqlite3)
 
 # Changelog
 

package/binding.gyp

@@ -15,6 +15,9 @@
       },
       "include_dirs": [
         "<!@(node -p \"require('node-addon-api').include\")"],
+      "dependencies": [
+        "<!(node -p \"require('node-addon-api').targets\"):node_addon_api"
+      ],
       "conditions": [
         ["sqlite != 'internal'", {
             "include_dirs": [
@@ -36,7 +39,6 @@
         },
         {
             "dependencies": [
-              "<!(node -p \"require('node-addon-api').targets\"):node_addon_api_except",
               "deps/sqlite3.gyp:sqlite3"
             ]
         }
@@ -53,7 +55,6 @@
         ["OS=='win'", {
           "msvs_settings": {
             "VCCLCompilerTool": {
-              "ExceptionHandling": 1,
               "BufferSecurityCheck": "true",
               "ControlFlowGuard": "Guard"
             },
@@ -94,4 +95,4 @@
       }
     }
   ]
-}
+}

package/deps/common-sqlite.gypi

@@ -1,6 +1,6 @@
 {
   'variables': {
-      'sqlite_version%':'3510300',
+      'sqlite_version%':'3530000',
       "toolset%":'',
   },
   'target_defaults': {