ADR 0032: PostGIS Deployment And Restore Validation
Status: accepted Date: 2026-05-22
Context
ADR 0023 selects PostgreSQL + PostGIS for reverse place lookup storage/indexing. That adds an operational dependency that must be explicit in Docker Compose, migrations, backup, restore, and validation. Memories' priorities include self-hostability, low operational surprise, and reliable fidelity restore. PostGIS cannot be an implicit assumption that fails only after an operator tries to import a gazetteer or restore a backup.
Options Considered
| Option | Summary | Benefits | Costs / Risks |
|---|---|---|---|
| A. Assume PostGIS exists | Migrations use PostGIS and fail if unavailable | Minimal app logic | Poor error messages; restore/import surprises |
| B. Bundle PostGIS-capable DB deployment and preflight | Compose uses PostGIS-capable image/config; Core/migrations check extension availability | Clear self-host path; early failures; reliable restore story | Slightly heavier DB image/dependency |
| C. Optional PostGIS feature flag | Reverse lookup disabled unless PostGIS configured | Flexible | More conditional code/ops; feature may degrade silently |
| D. Separate spatial service | Dedicated geospatial database/service | Isolation | Overkill for household deployment |
Decision
Use a PostGIS-capable PostgreSQL deployment with explicit preflight/migration and restore validation.
For the first reverse lookup implementation:
- Docker Compose / deployment documentation must use or support a PostGIS-capable PostgreSQL image/configuration.
- Database migrations should create/verify the PostGIS extension before creating reverse lookup geometry/geography tables or indexes.
- Core/Admin health should expose reverse lookup as unavailable/degraded when PostGIS is missing or unusable.
- Backup/restore documentation and validation must include a PostGIS restore check before claiming fidelity restore for reverse lookup data.
- JSON/JSONL export remains inspectable and should not require PostGIS to read outside Memories, but fidelity restore of cached labels/imported provider rows does require PostGIS availability.
This decision applies to reverse lookup. It does not make PostGIS a general requirement for all Memories deployments until the reverse lookup feature is enabled/used, but the supported deployment path for that feature must be explicit.
Consequences
Positive
- Avoids hidden deployment surprises.
- Makes backup/restore behavior honest.
- Keeps spatial data inside the existing PostgreSQL authority boundary.
- Gives operators clear degraded-state diagnostics when PostGIS is unavailable.
Negative / Costs
- Requires Docker/deployment changes or documentation for PostGIS-capable PostgreSQL.
- Tests need a PostGIS-capable integration path.
- Operators using custom PostgreSQL must install/enable the extension.
- Reverse lookup cannot be considered production-ready until restore validation covers PostGIS.
Revisit Triggers
Revisit this decision if:
- PostGIS materially complicates household deployment beyond expected cost.
- Memories introduces a separate supported database deployment pattern.
- Reverse lookup data is moved to a reinstallable external index instead of PostgreSQL.
- A future migration needs to support instances that enabled reverse lookup without PostGIS, which should not happen under this decision.
Memories Wiki
Using Memories
- Accounts, the Library Hub, and Data Export
- Albums and Automatic Suggestions
- Explore and Discovery Domains
- The Media Viewer
- People and Faces
- Places and Map
- Plants (In Development)
- Datenschutzerklärung (Privacy Policy)
- Fast, Progressive Image Loading
- Search
- Sharing and Households
- Timeline and Photos
- Uploading and Import
Self-Hosting
- Backup and Restore
- CLI Password Reset
- Deployment Architecture
- Known Issues and Operator Diagnostics
- Map Tiles and Place Data Privacy
- Storage Layout
- Upgrades and Versioning
- Workers
Reference