angelxmoreno / angelxmoreno/bun-sqlite-orm

[Feature]: Add support for binary data (BLOB) handling

Open
#17 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 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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.