@rinari/bun-sqlite

High-performance Bun-native SQLite driver for Rinari ORM using bun:sqlite.

Features

• Bun-native performance - Built on Bun's native bun:sqlite module
• 3-6x faster than better-sqlite3 for read queries
• Synchronous API - No async/await needed
• Multi-database support - Manage multiple SQLite files
• ACID transactions - Automatic rollback on errors
• Advanced query operators - $gt, $lt, $in, $like, $between, etc.
• Index management - Create and drop indexes
• WAL mode - Write-Ahead Logging for better concurrency
• Comprehensive aggregations - SUM, AVG, MIN, MAX, COUNT

Requirements

• Bun runtime (>=1.0.0)
• This driver only works with Bun, not Node.js

Installation

bun add @rinari/bun-sqlite @rinari/orm @rinari/types

Quick Start

import { BunSQLiteDriver } from '@rinari/bun-sqlite';
import { ORM } from '@rinari/orm';
import { DataTypes } from '@rinari/types';

// Initialize driver
const driver = new BunSQLiteDriver({
  storageDir: './data',
});

// Create ORM instance
const orm = new ORM({ driver });

// Define a model
const User = orm.define('default', 'users', {
  id: { type: DataTypes.INTEGER, primaryKey: true, autoIncrement: true },
  username: { type: DataTypes.TEXT, notNull: true, unique: true },
  email: { type: DataTypes.TEXT, notNull: true },
  age: { type: DataTypes.INTEGER },
});

// Use it!
const alice = User.create({
  username: 'alice',
  email: '[email protected]',
  age: 25,
});

const adults = User.findAll({
  where: { age: { $gte: 18 } },
});

// Cleanup
orm.disconnect();

Why Bun SQLite?

Bun's native SQLite implementation is significantly faster than better-sqlite3:

• 3-6x faster for read queries
• 8-9x faster than deno.land/x/sqlite
• Native integration with Bun runtime
• Zero external dependencies

Performance Comparison

Based on the Northwind Traders dataset:

| Operation | better-sqlite3 | bun:sqlite | Speedup | | -------------- | -------------- | ---------- | ------- | | SELECT queries | 100ms | 20-30ms | 3-5x | | Bulk inserts | 50ms | 15ms | 3x |

API Documentation

Driver Configuration

interface DriverConfig {
  storageDir: string; // Directory for database files
  verbose?: boolean; // Log SQL statements
  readonly?: boolean; // Open in read-only mode
}

Creating the Driver

const driver = new BunSQLiteDriver({
  storageDir: './data',
  verbose: false, // Enable SQL logging
  readonly: false, // Read-write mode
});

Queries

// Find one
const user = User.findOne({ where: { username: 'alice' } });

// Find all with filters
const adults = User.findAll({
  where: { age: { $gte: 18 } },
  orderBy: [['age', 'DESC']],
  limit: 10,
});

// Count
const count = User.count({ status: 'active' });

// Aggregations
const totalAge = User.sum('age');
const avgAge = User.avg('age');
const maxAge = User.max('age');

Transactions

const result = orm.getDriver().transaction(() => {
  const user = User.create({ username: 'alice' });
  Profile.create({ user_id: user.id, bio: 'Hello' });
  return user;
});

Indexes

User.createIndex('idx_email', {
  unique: true,
  columns: ['email'],
});

User.createIndex('idx_user_status', {
  columns: ['status', 'created_at'],
});

Advanced Features

Multi-Database Support

const driver = new BunSQLiteDriver({
  storageDir: './data',
});

const orm = new ORM({ driver });

// Each database name creates a separate .sqlite file
const User = orm.define('users_db', 'users', userSchema);
const Product = orm.define('products_db', 'products', productSchema);

console.log(orm.getDatabases()); // ['users_db', 'products_db']

WAL Mode

Write-Ahead Logging is automatically enabled for better concurrency and performance.

Query Operators

// Comparison operators
User.findAll({ where: { age: { $gt: 18 } } }); // greater than
User.findAll({ where: { age: { $gte: 18 } } }); // greater than or equal
User.findAll({ where: { age: { $lt: 65 } } }); // less than
User.findAll({ where: { age: { $lte: 65 } } }); // less than or equal
User.findAll({ where: { age: { $ne: 25 } } }); // not equal

// Range operators
User.findAll({ where: { age: { $between: [18, 65] } } });
User.findAll({ where: { status: { $in: ['active', 'premium'] } } });
User.findAll({ where: { status: { $notIn: ['banned'] } } });

// Pattern matching
User.findAll({ where: { username: { $like: '%alice%' } } });

Comparison with @rinari/sqlite

| Feature | @rinari/sqlite | @rinari/bun-sqlite | | ------------ | --------------------------- | ------------------ | | Runtime | Node.js, Bun (experimental) | Bun only | | Backend | better-sqlite3 | bun:sqlite | | Performance | Fast | 3-6x faster | | Dependencies | better-sqlite3 | None (native) | | API | Identical | Identical |

Examples

See the examples/bun-sqlite-basic directory for a complete working example.

License

OpenUwU Open License (OUOL-1.0)