linearvoid/docs/architecture/adr/ADR-006-data-storage.md

ADR-006: Data Storage Strategy (SQLite vs PostgreSQL)

Status: Accepted
Date: 2026-08-04
Author: AI Assistant (following AGENTS.md, ADR-002, ADR-003, ADR-004, ADR-005)
Related ADRs: ADR-001, ADR-003, ADR-005, ADR-007

Context

The system needs persistent storage for:

• Chat messages and history (public rooms and private DMs).
• User accounts, roles, and ban lists.
• Moderation audit log (immutable record of admin and moderator actions).
• Playlist and media metadata used by admin flows.
• System configuration visibility in admin APIs.

The codebase now ships with a PostgreSQL service in Docker Compose (db) and chat is configured with a PostgreSQL DATABASE_URL by default. The backend still supports SQLite for optional local fallback, but the deployed and compose-default path is PostgreSQL.

Decision Drivers

1. Implemented Reality - Docker Compose already provisions PostgreSQL and chat depends on it.
2. Concurrency & Throughput - Chat, moderation, and media metadata writes require stronger concurrent write behavior.
3. Operational Traceability - Structured backups, service health checks, and persistent volume management are already in place for PostgreSQL.
4. Admin Growth - Upcoming admin features (media CRUD, analytics, moderation tooling) benefit from relational querying and indexing.
5. Fallback Simplicity - Keep SQLite support for lightweight local or recovery scenarios without blocking developer workflows.

Decision

Primary storage for current implementation: PostgreSQL (Docker Compose db service).

Secondary/Fallback mode: SQLite remains supported via DATABASE_URL=sqlite://... for local-only scenarios.

Current Backend Behavior:

• Chat backend (backend/chat/src/main.go) resolves DATABASE_URL at startup.
• postgres:// or postgresql:// selects PostgreSQL driver.
• sqlite:// selects SQLite driver.
• Empty DATABASE_URL falls back to local chat.db for developer convenience.
• GORM AutoMigrate is used for chat/admin data models.

Media Model Decision (Admin UI Feature Track):

• Media metadata is persisted in the same database as messages and moderation logs.
• Physical media files remain on the shared filesystem (/app/media, mapped from data/media).
• The database is the source of truth for media library metadata and future runtime analytics.

Rationale

• The repository already operationalizes PostgreSQL in both docker-compose.yml and docker-compose.prod.yml with persistent storage.
• Default environment documentation (.env.example, setup docs) already points to PostgreSQL.
• This aligns architecture documentation with implemented behavior and avoids drift.
• Keeping SQLite support preserves local flexibility while avoiding a hard breaking change.

Consequences

Positive:

• Better write concurrency and query flexibility for chat + admin workloads.
• Clear operational model for containerized deployments (health checks, named volume, service dependency).
• Easier extension for admin analytics and media metadata features.

Negative / Risks:

• Additional service to operate versus embedded-only SQLite.
• Misconfigured DATABASE_URL can still route to SQLite fallback unintentionally if left empty outside compose.
• Requires backup/restore procedures for PostgreSQL volume in production runbooks.

Alternatives Considered

• SQLite-first in production: rejected for current implementation because compose and deployment already run PostgreSQL.
• PostgreSQL-only with no fallback: rejected to preserve local dev and troubleshooting flexibility.
• Managed external PostgreSQL: deferred; self-hosted compose remains the preferred operational model.

Implementation Status

1. ADR updated to match implemented state. Done.
2. Compose includes PostgreSQL service and persistent volume. Done.
3. Chat backend supports PostgreSQL and SQLite based on DATABASE_URL. Done.
4. Media metadata persistence model documented here for Admin UI track. In progress (implementation ongoing).
5. Admin storage observability and operations UI (vacuum/analyze/backup flows). Planned.

References

• ADR-001: Chat persistence, moderation log, monitoring requirements.
• ADR-003: Preference for operational simplicity and Go backend.
• ADR-005: Admin interface for user management, moderation, and analytics.
• ADR-007: Redis usage for presence, rate limiting, pub/sub.
• docker-compose.yml and docker-compose.prod.yml database service definitions.