sonnet-storage

Virtual file storage backed by PostgreSQL for sonnet-server applications.

Provides a UPath-compatible filesystem abstraction over a database table. Consumers use standard pathlib operations (read_text(), write_text(), iterdir(), etc.) and the backend (local filesystem or database) is transparent.

Quick Start

from sonnet_storage import get_storage_root, register_protocol

# Register the db:// protocol (once at startup)
register_protocol()

# Use like pathlib
root = get_storage_root()
rules = root / "rules"
for f in rules.iterdir():
    content = f.read_text()

Features

• Text, JSON (native JSONB), and binary content storage
• Soft delete with recovery
• Versioning (monotonic counter per file)
• Seeding from local directories / package data
• Configurable UPath protocol name (default: db://)
• Pre-built REST router factory
• Optional StorageExtension for auto-registration

Database

PostgreSQL only. See docs/data-model.md for the complete schema reference. Consumers own their Alembic migrations -- see ADR-0002.

Documentation

• Design document
• Data model reference