āļø node-sqlite3
Asynchronous, non-blocking SQLite3 bindings for Node.js.
![N-API v6 Badge](https://img.shields.io/badge/N--API-v6-green.svg)
Features
Installing
You can use npm
or yarn
toĀ install sqlite3
:
- (recommended) Latest published package:
npm install sqlite3
yarn add sqlite3
- GitHub's
master
branch: npm install https://github.com/tryghost/node-sqlite3/tarball/master
Prebuilt binaries
sqlite3
v5+ was rewritten to use Node-API 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 to ensure your Node version supports one of these. The prebuilt binaries should be supported on Node v10+.
The module uses node-pre-gyp 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:
Format: napi-v{napi_build_version}-{platform}-{libc}-{arch}
napi-v3-darwin-unknown-arm64
napi-v3-darwin-unknown-x64
napi-v3-linux-glibc-arm64
napi-v3-linux-glibc-x64
napi-v3-linux-musl-arm64
napi-v3-linux-musl-x64
napi-v3-win32-unknown-ia32
napi-v3-win32-unknown-x64
napi-v6-darwin-unknown-arm64
napi-v6-darwin-unknown-x64
napi-v6-linux-glibc-arm64
napi-v6-linux-glibc-x64
napi-v6-linux-musl-arm64
napi-v6-linux-musl-x64
napi-v6-win32-unknown-ia32
napi-v6-win32-unknown-x64
Unfortunately, node-pre-gyp 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.
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.).
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 in the wiki.
Usage
Note: theĀ module mustĀ be installed beforeĀ use.
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();
Source install
To skip searching for pre-compiled binaries, and force a build from source, use
npm install --build-from-source
The sqlite3 module depends only on libsqlite3. However, by default, an internal/bundled copy of sqlite will be built and statically linked, so an externally installed sqlite3 is not required.
If you wish to install against an external sqlite then you need to pass the --sqlite
argument to npm
wrapper:
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:
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.
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.
To build sqlite3
for node-webkit:
-
Install nw-gyp
globally: npm install nw-gyp -g
(unless already installed)
-
Build theĀ module with the custom flags of --runtime
, --target_arch
, and --target
:
NODE_WEBKIT_VERSION="0.8.6"
npm install sqlite3 --build-from-source --runtime=node-webkit --target_arch=ia32 --target=$(NODE_WEBKIT_VERSION)
This command internally calls out to node-pre-gyp
which itself calls out to nw-gyp
when the --runtime=node-webkit
option is passed.
You can also run this command from within a sqlite3
checkout:
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ā 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:
npm install sqlite3 --build-from-source --sqlite_libname=sqlcipher --sqlite=/usr/
node -e 'require("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"
npm install sqlite3 --build-from-source --sqlite_libname=sqlcipher --sqlite=`brew --prefix`
node -e 'require("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"
npm install sqlite3 --build-from-source --sqlite_libname=sqlcipher --sqlite=/usr/local --verbose
node -e 'require("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. Your npm install 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):
--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:
npm install sqlite3 --build-from-source --sqlite_libname=sqlcipher --sqlite=`brew --prefix` --runtime=electron --target=18.2.1 --dist-url=https://electronjs.org/headers
Testing
npm test
Contributors
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 & is now maintained by Ghost.
Changelog
We use GitHub releases for notes on the latest versions. See CHANGELOG.md in git history for details on older versions.
License
node-sqlite3
is BSD licensed.
![FOSSA Status](https://app.fossa.io/api/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmapbox%2Fnode-sqlite3.svg?type=large)