/concepts/files-and-storage/
Files and storage
vola keeps two things apart. The bytes live on disk, named by their hash. Everything a person would call a file (its name, folder, owner, versions) is a row in the database that points at those bytes: PostgreSQL, or a single SQLite file.
Content addressing
Section titled “Content addressing”A blob is stored under the SHA-256 of its bytes, at blobs/aa/bb/cc/<sha256>, with no extension, because the name is not data.
The same bytes uploaded twice are one blob, whoever uploads them and in whichever tenant. Two rows simply cite the same hash. A blob is never overwritten: when two uploads of the same bytes race, one of them discards its temporary file.
Thumbnails are stored next to the blob they were rendered from, so files with the same content share them too. An encrypted file is the exception: its key and nonce are random per file, so its blob is unique to one row and is never deduplicated.
The rest of the storage directory holds work in progress:
| Path | What it holds |
|---|---|
blobs/aa/bb/cc/<sha256> |
A blob |
blobs/aa/bb/cc/<sha256>.thumb-<size>-<crop>.webp |
A thumbnail of a plain file |
blobs/aa/bb/cc/<sha256>.enc-<file id>-thumb-<size>-<crop> |
A sealed thumbnail of an encrypted file |
tmp/<uuid> |
A multipart upload in flight |
uploads/<upload id>.part |
The bytes of a resumable upload so far |
uploads/<upload id>.partial |
The sealed incomplete segment of an encrypted resumable upload |
Every path is derived from a validated hash or a validated derived name, so no input from a request reaches the file system. The filesystem is the only storage backend in v1.0. The interface it implements is what an S3 backend would implement later.
PostgreSQL or SQLite
Section titled “PostgreSQL or SQLite”VOLA_DATABASE_URL picks the database when the server starts: postgresql://… for PostgreSQL, the default, or file:<path> for one SQLite file. The routes, the answers and the error codes are the same on both, and so are the storage directory, the key files and every other variable. There is no tool to move an installation from one to the other, so pick when you install.
| PostgreSQL (default) | SQLite (file:<path>) |
|
|---|---|---|
| What it needs | A PostgreSQL 16 service | Nothing: Node’s built-in node:sqlite (Node 24+), one file on a local disk |
Files, folders, versions, slugs, shares, tenants, keys, Range, tus uploads, tenant / caller / client encryption, UDC lists and subscribe, statistics, transfer, the CLI |
Yes | Yes |
keyring encryption (PINs) |
Needs Redis | Needs Redis (same) |
| Thumbnails | By the worker, or inline on the first /thumb |
By the worker, or inline on the first /thumb |
| OCR and the OCR text search | Yes: worker + tesseract; tsvector + GIN |
Yes: worker + tesseract; FTS5 (how it differs) |
| The worker and Redis | Optional; the worker on any host | Optional; the worker on the server’s host, opening the same file |
| Processes | Any number of servers and workers | One server process and at most one worker, one writer at a time |
| Hosts | Any | One (the file, the server and the worker on the same machine) |
| Backup | pg_dump + the storage |
VACUUM INTO (or a copy while stopped) + the storage |
| Scaling | More servers behind a proxy, more workers | None: one process. Move to PostgreSQL when it is not enough |
| Moving to the other database | No tool | No tool |
SQLite fits a small installation that must not depend on a database service: a team’s file store, an application that embeds vola and ships as one process, a demo, an edge box. PostgreSQL fits when you need more than one server process, a worker on another machine, storage shared over the network, or a database your operations already back up and monitor. Run it on a SQLite file is the quick start, and the SQLite guide covers operating the file.
Delete and purge
Section titled “Delete and purge”A delete is soft: the row gets a deleted_at and the bytes stay. A purge is the only hard delete of a file, and it is the one moment a blob may leave the disk. It goes only when no row of any tenant cites its hash.
Uploads and purges take the same lock on the hash: a PostgreSQL advisory lock, or on SQLite the file’s one write lock, which every transaction holds from its start. That is what makes deduplication safe: a purge cannot remove a blob at the moment a new upload starts citing it.
The instance model
Section titled “The instance model”A file belongs to a tenant and to an instance: a pair of instance_type and instance_id that names an entity in your application. tickets/<uuid> is the files of one ticket, and users/<uuid> is the files of one user.
instance_type is a lowercase identifier and instance_id is a UUID. vola does not know what a ticket is. Your application keeps its own data model, and vola keeps the bytes and the hierarchy under it. The instance is in every file route:
curl -s -H "Authorization: Bearer $KEY" localhost:8300/vola/files/tickets/$TICKET | jq '.files | length'Folders
Section titled “Folders”Folders are virtual. They are a hierarchy in the database inside one instance, and the blob store stays flat.
- A path looks like
docs/2026. It can have at most 32 levels, and each segment is 1 to 255 characters. Names may hold spaces and Unicode. - Creating a folder is idempotent and creates its parents.
- Renaming or moving a folder rewrites every descendant path in one transaction. No blob moves.
- Deleting a folder that is not empty needs
?recursive=1, otherwise the answer is409 folder_not_empty. - An upload into a folder where the name already exists is renamed:
a.pdfbecomesa (1).pdf.
A folder can also carry an encryption policy, described under Encryption.
A slug gives a file a fixed name within an instance, such as avatar or logo. There is one live file per slug. PUT /vola/files/:type/:id/slug/:slug is an upsert: the new upload soft-deletes the previous live file of that slug in the same transaction.
Use a slug when your application asks for a role rather than a file: the current avatar of this user.
Versions
Section titled “Versions”A version is an upload with a parent_id. The new row points at the previous one and inherits its name and folder unless given new ones, and the same name is no collision against its own chain.
The previous version stays live. A download by path answers the newest file of that name. GET …/:fileId/versions lists the chain from any member, and a purge removes the whole chain.
Who may read a file
Section titled “Who may read a file”| Field | Who can read |
|---|---|
| Neither set | Keys of the owning tenant with files:read |
is_public |
Any authenticated tenant, by its full (type, id, fileId) |
is_global_public |
Anyone, without a key, through GET /vola/public/:fileId |
An encrypted file can never be is_global_public. Share links are a separate mechanism: a token that opens one file or one folder, with an optional password, expiry and download cap. The Share example shows them.
Tenants and keys
Section titled “Tenants and keys”Every row that belongs to a tenant carries its id, and every query is scoped by it. Another tenant’s file does not exist as far as a request can tell: the answer is 404, never 403.
An API key looks like vola_live_…, vola_test_… or vola_admin_…. The plaintext is shown once, and only its SHA-256 is stored. A request sends it in Authorization: Bearer or X-Api-Key, and a WebSocket sends it as a subprotocol.
| Scope | Allows |
|---|---|
files:read, files:write |
Reading and writing files, including resumable uploads |
folders:read, folders:write |
Listing and changing folders |
shares:write |
Creating, listing and revoking share links |
keys:write |
Managing API keys |
keyrings:write |
The PIN routes of a keyring |
encryption:caller |
Sending a per-request content key |
admin |
Admin routes |
Two headers complete the picture:
X-Tenant-Slugsays which tenant an admin key acts for. An admin key can act for any tenant.X-User-Idnames the acting user of your application. It is recorded as the uploader, and it is the owner of a keyring.
Tenants and keys are made with the vola command, inside the container: see the CLI reference.
Moving instances between tenants
Section titled “Moving instances between tenants”An admin transfer moves every row of a set of instances from one tenant to another in one transaction: files with all their versions, folders, share links, processing jobs and OCR metadata. Blobs stay where they are, because they are content-addressed and shared.
tenant-encrypted keys are re-wrapped for the destination in the same transaction. An instance that holds a keyring, caller or client file refuses the whole call, because the server holds no key to re-wrap with. A dry_run runs the same statements and rolls back.
Reading lists
Section titled “Reading lists”There are two ways to list files. The REST routes (GET /vola/files/:type/:id, GET /vola/folders/:type/:id) answer one instance or one folder level. The files UDC collection (POST /vola/udc/list) adds filters, sorting and an opaque cursor, and it requires a top-level instance_type filter. Real-time keeps those same rows live.
v1.1.1released built 519e3dc