File Storage - Overview
Anvil bundles an object/blob store directly inside the database binary, so deployments don't need a sidecar S3/MinIO instance. Files live as :storage.Object nodes in the system storage schema; binary content is held by a pluggable backend (local FS by default, optionally AWS S3, Cloudflare R2, MinIO, Google Cloud Storage, or Azure Blob).
Modeled after Supabase Storage but graph-native: buckets and files are first-class graph entities, so they participate in Cypher queries, relationships, row-level security policies, triggers, and edge functions.
Architecture
The storage subsystem has three layers:
| Layer | Responsibility | Examples |
|---|---|---|
| Graph | Bucket / Object metadata as nodes | :storage.Bucket, :storage.Object |
| Refcount | Content-addressed dedup + lifetime | RefCounter::incref/decref |
| Backend | Bytes on disk or in the cloud | LocalBackend, S3Backend |
Backend blobs are content-addressed (SHA-256). Two objects with identical bytes share one backend file - uploading the same image twice is free after the first time.
How it compares
| Feature | Anvil Storage | S3 / R2 | Supabase Storage |
|---|---|---|---|
| Built-in to DB | Yes | No | Postgres extension |
| Graph-native | Yes (Cypher MATCH) | No | Partial (SQL) |
| RLS for objects | Native | IAM only | Native |
| Signed URLs | HMAC, bucket-versioned | Pre-signed | JWT-based |
| Image transform | Built-in | External (Lambda) | Pro tier |
| Resumable upload | TUS 1.0.0 | Multipart | TUS |
| Content dedup | Refcounted | No | No |
What's in the box
| Component | Surface |
|---|---|
| REST API | /storage/v1/bucket, /storage/v1/object, /storage/v1/upload/resumable, /storage/v1/render |
| Cypher DDL | CREATE BUCKET, ALTER BUCKET, DROP BUCKET, SHOW BUCKETS |
| Cypher helpers | file_url, signed_url, file_size, file_mime, bucket_size, image_metadata |
| Triggers | BEFORE/AFTER INSERT/UPDATE/DELETE on :storage.Object |
| Client SDKs | anvilent for Rust / TypeScript / Python / Go |
| CLI | anvil storage create-bucket / upload / download / ls / rm / sign / usage / gc |
| Hammer UI | /storage panel with browser, upload, preview, signed URLs |