ADR-0007: Migrate WatchTower Event Storage from SQLite to PostgreSQL
Status
Accepted
Date
2026-05-30
Context
ADR-0003 selected SQLite as the primary database for WatchTower due to its lightweight setup and suitability for rapid MVP development.
As WatchTower has evolved, the project has moved toward a fully hosted architecture consisting of:
- a deployed frontend
- a deployed Node.js backend
- cloud-hosted infrastructure
While SQLite was appropriate during local development, its file-based architecture introduces challenges in hosted environments:
- database files must be managed alongside application deployments
- persistence becomes dependent on server filesystem storage
- database access is tied to a single application instance
WatchTower requires a database solution that is designed for hosted and production environments.
Decision
Replace SQLite with PostgreSQL as the primary database for WatchTower.
PostgreSQL will be used for:
- telemetry event storage
- user and project metadata
- performance metrics
- error logs
- feedback submissions
This decision supersedes ADR-0003.
Rationale
- PostgreSQL is designed for hosted and production deployments
- Separates application infrastructure from data storage
- Allows the backend and database to be deployed independently
- Supported by major cloud providers and hosting platforms
- Simplifies long-term deployment and maintenance
- Provides a clear path for future scalability without requiring another database migration
- Integrates well with the existing Node.js backend architecture
Alternatives Considered
Continue Using SQLite
Rejected because SQLite is primarily intended for local and embedded use cases. Its file-based storage model creates deployment and infrastructure limitations for a hosted observability platform.
MongoDB
Rejected because WatchTower’s DB accesses are configured for relational queries and migrating would incur a big overhead.
Consequences
Positive
- Better alignment with hosted deployment architecture
- Clear separation between application and database infrastructure
- Easier cloud deployment and management
- Improved maintainability
- Supports future growth without another database migration
Negative
- Increased deployment complexity
- Requires management of a dedicated database service
- Higher operational overhead compared to SQLite
- Existing SQLite data may require migration
Supersedes
ADR-0003: Use SQLite for WatchTower Event Storage
Conclusion
PostgreSQL was selected because it better aligns with WatchTower’s transition from a local prototype to a hosted observability platform. While SQLite was effective for MVP development, PostgreSQL provides a more suitable foundation for deployment, maintenance, and future expansion.