90 lines
4.5 KiB
Markdown
90 lines
4.5 KiB
Markdown
# 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.
|