better-sqlite3 vs sqlite vs sqlite3: Architecture, Performance, and Use Cases

When adding a local database to a Node.js project, SQLite is the go-to choice for its zero-configuration setup and single-file storage. However, the JavaScript binding you choose dictates your application's architecture, performance ceiling, and deployment targets. The three main contenders—better-sqlite3, sqlite (often sql.js), and sqlite3—take fundamentally different approaches to bridging C++ and JavaScript. Let's break down how they work and when to use each.

⚡ Execution Model: Synchronous vs Asynchronous vs Portable

The most critical difference lies in how these libraries handle the Node.js event loop.

better-sqlite3 runs synchronously. Every query blocks the main thread until the database returns a result. While this sounds scary, it actually makes code easier to read and debug because you don't need await or callbacks for every step. It is incredibly fast for heavy workloads.

// better-sqlite3: Synchronous execution
const Database = require('better-sqlite3');
const db = new Database('my-db.sqlite');

// No await needed; runs immediately
const row = db.prepare('SELECT * FROM users WHERE id = ?').get(1);
console.log(row);

// Transactions are simple functions
const insert = db.prepare('INSERT INTO users (name) VALUES (?)');
const insertMany = db.transaction((names) => {
  for (const name of names) insert.run(name);
});
insertMany(['Alice', 'Bob']);

sqlite3 is fully asynchronous. It uses callbacks or promises to ensure the event loop never blocks. This is great for servers handling thousands of concurrent connections where a slow query shouldn't freeze other requests, but it leads to more complex code structures.

// sqlite3: Asynchronous execution with callbacks
const sqlite3 = require('sqlite3').verbose();
const db = new sqlite3.Database('my-db.sqlite');

db.get('SELECT * FROM users WHERE id = ?', [1], (err, row) => {
  if (err) throw err;
  console.log(row);
});

// Closing requires checking when all queries finish
db.close((err) => {
  if (err) console.error(err.message);
});

sqlite (typically referring to sql.js or similar WASM-based ports) compiles SQLite to WebAssembly. It can run synchronously or asynchronously depending on the wrapper, but its superpower is portability. It runs anywhere JavaScript runs, including browsers.

// sqlite (sql.js): Portable, often async initialization
const initSqlJs = require('sql.js');

(async () => {
  const SQL = await initSqlJs();
  const db = new SQL.Database();
  
  // Run queries in memory or load from file buffer
  db.run('CREATE TABLE users (id INT, name TEXT)');
  db.run('INSERT INTO users VALUES (?, ?)', [1, 'Alice']);
  
  const stmt = db.prepare('SELECT * FROM users WHERE id = :id');
  stmt.bind({ ':id': 1 });
  while (stmt.step()) {
    console.log(stmt.getAsObject());
  }
})();

📦 Installation and Binary Dependencies

How you install these packages affects your CI/CD pipeline and deployment strategy.

better-sqlite3 requires native compilation. It downloads pre-built binaries for most systems, but if your server OS isn't standard (like some ARM-based Lambdas or Alpine Linux), you might need Python and a C++ compiler installed to build it from source. This can slow down Docker builds if not cached correctly.

# May require build tools on some systems
npm install better-sqlite3

sqlite3 also relies on native binaries and has historically been notorious for installation headaches, especially when switching Node versions or OS architectures. It often forces a rebuild of the native module, which can fail in minimal container environments without extra setup.

# Frequently requires node-gyp rebuilds
npm install sqlite3

sqlite (sql.js) has zero native dependencies. It is pure JavaScript and WebAssembly. You can install it on any machine, cross-compile easily, and it works instantly in browser bundles without special webpack configuration for native modules.

# Pure JS/WASM, no build tools needed
npm install sql.js

🛠️ API Ergonomics and Error Handling

The developer experience varies significantly between synchronous and asynchronous styles.

better-sqlite3 shines with its prepared statement API. You prepare a statement once and reuse it efficiently. Errors are thrown as standard JavaScript exceptions, making them easy to catch with try...catch blocks.

// better-sqlite3: Clean error handling
try {
  const stmt = db.prepare('INSERT INTO logs (msg) VALUES (?)');
  stmt.run('System started');
} catch (err) {
  console.error('Database write failed:', err.message);
}

sqlite3 forces you into callback hell or promise chains unless you wrap it yourself. Error handling happens inside the callback, which can lead to swallowed errors if you forget to check the err argument.

// sqlite3: Error handling inside callbacks
db.run('INSERT INTO logs (msg) VALUES (?)', ['System started'], function(err) {
  if (err) {
    return console.error('Database write failed:', err.message);
  }
  console.log('Row inserted with ID:', this.lastID);
});

sqlite offers a C-like API adapted for JS. While powerful, it often requires manual binding of parameters and stepping through results, which feels more verbose than the high-level helpers in better-sqlite3.

// sqlite (sql.js): Manual stepping
const stmt = db.prepare('SELECT * FROM logs');
while (stmt.step()) {
  const row = stmt.getAsObject();
  // Process row
}
stmt.free(); // Must manually free memory

🌐 Environment Compatibility

Where your code runs is a hard constraint.

• Node.js Desktop/Server: better-sqlite3 is the performance king. sqlite3 is the legacy alternative.
• Web Browsers: Only sqlite (sql.js) works here. Native bindings cannot run in Chrome or Firefox.
• Serverless/Edge: sqlite is safest. better-sqlite3 works on some platforms (like standard AWS Lambda) but fails on others that restrict synchronous I/O or native addons.

📊 Summary: Key Differences

💡 The Big Picture

better-sqlite3 is the modern standard for Node.js development. If you are building a backend service, a desktop app with Electron, or a command-line tool, this is the package to pick. Its synchronous API removes the complexity of async database calls, and its speed is unmatched. Just ensure your deployment environment supports native modules.

sqlite (sql.js) is the universal soldier. Choose it if you need to share database logic between your Node backend and a React frontend, or if you are deploying to restrictive environments like Cloudflare Workers or browser-based IDEs. You trade some speed for the ability to run anywhere.

sqlite3 is the legacy option. While still widely installed, it offers no real advantage over better-sqlite3 for new projects. Its asynchronous nature adds code complexity without providing significant concurrency benefits for typical SQLite workloads, and its installation process is often more fragile. Reserve it for maintaining older applications that haven't been migrated yet.

Final Thought: For 90% of Node.js projects today, better-sqlite3 provides the best balance of speed, simplicity, and reliability. Reach for sqlite only when you strictly need browser compatibility or zero-native-dependency deployment.