angelxmoreno / angelxmoreno/bun-sqlite-orm
[Feature]: Add support for binary data (BLOB) handling
- Dominant language
- TypeScript
- Stars
- 1
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
## Problem Statement
The ORM doesn't provide proper support for binary data storage and retrieval. SQLite supports BLOB data types, and bun:sqlite handles `Uint8Array` and `Buffer` types, but the ORM lacks integration for these data types.
## Proposed Solution
Add proper BLOB data type support with automatic conversion between JavaScript binary types (`Uint8Array`, `Buffer`) and SQLite BLOB storage.
## Alternatives Considered
- Base64 encoding for binary data storage as TEXT
- Manual conversion by users
- External file storage with path references
## Example Usage
```typescript
// Entity with binary data
@Entity('files')
class FileEntity extends BaseEntity {
@PrimaryGeneratedColumn('increment')
id\!: number;
@Column()
name\!: string;
@Column({ type: 'blob' })
content\!: Uint8Array; // Binary file content
@Column({ type: 'blob', nullable: true })
thumbnail?: Buffer; // Optional thumbnail image
}
// Usage with binary data
const imageBuffer = await Bun.file('image.png').arrayBuffer();
const file = FileEntity.build({
name: 'image.png',
content: new Uint8Array(imageBuffer)
});
await file.save();
// Retrieve and use binary data
const savedFile = await FileEntity.get(1);
await Bun.write('output.png', savedFile.content);
// Query with binary data conditions (size, etc.)
const largeFiles = await FileEntity.find({
// Custom query for BLOB length
});
```
## Impact
- Query API: ✗
- Performance: ✗
- Entity definitions: ✓
- Validation: ✗
- Migrations: ✗
- TypeScript types: ✓
- Documentation: ✓
## Additional Context
**Binary Data Types Support:**
- `Uint8Array` - Typed array for binary data
- `Buffer` - Node.js/Bun buffer type
- `ArrayBuffer` - Raw binary data buffer
**SQLite BLOB Features:**
- Efficient binary storage
- Streaming for large data
- BLOB length queries
- Partial BLOB updates
**Implementation Requirements:**
- Column type detection for BLOB
- Automatic type conversion in `_loadFromRow`
- Parameter binding for binary types
- Type validation for BLOB columns
- Size limits and validation
**Use Cases:**
- File storage (images, documents, etc.)
- Serialized binary data
- Encrypted data storage
- Audio/video metadata
- Binary configuration data
**Technical Considerations:**
- Memory usage for large BLOBs
- Streaming support for huge files
- BLOB indexing limitations
- Query performance with binary data
- Serialization for JSON APIs
**Validation Support:**
```typescript
@Entity('files')
class FileEntity extends BaseEntity {
@Column({ type: 'blob' })
@IsNotEmpty()
@MaxBlobSize(10 * 1024 * 1024) // 10MB limit
content\!: Uint8Array;
}
```
**Query Enhancements:**
```typescript
// BLOB-specific query methods
const files = await FileEntity.find({
// length(content) > 1000
}).where('length(content) > ?', [1000]);
```
**Priority:** Low - Specialized use case, many applications don't need BLOB storage
**Estimated Impact:** Enables file storage use cases within the database
Contributor guide
Research direction
Start by locating the ORM's _loadFromRow path, column type detection, and parameter binding, then inspect how entity definitions and TypeScript types are handled. Done should include BLOB columns accepting the listed binary types, storing and retrieving them correctly, and covering the requested validation and query behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- bun, sqlite, typescript
- Domain
- databases
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100