angelxmoreno / angelxmoreno/bun-sqlite-orm

[Feature]: Add support for loading SQLite extensions

Open
#16 0 comments 0 reactions 0 assignees View on GitHub
enhancement feature low-priority minor
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.