Blob Storage

Nucleus includes built-in blob storage for binary data — files, images, videos, and backups. Content-addressed with automatic deduplication, no S3 or MinIO needed.

Storing Blobs

-- Store binary data (hex-encoded) with a key
SELECT BLOB_STORE('avatar/user-1.png', '89504e470d0a1a0a...', 'image/png');

-- Store without content type
SELECT BLOB_STORE('backup/db-2026-03-08.bak', 'cafebabe...');

Retrieving Blobs

-- Get blob data (hex-encoded)
SELECT BLOB_GET('avatar/user-1.png');

-- Get metadata (size, hash, content type, tags)
SELECT BLOB_META('avatar/user-1.png');
-- → {"size":4096,"hash":"a1b2c3...","content_type":"image/png","tags":{}}

Listing & Counting

-- List all blob keys
SELECT BLOB_LIST();
-- → ["avatar/user-1.png","backup/db-2026-03-08.bak"]

-- List by prefix
SELECT BLOB_LIST('avatar/');
-- → ["avatar/user-1.png"]

-- Total blob count
SELECT BLOB_COUNT();
-- → 2

Tagging

Add custom metadata tags to blobs:

SELECT BLOB_TAG('avatar/user-1.png', 'uploaded_by', 'user-1');
SELECT BLOB_TAG('avatar/user-1.png', 'resize', '128x128');

Deleting

SELECT BLOB_DELETE('avatar/user-1.png');
-- → true

Deduplication

Nucleus uses BLAKE3 content hashing. Identical data is stored only once, regardless of key:

-- Check deduplication ratio
SELECT BLOB_DEDUP_RATIO();
-- → 2.5  (logical bytes / physical bytes)

A ratio of 2.5 means you're storing 2.5x more logical data than actual disk usage.

How It Works

• Content-addressed — BLAKE3 (256-bit) cryptographic hashing
• Chunked storage — Large objects split into 1MB chunks
• Deduplication — Identical chunks stored once across all keys
• Byte-range index — O(log N) access for partial reads
• WAL-backed — Crash-safe persistence

Use Cases

• User uploads — Avatars, attachments, documents
• Media storage — Images, videos, audio files
• Backups — Database snapshots with deduplication
• Artifacts — Build outputs, logs, reports
• Content delivery — Serve static files directly from the database