angelxmoreno / angelxmoreno/bun-sqlite-orm
[Feature]: Add WAL mode and SQLite performance optimization pragmas
- 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
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