better-sqlite3 — самая быстрая и простая библиотека SQLite для Node.js
📂 Исходный код на GitHubСамая быстрая и простая библиотека SQLite для Node.js: синхронный API, полная поддержка транзакций, пользовательские функции, виртуальные таблицы и расширения.
better-sqlite3 — самая быстрая и простая библиотека SQLite для Node.js
better-sqlite3 — библиотека для работы с SQLite в Node.js. Автор называет её самой быстрой и самой простой библиотекой SQLite для этой платформы. Под капотом это нативное расширение на C++, а сверху — аккуратный синхронный API. Лицензия MIT, последняя версия — v13.2.0. Это обычный инструмент разработчика, а не AI-проект, но пригодится он везде, где приложению на Node.js нужна локальная база данных.
Зачем ещё одна библиотека для SQLite
В Node.js давно есть пакет node-sqlite3 с асинхронным API. Он популярен, но у его асинхронности есть цена:
- асинхронные вызовы для задач, упирающихся в процессор, тратят ресурсы впустую;
- несколько параллельных запросов конкурируют за мьютексы и замедляют друг друга;
- пакет открывает низкоуровневое управление памятью на C, хотя сборщик мусора JavaScript справляется с этой работой надёжнее.
better-sqlite3 выбирает другой путь. API здесь синхронный, памятью управляет сборщик мусора, а сложные операции спрятаны за готовыми вспомогательными методами. Код читается проще, и в большинстве сценариев он ещё и быстрее.
Почему синхронный API — это нормально
На первый взгляд синхронный API противоречит духу Node.js, где принято всё делать асинхронно. Но SQLite работает в том же процессе, что и ваш код. Асинхронная обёртка не добавляет здесь настоящей параллельности: она лишь перекладывает те же операции в очередь и добавляет лишние накладные расходы.
Поэтому автор формулирует это так: для SQLite синхронный API даёт лучшую параллельность, чем асинхронный. Да, вы прочитали правильно — так и написано в описании библиотеки.
Для тяжёлых и медленных запросов библиотека поддерживает потоки Worker: вынесенный в отдельный поток запрос не останавливает основной процесс.
Производительность
В репозитории есть бенчмарки, которые сравнивают better-sqlite3 с популярными пакетами sqlite и sqlite3. Числа показывают, во сколько раз конкуренты медленнее (базовый уровень — 1x):
| Операция | Во сколько раз медленнее sqlite / sqlite3 |
|---|---|
Выборка одной строки (get()) |
в 11,7 раза |
Выборка ста строк (all()) |
в 2,9 раза |
Построчная выборка ста строк (iterate()) |
в 24,4 раза |
Вставка одной строки (run()) |
в 2,8 раза |
| Вставка ста строк в одной транзакции | в 15,6 раза |
Это не абстрактные цифры. Автор приводит практический пример: при правильных индексах библиотека выдерживает около 2000 запросов в секунду с пятью соединениями (JOIN) в базе на 60 ГБ, где каждый запрос возвращает от 5 до 50 КБ данных.
Возможности
- Полная поддержка транзакций.
- Пользовательские функции, агрегаты, виртуальные таблицы и расширения.
- 64-битные целые числа: «невидимы», пока они вам не понадобятся.
- Потоки Worker для больших и медленных запросов.
- Режим WAL: одна строка кода включает журнал упреждающей записи, который рекомендуют включать ради производительности.
Установка и первые запросы
npm install better-sqlite3
Библиотека требует актуальной поддерживаемой версии Node.js. Для основных платформ и архитектур есть готовые бинарные сборки, поэтому npm обычно просто скачивает нужный файл. Если сборки для вашей платформы нет, пакет скомпилируется на месте; на случай проблем есть отдельное руководство по устранению неполадок.
CommonJS:
const db = require('better-sqlite3')('foobar.db', options);
const row = db.prepare('SELECT * FROM users WHERE id = ?').get(userId);
db.pragma('journal_mode = WAL');
ESM:
import Database from 'better-sqlite3';
const db = new Database('foobar.db', options);
db.pragma('journal_mode = WAL');
API компактный: метод prepare() один раз собирает запрос, а дальше методы get(), all(), iterate() и run() выполняют его и возвращают результат в удобном виде. Метод run() заодно сообщает, сколько строк изменилось, и возвращает lastInsertRowid.
Транзакции
Транзакции — одна из главных фишек библиотеки. Метод transaction() оборачивает обычную функцию в транзакцию: она стартует при вызове, фиксируется после успешного возврата и откатывается при ошибке.
const insert = db.prepare('INSERT INTO cats (name, age) VALUES (@name, @age)');
const insertMany = db.transaction((cats) => {
for (const cat of cats) insert.run(cat);
});
insertMany([
{ name: 'Joey', age: 2 },
{ name: 'Sally', age: 4 },
]);
Вложенные вызовы автоматически превращаются в savepoints: ошибка внутри вложенной функции откатывает её до точки сохранения, а внешняя транзакция может откатиться вся. Есть варианты запуска deferred, immediate и exclusive. Ограничение одно: внутри транзакции нельзя использовать async-функции — транзакция зафиксируется раньше, чем выполнится асинхронный код.
Когда SQLite не подойдёт
Автор честно описывает границы применимости и советует брать полноценную СУБД вроде PostgreSQL, если у вас:
- большой поток параллельных чтений, где каждый запрос возвращает мегабайты данных, например видео;
- высокая конкуренция записей, как в социальной сети;
- база данных приближается к размеру в терабайт.
SQLite отлично подходит, когда база живёт внутри одного приложения. А высокая параллельная нагрузка на больших объёмах данных — уже задача для полноценной СУБД.
Документация
Документация разбита на отдельные файлы в репозитории:
- Полный справочник API
- Производительность и лучшие практики
- Бенчмарки
- Работа с 64-битными целыми числами
- Потоки Worker
- Небезопасный режим
- Компиляция из исходников
- Устранение неполадок при установке
Итог
better-sqlite3 — зрелый проект: он развивается с 2016 года и придерживается простого подхода. Синхронный API там, где он действительно быстрее, готовые сборки для всех платформ и подробная документация. Если вашему приложению на Node.js нужна локальная база данных, это самый короткий путь от npm install до работающего кода.
Проект распространяется по лицензии MIT.