angelxmoreno / angelxmoreno/bun-sqlite-orm
[Feature]: Add support for loading SQLite extensions
- Dominant language
- TypeScript
- Stars
- 1
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
## Problem Statement
The ORM doesn't provide a way to load SQLite extensions, limiting users from accessing advanced SQLite functionality like FTS (Full-Text Search), JSON functions, or custom extensions.
## Proposed Solution
Add extension loading support to DataSource configuration, leveraging bun:sqlite's `loadExtension()` method with proper error handling and platform considerations.
## Alternatives Considered
- Manual extension loading by users after DataSource creation
- Plugin system within the ORM
- Built-in implementations of common extensions
## Example Usage
```typescript
// DataSource with extensions
const dataSource = new DataSource({
database: 'app.db',
entities: [User, Post],
extensions: [
'fts5', // Full-text search
'json1', // JSON functions
'./custom-ext' // Custom extension
]
});
// Or load extensions after initialization
await dataSource.initialize();
await dataSource.loadExtension('fts5');
// Use extension features in queries
const results = await dataSource.database.query(`
SELECT * FROM posts
WHERE posts MATCH 'search term'
`).all();
// Extension configuration with options
const dataSource = new DataSource({
database: 'app.db',
entities: [User],
extensions: [
{
name: 'custom-ext',
path: './extensions/custom.so',
entryPoint: 'custom_init' // Optional entry point
}
]
});
```
## Impact
- Query API: ✓
- Performance: ✗
- Entity definitions: ✗
- Validation: ✗
- Migrations: ✗
- TypeScript types: ✗
- Documentation: ✓
## Additional Context
**Common SQLite Extensions:**
- **FTS5**: Full-text search capabilities
- **JSON1**: JSON functions and operators
- **R-Tree**: Spatial indexing
- **ICU**: International text processing
- **Math**: Mathematical functions
- **Custom**: User-defined extensions
**Platform Considerations:**
- **macOS**: Requires custom SQLite build (not Apple's version)
- **Linux**: Standard SQLite typically supports extensions
- **Windows**: Extension support varies by SQLite build
**Implementation Features:**
- Extension path resolution
- Error handling for missing extensions
- Platform-specific loading logic
- Extension dependency management
- Runtime extension loading/unloading
**Error Handling:**
```typescript
try {
await dataSource.loadExtension('fts5');
} catch (error) {
if (error.message.includes('not authorized')) {
console.warn('Extension loading disabled or not supported');
} else {
throw new DatabaseError(`Failed to load extension: ${error.message}`);
}
}
```
**Configuration Options:**
- Pre-load extensions during initialization
- Lazy loading when needed
- Extension availability checking
- Fallback behavior for missing extensions
**Priority:** Low - Advanced feature for specific use cases
**Estimated Impact:** Enables advanced SQLite functionality for power users
**References:**
- [SQLite Extension Loading](https://www.sqlite.org/loadext.html)
- [bun:sqlite Extension Support](https://bun.sh/docs/api/sqlite#loadextension)
Contributor guide
Research direction
Read the DataSource configuration and initialization entry points, then compare them with bun:sqlite's loadExtension() API. The scope needs to be narrowed across configuration, runtime loading, error handling, platform considerations, and documentation; done means the agreed subset is implemented and verified.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- bun, sqlite, typescript
- Domain
- database
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100