1 ADR 0032 postgis deployment and restore validation
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

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:

  1. Docker Compose / deployment documentation must use or support a PostGIS-capable PostgreSQL image/configuration.
  2. Database migrations should create/verify the PostGIS extension before creating reverse lookup geometry/geography tables or indexes.
  3. Core/Admin health should expose reverse lookup as unavailable/degraded when PostGIS is missing or unusable.
  4. Backup/restore documentation and validation must include a PostGIS restore check before claiming fidelity restore for reverse lookup data.
  5. 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.