ZeroBucket

Your database. Your images. Zero buckets.

ZeroBucket is a database-native image storage library. It lets you store and retrieve images using the PostgreSQL database you already have, instead of standing up a separate object-storage service like S3.

from zerobucket import ZeroBucket

images = ZeroBucket(database_url="postgresql://...")

image_id = images.put("avatar.jpg")

image = images.get(image_id)
print(image.mime_type)   # "image/jpeg"
print(image.size_bytes)  # 1116478
print(image.data)        # raw bytes, ready to serve

Full documentation, architecture notes, and benchmark results live in the GitHub repository.

Installation

pip install zerobucket

Requires Python 3.10+ and PostgreSQL 13+ (uses gen_random_uuid(), built in since Postgres 13).

Quick reference

from zerobucket import ZeroBucket, ImageNotFoundError, ImageValidationError

images = ZeroBucket(
    database_url="postgresql://user:pass@localhost/mydb",
    max_bytes=8 * 1024 * 1024,  # default: 8MB
)

image_id = images.put("photo.jpg")
image_id = images.put(open("photo.jpg", "rb"))
image_id = images.put(request.files["avatar"])  # framework upload objects

image = images.get(image_id)
info = images.metadata(image_id)

try:
    images.get("nonexistent-id")
except ImageNotFoundError:
    ...

try:
    images.put("not-actually-an-image.txt")
except ImageValidationError:
    ...

Serving from a web API

from flask import Flask, Response

app = Flask(__name__)
images = ZeroBucket(database_url=DATABASE_URL)

@app.route("/images/<image_id>")
def serve_image(image_id):
    image = images.get(image_id)
    return Response(image.data, mimetype=image.mime_type)

What it validates

• Format: JPEG, PNG, WebP — detected from actual file content, never from filename extension or a client-supplied Content-Type header.
• Corruption: truncated or malformed images are decoded and rejected before they reach the database.
• Decompression bombs: a tiny compressed file that decodes to an enormous pixel grid is rejected, not silently allocated.
• Size: configurable via max_bytes (default 8MB) — see the benchmark results for why.

Limitations (read before using in production)

• Not built for large files or high-volume media. Full images are read into memory on both ends of every request — no streaming, no range requests, no CDN.
• No deduplication yet. A SHA-256 checksum is stored on every row, but duplicate uploads currently create duplicate rows.
• No resize/optimization pipeline yet. ZeroBucket validates and stores what you give it; it doesn't transform it.
• PostgreSQL only, for now. The storage layer is abstracted for future adapters, but only Postgres exists today.

See the full README and roadmap on GitHub for more detail, including why BYTEA storage doesn't compress image bytes any further than they already are.

License

MIT — see LICENSE.