OxiDB includes an S3-style blob storage API for storing binary objects alongside your documents. Store images, PDFs, files — anything — directly in the database.

Buckets & Objects

Blob storage is organized into buckets (like S3 buckets). Each bucket contains objects identified by unique keys.

from oxidb import OxiDbClient
db = OxiDbClient("127.0.0.1", 4444)

# Create a bucket
db.create_bucket("user-avatars")

# Upload an object
with open("avatar.jpg", "rb") as f:
    data = f.read()

db.put_object("user-avatars", "alice-avatar.jpg", data,
              content_type="image/jpeg",
              metadata={"user_id": "alice", "uploaded": "2026-03-05"})

# Download an object
data, meta = db.get_object("user-avatars", "alice-avatar.jpg")
print(f"Content-Type: {meta['content_type']}")
print(f"Size: {len(data)} bytes")
print(f"ETag: {meta['etag']}")  # CRC32 checksum

# Save to file
with open("downloaded-avatar.jpg", "wb") as f:
    f.write(data)

Object Metadata

Each object stores metadata alongside the binary data:

  • content_type — MIME type (e.g., "image/jpeg", "application/pdf")
  • etag — CRC32 checksum for integrity verification
  • metadata — custom key-value pairs you can attach to any object

Practical Use Case: Image Uploads

Here's how this blog uses blob storage for image uploads with FastAPI:

from fastapi import UploadFile, File
import uuid

@app.post("/upload")
async def upload_image(file: UploadFile = File(...)):
    data = await file.read()
    key = f"{uuid.uuid4().hex}.{file.filename.split('.')[-1]}"

    db.put_object("blog-images", key, data,
                  content_type=file.content_type)

    return {"url": f"/images/{key}"}

@app.get("/images/{key}")
def serve_image(key: str):
    data, meta = db.get_object("blog-images", key)
    return Response(content=data, media_type=meta["content_type"])

Storage Format

Objects are stored in the data directory as:

_blobs/
  └── user-avatars/
      ├── alice-avatar.jpg.data   # binary content
      └── alice-avatar.jpg.meta   # JSON metadata + CRC32 etag
Blob storage is especially powerful when combined with full-text search. Store PDF and DOCX files as blobs, and OxiDB can automatically extract and index their text content for searching.