@photostructure/sqlite

Native SQLite for Node.js 22+. Drop-in replacement for node:sqlite. Synced with Node.js v26.7.0 for the latest features including native Symbol.dispose resource management.

Installation

npm install @photostructure/sqlite

Quick Start

import { DatabaseSync } from "@photostructure/sqlite";

const db = new DatabaseSync(":memory:");
db.exec("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)");
const insert = db.prepare("INSERT INTO users (name) VALUES (?)");
insert.run("Alice");
const users = db.prepare("SELECT * FROM users").all();
console.log(users); // [{ id: 1, name: 'Alice' }]
db.close();

Experimental async pool

Server workloads that must keep SQLite execution off the event loop can use the experimental fixed-size connection pool:

import { DatabasePool } from "@photostructure/sqlite/experimental";

await using pool = await DatabasePool.open("app.db", {
  connections: 2,
  connectionSetup: [
    { sql: "PRAGMA journal_mode=WAL" },
    { sql: "PRAGMA busy_timeout=5000" },
  ],
});

const user = await pool.get("SELECT * FROM users WHERE id = ?", [1]);

The experimental entry point deliberately offers only connection-independent run, get, all, and batch operations. Review its authorizer, setup, ordering, memory, and libuv tradeoffs in the async pool guide before using it in production.

Features

• API-compatible with Node.js v26.7.0 built-in node:sqlite module*
• Zero dependencies - native SQLite implementation
• Stable synchronous API with no async overhead on the root entry point
• Native SQLite performance (benchmarks and tradeoffs)
• Experimental async connection pool for off-event-loop SQLite execution
• Full SQLite feature set (details)
• TypeScript support with complete type definitions
• Cross-platform prebuilt binaries (Windows/macOS/Linux, x64/ARM64)
• User-defined functions and aggregates
• Database backups and session/changeset support
• Session class exposed for advanced replication workflows
• Native Symbol.dispose for resource management
• enhance() function for better-sqlite3 style .pragma() and .transaction() methods
• URI filename support for advanced configuration
• Worker thread safe
• Compare with other libraries →

Performance

For most applications, @photostructure/sqlite is fast enough that SQLite or storage will be the bottleneck. Durable single-row writes match node:sqlite and better-sqlite3, and indexed single-row reads are within roughly 20% of the fastest driver in our benchmarks.

The exception is materializing large result sets. This package uses the stable Node-API ABI for compatibility across Node.js releases, so each returned value crosses that boundary. node:sqlite can use internal V8 bulk constructors that addons cannot use through stable Node-API. If thousand-row reads are a hot path in your application, review the results and run the benchmark.

Note

*API-compatible with Node.js SQLite, but this library adopts SQLite-recommended features and security-enhancing build flags. See build configuration details.

Documentation

Getting Started

• Installation & Setup
• Migrating from node:sqlite
• Migrating from better-sqlite3

Using SQLite

• Working with Data
• Extending SQLite
• Advanced Patterns
• Experimental Async Pool

Reference

• API Reference
• All Features
• Build Flags & Configuration
• Library Comparison

License

MIT - see LICENSE for details.

This package includes SQLite (public domain) and code from Node.js (MIT licensed).

---

Note: This package is not affiliated with the Node.js project. It extracts and redistributes Node.js's SQLite implementation under the MIT license.