# 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-001.md), [ADR-003](./ADR-003-tech-stack.md), [ADR-005](./ADR-005-admin-moderation-analytics.md), [ADR-007](./ADR-007-redis-usage.md)

## 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.