better-sqlite3-multiple-ciphers

The fastest and simplest library for SQLite in Node.js. This particular fork supports multiple-cipher encryption using SQLite3MultipleCiphers. Check usage to learn more.

• Full transaction support
• High performance, efficiency, and safety
• Easy-to-use synchronous API (better concurrency than an asynchronous API... yes, you read that correctly)
• Support for user-defined functions, aggregates, virtual tables, and extensions
• 64-bit integers (invisible until you need them)
• Worker thread support (for large/slow queries)
• Encryption support using multiple algorithms

Current versions

• ### Stable

• ### Beta

Help this project stay strong! 💪

I'm the author of better-sqlite3-multiple-ciphers and also a team member and maintainer of better-sqlite3. better-sqlite3-multiple-ciphers is mostly used by commercial projects that require data security on the client's end. If your company uses better-sqlite3-multiple-ciphers, ask your manager to consider supporting the project. I put in a lot of hours to maintain both of these projects, and you can support me by buying me a few coffees. 😊

The best way for you to support me is via GitHub Sponsors, even for one-time donations, because they don't keep a share. Everything you donate goes to the developer.

Head over to the better-sqlite3 repo and give some support to the author and the team to keep this valuable package maintained.

Also, head over to the SQLite3MultipleCiphers repo and give some support to the developer to keep this very useful extension alive. This project is authored and maintained by a sole developer.

How other libraries compare

| |select 1 row  get() |select 100 rows   all()  |select 100 rows iterate() 1-by-1|insert 1 row run()|insert 100 rows in a transaction| |---|---|---|---|---|---| |better-sqlite3|1x|1x|1x|1x|1x| |sqlite and sqlite3|11.7x slower|2.9x slower|24.4x slower|2.8x slower|15.6x slower|

You can verify these results by running the benchmark yourself.

Installation

Stable

npm install better-sqlite3-multiple-ciphers

Beta

npm install better-sqlite3-multiple-ciphers@beta

Requires a currently supported Node.js version. Prebuilt binaries are available for major platforms/architectures. If you have trouble installing, check the troubleshooting guide.

Usage

const db = require('better-sqlite3-multiple-ciphers')('foobar.db', options);
const row = db.prepare('SELECT * FROM users WHERE id = ?').get(userId);
console.log(row.firstName, row.lastName, row.email);

Though not required, it is generally important to set the WAL pragma for performance reasons.

db.pragma('journal_mode = WAL');

##### In ES6 module notation:

import Database from 'better-sqlite3-multiple-ciphers';
const db = new Database('foobar.db', options);
db.pragma('journal_mode = WAL');

Encryption

A database can be encrypted and decrypted simply using key and rekey PRAGMA statements.

Running this will encrypt the database using the default cipher (sqleet):

const db = require('better-sqlite3-multiple-ciphers')('foobar.db', options);
db.pragma(rekey='secret-key');
db.close();

To read an encrypted database (assuming default cipher):

const db = require('better-sqlite3-multiple-ciphers')('foobar.db', options);
db.pragma(key='secret-key');
const row = db.prepare('SELECT * FROM users WHERE id = ?').get(userId);
console.log(row.firstName, row.lastName, row.email);

To read an encrypted database _(legacy SQLCipher)_ created by tools like DB Browser for SQLite:

const db = require('better-sqlite3-multiple-ciphers')('foobar.db', options);
db.pragma(cipher='sqlcipher')
db.pragma(legacy=4)
db.pragma(key='secret-key');
const row = db.prepare('SELECT * FROM users WHERE id = ?').get(userId);
console.log(row.firstName, row.lastName, row.email);

You can also use key() and rekey() functions for encryption and decryption tasks.

GUI database editors:

Even though better-sqlite3-multiple-ciphers supports opening databases created using DB Browser for SQLite, it only supports creating/editing legacy SQLCipher databases which means, it's highly likely that you won't be able to open a database created using better-sqlite3-multiple-ciphers in DB Browser for SQLite.

To visually edit databases created using better-sqlite3-multiple-ciphers regardless of the cipher configuration, it's recommended to use a tool like SQLiteStudio because it also uses SQLite3MultipleCiphers under the hood.

Read more about encryption at SQLite3MultipleCiphers documentation.

Why should I use this instead of node-sqlite3?

• node-sqlite3 uses asynchronous APIs for tasks that are either CPU-bound or serialized. That's not only bad design, but it wastes tons of resources. It also causes mutex thrashing which has devastating effects on performance.
• node-sqlite3 exposes low-level (C language) memory management functions. better-sqlite3 does it the JavaScript way, allowing the garbage collector to worry about memory management.
• better-sqlite3 is simpler to use, and it provides nice utilities for some operations that are very difficult or impossible in node-sqlite3.
• better-sqlite3 is much faster than node-sqlite3 in most cases, and just as fast in all other cases.

When is this library not appropriate?

In most cases, if you're attempting something that cannot be reasonably accomplished with better-sqlite3, it probably cannot be reasonably accomplished with SQLite in general. For example, if you're executing queries that take one second to complete, and you expect to have many concurrent users executing those queries, no amount of asynchronicity will save you from SQLite's serialized nature. Fortunately, SQLite is very very fast. With proper indexing, we've been able to achieve upward of 2000 queries per second with 5-way-joins in a 60 GB database, where each query was handling 5–50 kilobytes of real data.

If you have a performance problem, the most likely causes are inefficient queries, improper indexing, or a lack of WAL mode—not better-sqlite3 itself. However, there are some cases where better-sqlite3 could be inappropriate:

• If you expect a high volume of concurrent reads each returning many megabytes of data (i.e., videos)
• If you expect a high volume of concurrent writes (i.e., a social media site)
• If your database's size is near the terabyte range

Upgrading

Upgrading your better-sqlite3-multiple-ciphers dependency can potentially introduce breaking changes, either in the better-sqlite3-multiple-ciphers API (if you upgrade to a new major version), or between your existing database(s) and the underlying version of SQLite. Before upgrading, review:

• better-sqlite3-multiple-ciphers release notes
• SQLite release history

Documentation

• API documentation
• Performance (also see benchmark results)
• 64-bit integer support
• Worker thread support
• Unsafe mode (advanced)
• SQLite compilation (advanced)

License

MIT