# Data model and durable storage

Separate canonical data from files and rebuildable search indexes.

DATABASE_URL selects PostgreSQL. If it is unset, Ralti uses the local SQLite database at .atlas/atlas.sqlite, with ATLAS_DATA_DIR overriding the private data root. The application stores workspaces, workbook metadata, sheets, fields, records, views, history, collaborations, email, jobs, and workflow definitions in normalized tables. It does not create a SQL table for every sheet.

## Typed records and transactions

Records store typed values associated with their fields. Ralti validates field semantics before saving changes and preserves undo history. Existing saved work remains readable as the application evolves.

| Data | Location | Recovery requirement |
| --- | --- | --- |
| Canonical entities | PostgreSQL or atlas.sqlite | Consistent database backup |
| Uploaded bytes and private document artifacts | Private persistent filesystem | File backup coordinated with application writes |
| Email credentials | Encrypted database values | Database backup plus separately preserved encryption key |
| SQLite semantic index | search-v1.sqlite sidecar | Rebuildable from canonical sources |

PostgreSQL is the intended coordinated deployment option: it supplies pooled access, permissions, revision locks, shared rate limits, and native search indexes. SQLite remains a single-host fallback with single-writer constraints. Do not place its live files on ephemeral storage or share them over a network filesystem.

> **Scaling is more than selecting a database** Uploads remain filesystem-backed. Multiple application hosts need durable shared file access before they can serve the same attachments reliably. Some mutation validation and computed-field filters still inspect complete workspaces; measure memory, transaction latency, and pool pressure with representative data.

A database dump alone does not recover uploaded files or the email encryption secret. Conversely, the semantic sidecar is not your source of truth. Keep source databases private and never package the data directory into a public website or container image.