Database Schema

Entity-relationship diagram of the PostgreSQL metadata store. Hover over any table for column details and usage context.

Legend

Symbol	Meaning
PK	Primary key column
FK	Foreign key reference
`\|\|--o{`	One-to-many relationship
BIGSERIAL	Auto-incrementing surrogate key
text_pattern_ops	B-tree index optimized for LIKE prefix queries

Table Summary

Table	Purpose	Primary Key
backend_quotas	Backend registry with storage quota tracking	`backend_name`
object_locations	Maps objects to backends (supports replication)	`(object_key, backend_name)`
multipart_uploads	In-progress multipart upload state	`upload_id`
multipart_parts	Individual parts within a multipart upload	`(upload_id, part_number)`
backend_usage	Monthly API/bandwidth counters per backend	`(backend_name, period)`
cleanup_queue	Retry queue for failed orphan deletions	`id` (auto-increment)
cleanup_dlq	Dead-letter for cleanup_queue rows that exhausted retries	`id` (auto-increment)
pending_objects	In-flight PUT intents (PUT-before-COMMIT write-path crash recovery)	`intent_id` (UUID)
notification_outbox	Durable webhook event delivery queue	`id` (auto-increment)

Schema Migrations

Migration	Description
`00001_init_schema`	All six tables, indexes, and foreign keys
`00002_multipart_metadata`	Add `metadata` JSONB column to `multipart_uploads`
`00003_add_encryption`	Add encryption columns to `object_locations` and `multipart_parts`
`00004_add_orphan_bytes`	Add `orphan_bytes` to `backend_quotas` and `size_bytes` to `cleanup_queue`
`00005_add_content_hash`	Add `content_hash` to `object_locations` for integrity verification
`00006_add_indexes_and_tablesample`	Performance indexes on `multipart_uploads(backend_name)` and `object_locations(object_key, created_at)`
`00007_notification_outbox`	Add `notification_outbox` table for durable webhook event delivery
`00008_pending_objects`	Add `pending_objects` table for the PUT-before-COMMIT write-path pattern
`00009_cleanup_dlq`	Add `cleanup_dlq` table so retry-exhausted cleanup rows surface for operator action
`00010_multipart_upload_encryption`	Add `encryption_key` and `key_id` columns to `multipart_uploads` so every part of an encrypted upload shares one wrapped DEK
`00011_cleanup_queue_claim`	Add `claimed_at` and `claimed_by` to `cleanup_queue`; replace the partial index with `idx_cleanup_queue_claim (next_retry, created_at) WHERE attempts < 10`; supports the `ClaimPendingCleanups` `FOR UPDATE SKIP LOCKED` worker pattern that prevents cross-instance double-processing