@homeofthings/sqlite3 0.0.1-alpha0 → 6.1.0

package/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) 2013-2026 Mapbox & Ghost Foundation
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+- Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+- Redistributions in binary form must reproduce the above copyright notice, this
+  list of conditions and the following disclaimer in the documentation and/or
+  other materials provided with the distribution.
+- Neither the name "MapBox" nor the names of its contributors may be
+  used to endorse or promote products derived from this software without
+  specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,26 +1,76 @@
-# @homeofthings/sqlite3
+# gms1/node-sqlite3
 
+**Note:** This repository is forked from [TryGhost/node-sqlite3](https://github.com/TryGhost/node-sqlite3) which was marked as deprecated/unmaintained.
+
+---
 Asynchronous, non-blocking [SQLite3](https://sqlite.org/) bindings for [Node.js](http://nodejs.org/).
 
-## Features
+[![npm version](https://badge.fury.io/js/%40homeofthings%2Fsqlite3.svg)](https://badge.fury.io/js/%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)
+[![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)
+
+# Features
+
+ - 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)
+ - 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
 
-- 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)
+# Installing
 
-## Installing
+You can use [`npm`](https://github.com/npm/cli) or [`yarn`](https://github.com/yarnpkg/yarn) to install `@homeofthings/sqlite3`:
 
+* (recommended) Latest published package:
 ```bash
 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
+
+`sqlite3` v5+ was rewritten to use [Node-API](https://nodejs.org/api/n-api.html) so prebuilt binaries do not need to be built for specific Node versions. `sqlite3` currently builds for both 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. The prebuilt binaries should be supported on Node v20.17.0+.
+
+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 for `sqlite3` versions above 5.0.2, and they are hosted on S3 otherwise. The following targets are currently provided:
+
+* `darwin-arm64`
+* `darwin-x64`
+* `linux-arm64`
+* `linux-x64`
+* `linuxmusl-arm64`
+* `linuxmusl-x64`
+* `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.
+
+### 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.](#source-install)).
 
-## Usage
+The `sqlite3` module also works with [node-webkit](https://github.com/rogerwang/node-webkit) if node-webkit contains a supported version of Node.js engine. [(See below.)](#building-for-node-webkit)
 
-```js
+SQLite's [SQLCipher extension](https://github.com/sqlcipher/sqlcipher) is also supported. [(See below.)](#building-for-sqlcipher)
+
+# API
+
+See the [API documentation](https://github.com/gms1/node-sqlite3/wiki/API) in the wiki.
+
+# Usage
+
+**Note:** the module must be [installed](#installing) before use.
+
+``` js
 const sqlite3 = require('@homeofthings/sqlite3').verbose();
 const db = new sqlite3.Database(':memory:');
 
@@ -41,10 +91,155 @@ db.serialize(() => {
 db.close();
 ```
 
-## Source
+## Source install
+
+To skip searching for pre-compiled binaries, and force a build from source, use
+
+```bash
+npm install --build-from-source --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:
+
+```bash
+npm install --build-from-source --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.
+
+```bash
+npm install --build-from-source --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](https://github.com/rogerwang/node-webkit).
+
+To build `sqlite3` for node-webkit:
+
+1. Install [`nw-gyp`](https://github.com/rogerwang/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`:
+
+```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)
+```
+
+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)
+```
+
+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](https://github.com/rogerwang/node-webkit/wiki/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](https://coolaj86.com/articles/building-sqlcipher-for-node-js-on-raspberry-pi-2/). 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:
+
+```bash
+npm install @homeofthings/sqlite3 --build-from-source --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:
+
+```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`
+
+node -e 'require("@homeofthings/sqlite3")'
+```
+
+### On most Linuxes (including Raspberry Pi)
+
+Set the location where `make` installed it:
+
+```bash
+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
+
+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):
+
+```bash
+npm install @homeofthings/sqlite3 --build-from-source --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
+```
+
+# Testing
+
+```bash
+npm test
+```
+
+# Contributors
+
+* [Daniel Lockyer](https://github.com/daniellockyer)
+* [Konstantin Käfer](https://github.com/kkaefer)
+* [Dane Springmeyer](https://github.com/springmeyer)
+* [Will White](https://github.com/willwhite)
+* [Orlando Vazquez](https://github.com/orlandov)
+* [Artem Kustikov](https://github.com/artiz)
+* [Eric Fredricksen](https://github.com/grumdrig)
+* [John Wright](https://github.com/mrjjwright)
+* [Ryan Dahl](https://github.com/ry)
+* [Tom MacWright](https://github.com/tmcw)
+* [Carter Thaxton](https://github.com/carter-thaxton)
+* [Audrius Kažukauskas](https://github.com/audriusk)
+* [Johannes Schauer](https://github.com/pyneo)
+* [Mithgol](https://github.com/Mithgol)
+* [Kewde](https://github.com/kewde)
+
+# Acknowledgments
+
+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).
+
+# Changelog
+
+We use [GitHub releases](https://github.com/gms1/node-sqlite3/releases) for notes on the latest versions. See [CHANGELOG.md](https://github.com/gms1/node-sqlite3/blob/main/CHANGELOG.md) in git history for details on older versions.
+
+# Copyright & license
 
-[GitHub Repository](https://github.com/gms1/node-sqlite3)
+Copyright (c) 2013-2026 Mapbox & Ghost Foundation
 
-## License
+`node-sqlite3` is [BSD licensed](https://github.com/gms1/node-sqlite3/raw/main/LICENSE).
 
-BSD-3-Clause
+[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmapbox%2Fnode-sqlite3.svg?type=large)](https://app.fossa.io/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmapbox%2Fnode-sqlite3?ref=badge_large)

package/binding.gyp

@@ -0,0 +1,58 @@
+{
+  "includes": [ "deps/common-sqlite.gypi" ],
+  "variables": {
+      "sqlite%":"internal",
+      "sqlite_libname%":"sqlite3",
+      "module_name": "node_sqlite3",
+  },
+  "targets": [
+    {
+      "target_name": "<(module_name)",
+      "cflags!": [ "-fno-exceptions" ],
+      "cflags_cc!": [ "-fno-exceptions" ],
+      "xcode_settings": { "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
+        "CLANG_CXX_LIBRARY": "libc++",
+        "MACOSX_DEPLOYMENT_TARGET": "10.7",
+      },
+      "msvs_settings": {
+        "VCCLCompilerTool": { "ExceptionHandling": 1 },
+      },
+      "include_dirs": [
+        "<!@(node -p \"require('node-addon-api').include\")"],
+      "conditions": [
+        ["sqlite != 'internal'", {
+            "include_dirs": [
+              "<!@(node -p \"require('node-addon-api').include\")", "<(sqlite)/include" ],
+            "libraries": [
+               "-l<(sqlite_libname)"
+            ],
+            "conditions": [
+              [ "OS=='linux'", {"libraries+":["-Wl,-rpath=<@(sqlite)/lib"]} ],
+              [ "OS!='win'", {"libraries+":["-L<@(sqlite)/lib"]} ]
+            ],
+            'msvs_settings': {
+              'VCLinkerTool': {
+                'AdditionalLibraryDirectories': [
+                  '<(sqlite)/lib'
+                ],
+              },
+            }
+        },
+        {
+            "dependencies": [
+              "<!(node -p \"require('node-addon-api').gyp\")",
+              "deps/sqlite3.gyp:sqlite3"
+            ]
+        }
+        ]
+      ],
+      "sources": [
+        "src/backup.cc",
+        "src/database.cc",
+        "src/node_sqlite3.cc",
+        "src/statement.cc"
+      ],
+      "defines": [ "NAPI_VERSION=<(napi_build_version)", "NAPI_DISABLE_CPP_EXCEPTIONS=1" ]
+    }
+  ]
+}

package/deps/common-sqlite.gypi

@@ -0,0 +1,60 @@
+{
+  'variables': {
+      'sqlite_version%':'3510300',
+      "toolset%":'',
+  },
+  'target_defaults': {
+    'default_configuration': 'Release',
+    'conditions': [
+      [ 'toolset!=""', {
+        'msbuild_toolset':'<(toolset)'
+      }]
+    ],
+    'configurations': {
+      'Debug': {
+        'defines!': [
+          'NDEBUG'
+        ],
+        'cflags_cc!': [
+          '-O3',
+          '-Os',
+          '-DNDEBUG'
+        ],
+        'xcode_settings': {
+          'OTHER_CPLUSPLUSFLAGS!': [
+            '-O3',
+            '-Os',
+            '-DDEBUG'
+          ],
+          'GCC_OPTIMIZATION_LEVEL': '0',
+          'GCC_GENERATE_DEBUGGING_SYMBOLS': 'YES'
+        },
+        'msvs_settings': {
+          'VCCLCompilerTool': {
+            'ExceptionHandling': 1, # /EHsc
+          }
+        }
+      },
+      'Release': {
+        'defines': [
+          'NDEBUG'
+        ],
+        'xcode_settings': {
+          'OTHER_CPLUSPLUSFLAGS!': [
+            '-Os',
+            '-O2'
+          ],
+          'GCC_OPTIMIZATION_LEVEL': '3',
+          'GCC_GENERATE_DEBUGGING_SYMBOLS': 'NO',
+          'DEAD_CODE_STRIPPING': 'YES',
+          'GCC_INLINES_ARE_PRIVATE_EXTERN': 'YES'
+        },
+        'msvs_settings': {
+          'VCCLCompilerTool': {
+            'ExceptionHandling': 1, # /EHsc
+          }
+        }
+      }
+    }
+  }
+}

package/deps/extract.js

@@ -0,0 +1,19 @@
+const tar = require("tar");
+const fs = require("fs");
+const path = require("path");
+const tarball = path.resolve(process.argv[2]);
+const dirname = path.resolve(process.argv[3]);
+
+tar.extract({
+    sync: true,
+    file: tarball,
+    cwd: dirname,
+});
+
+// SQLite >= 3.49 ships a VERSION file that conflicts with the C++20 <version>
+// header on case-insensitive filesystems (macOS/Windows).
+const base = path.basename(tarball, ".tar.gz");
+const versionFile = path.join(dirname, base, "VERSION");
+if (fs.existsSync(versionFile)) {
+    fs.unlinkSync(versionFile);
+}

package/deps/sqlite3.gyp

@@ -0,0 +1,121 @@
+{
+  'includes': [ 'common-sqlite.gypi' ],
+
+  'variables': {
+    'sqlite_magic%': '',
+  },
+
+  'target_defaults': {
+    'default_configuration': 'Release',
+    'cflags':[
+      '-std=c99'
+    ],
+    'configurations': {
+      'Debug': {
+        'defines': [ 'DEBUG', '_DEBUG' ],
+        'msvs_settings': {
+          'VCCLCompilerTool': {
+            'RuntimeLibrary': 1, # static debug
+          },
+        },
+      },
+      'Release': {
+        'defines': [ 'NDEBUG' ],
+        'msvs_settings': {
+          'VCCLCompilerTool': {
+            'RuntimeLibrary': 0, # static release
+          },
+        },
+      }
+    },
+    'msvs_settings': {
+      'VCCLCompilerTool': {
+      },
+      'VCLibrarianTool': {
+      },
+      'VCLinkerTool': {
+        'GenerateDebugInformation': 'true',
+      },
+    },
+    'conditions': [
+      ['OS == "win"', {
+        'defines': [
+          'WIN32'
+        ],
+      }]
+    ],
+  },
+
+  'targets': [
+    {
+      'target_name': 'action_before_build',
+      'type': 'none',
+      'hard_dependency': 1,
+      'actions': [
+        {
+          'action_name': 'unpack_sqlite_dep',
+          'inputs': [
+            './sqlite-autoconf-<@(sqlite_version).tar.gz'
+          ],
+          'outputs': [
+            '<(SHARED_INTERMEDIATE_DIR)/sqlite-autoconf-<@(sqlite_version)/sqlite3.c'
+          ],
+          'action': ['node','./extract.js','./sqlite-autoconf-<@(sqlite_version).tar.gz','<(SHARED_INTERMEDIATE_DIR)']
+        }
+      ],
+      'direct_dependent_settings': {
+        'include_dirs': [
+          '<(SHARED_INTERMEDIATE_DIR)/sqlite-autoconf-<@(sqlite_version)/',
+        ]
+      },
+    },
+    {
+      'target_name': 'sqlite3',
+      'type': 'static_library',
+      'include_dirs': [ '<(SHARED_INTERMEDIATE_DIR)/sqlite-autoconf-<@(sqlite_version)/' ],
+      'dependencies': [
+        'action_before_build'
+      ],
+      'sources': [
+        '<(SHARED_INTERMEDIATE_DIR)/sqlite-autoconf-<@(sqlite_version)/sqlite3.c'
+      ],
+      'direct_dependent_settings': {
+        'include_dirs': [ '<(SHARED_INTERMEDIATE_DIR)/sqlite-autoconf-<@(sqlite_version)/' ],
+        'defines': [
+          'SQLITE_THREADSAFE=1',
+          'HAVE_USLEEP=1',
+          'SQLITE_ENABLE_FTS3',
+          'SQLITE_ENABLE_FTS4',
+          'SQLITE_ENABLE_FTS5',
+          'SQLITE_ENABLE_RTREE',
+          'SQLITE_ENABLE_DBSTAT_VTAB=1',
+          'SQLITE_ENABLE_MATH_FUNCTIONS'
+        ],
+      },
+      'cflags_cc': [
+          '-Wno-unused-value'
+      ],
+      'defines': [
+        '_REENTRANT=1',
+        'SQLITE_THREADSAFE=1',
+        'HAVE_USLEEP=1',
+        'SQLITE_ENABLE_FTS3',
+        'SQLITE_ENABLE_FTS4',
+        'SQLITE_ENABLE_FTS5',
+        'SQLITE_ENABLE_RTREE',
+        'SQLITE_ENABLE_DBSTAT_VTAB=1',
+        'SQLITE_ENABLE_MATH_FUNCTIONS'
+      ],
+      'export_dependent_settings': [
+        'action_before_build',
+      ],
+      'conditions': [
+        ["sqlite_magic != ''", {
+            'defines': [
+              'SQLITE_FILE_HEADER="<(sqlite_magic)"'
+            ]
+        }]
+      ],
+    }
+  ]
+}

package/lib/sqlite3-binding.js

@@ -0,0 +1 @@
+module.exports = require('bindings')('node_sqlite3.node');