angelxmoreno / angelxmoreno/bun-sqlite-orm

[Feature]: Add WAL mode and SQLite performance optimization pragmas

Open
#13 0 comments 0 reactions 0 assignees View on GitHub
enhancement feature medium-priority minor
Dominant language
TypeScript
Stars
1
Forks
0
PR merge metrics
No merged PRs in 30d

Description

## Problem Statement
The ORM doesn't configure SQLite for optimal performance. WAL mode and other performance pragmas can dramatically improve performance, especially with concurrent readers and writers.

## Proposed Solution
Add configurable SQLite performance pragmas to DataSource initialization, including WAL mode, synchronous settings, and cache configuration.

## Alternatives Considered
- Leaving performance configuration to users
- Hard-coding optimal settings
- Providing preset performance profiles

## Example Usage
```typescript
// DataSource configuration with performance options
const dataSource = new DataSource({
database: 'app.db',
entities: [User, Post],
performance: {
walMode: true, // Enable WAL mode
synchronous: 'NORMAL', // FULL, NORMAL, or OFF
cacheSize: 64000, // Cache size in KB
foreignKeys: true, // Enable foreign key constraints
mmapSize: 268435456, // Memory-mapped I/O size
}
});

// Or individual pragma configuration
const dataSource = new DataSource({
database: 'app.db',
entities: [User, Post],
pragmas: {
'journal_mode': 'WAL',
'synchronous': 'NORMAL',
'cache_size': '-64000', // Negative = KB, positive = pages
'foreign_keys': 'ON',
'mmap_size': '268435456',
}
});
```

## Impact
- Query API: ✗
- Performance: ✓
- Entity definitions: ✗
- Validation: ✗
- Migrations: ✗
- TypeScript types: ✗
- Documentation: ✓

## Additional Context
SQLite performance optimizations to implement:

**WAL Mode Benefits:**
- Concurrent readers with single writer
- Faster writes (no blocking)
- Better crash recovery

**Other Important Pragmas:**
- `synchronous = NORMAL`: Balance safety/performance
- `cache_size = -64000`: 64MB cache for better performance
- `foreign_keys = ON`: Enable referential integrity
- `mmap_size`: Memory-mapped I/O for large databases

**Configuration Options:**
- Preset profiles (development, production, testing)
- Individual pragma control
- Runtime pragma modification
- Performance monitoring hooks

**Priority:** Medium - Significant performance gains but not breaking
**Estimated Impact:** 2-5x performance improvement in many scenarios

References:
- [SQLite WAL Mode](https://www.sqlite.org/wal.html)
- [SQLite Pragma Statements](https://www.sqlite.org/pragma.html)

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the DataSource initialization described in the issue and the linked SQLite WAL and pragma references. Define how configurable pragmas, performance options, profiles, runtime modification, and monitoring hooks should fit together. Done means the requested SQLite performance configuration is supported without changing the query API, entity definitions, validation, or migrations.

Written by the indexing model from the issue text.

Assessment

Tech stack
sqlite, typescript
Domain
database
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.