ADR-015: Local Database Topology

• Status: Accepted
• Date: 2026-08-18
• Roadmap task: F1-005
• Decision owners: database platform maintainers

Context

Munderecat needs a disposable local PostgreSQL environment that can later replay migrations, expose public through PostgREST and run in CI. The local topology must be reproducible for outside contributors while remaining fully isolated from the certified legacy reference container supabase_db_sql_ref_only.

Two orchestration layers were available: a repository-maintained Docker Compose stack or Supabase CLI. Maintaining Compose directly would make this repository responsible for compatible versions, boot order, roles, health checks and configuration across PostgreSQL, PostgREST and the gateway. The CLI already owns those relationships and provides migration reset and status semantics used by Supabase development.

Official references:

• Local development workflow
• CLI configuration
• Localhost-only Docker network guidance
• Supabase CLI and version pinning

Decision

Orchestrator

Supabase CLI is the sole owner of the local Supabase service topology.

• The repository does not maintain an equivalent Docker Compose file.
• CLI version 2.114.0 is an exact root development dependency and is run through pnpm. A machine-global CLI is not part of the project contract.
• Docker remains the container runtime. The CLI owns service image selection, startup order, health checks, volumes, status and reset behavior.
• CLI upgrades are reviewed dependency changes because they can change both commands and service images.

Ownership And Location

db is passed as the Supabase CLI work directory. The supported CLI layout is therefore rooted at db/supabase/.

This small nesting is intentional: all persistent database configuration and future migration artifacts remain under the db ownership boundary while the CLI receives its required supabase/ project layout. Application packages do not import or own these files.

Initial Service Surface

The first stack runs only what the current project needs:

• PostgreSQL major 17,
• Supabase gateway plumbing required by the CLI,
• PostgREST with only public exposed.

Auth, Storage, Realtime, Studio, local mail, analytics, Edge Runtime and the connection pooler are disabled. A later product task may enable one only with its configuration, security boundary and verification in the same change.

This packet intentionally contains no application migration or seed. F1 proves that the empty platform can start and reset; canonical schema and corpus work begin in their owning roadmap phases.

Isolation Contract

• CLI project ID is munderecat-local.
• Host ports use 55320 through 55322, avoiding legacy port 54322.
• Startup must use a dedicated Docker bridge network configured with com.docker.network.bridge.host_binding_ipv4=127.0.0.1.
• Host binding must also be probed. Docker Desktop 29.2.1 on macOS was observed to ignore that documented bridge option for CLI-published ports and expose them on the LAN address. Therefore the F1-005 stack contains no sensitive or corpus data and is stopped after lifecycle tests. F1-031 must provide a verified host-binding or equivalent access-control gate before real data is loaded into a local stack.
• Local commands explicitly use --workdir db; commands that can choose local or linked targets must also state --local where supported.
• The project is never linked to a hosted Supabase instance as part of local bootstrap.
• Local volumes, .temp, .branches, credentials, dumps and generated state are not committed.
• The certified legacy container never joins the local network and its identity, image, port, volumes and running state are invariant across local lifecycle tests.

F1-006 will encode network creation and CLI lifecycle in the repository’s one task runner. It must not claim loopback-only binding without a real non-loopback probe. Until then, the canonical manual sequence is:

docker network inspect munderecat-local >/dev/null 2>&1 || \
  docker network create \
    -o com.docker.network.bridge.host_binding_ipv4=127.0.0.1 \
    munderecat-local
pnpm exec supabase --workdir db start --network-id munderecat-local
pnpm exec supabase --workdir db status
pnpm exec supabase --workdir db db reset --local
pnpm exec supabase --workdir db stop --no-backup

Consequences

Benefits

• Contributors receive a versioned, resettable Supabase-compatible DB/API environment without reproducing service wiring.
• The public-only initial surface is substantially smaller than the full local Supabase stack.
• Exact CLI and lockfile versions make image-topology changes visible in code review.
• Unique project, ports, network and volumes prevent accidental coupling to legacy or another local project.
• DB-owned files stay together under db.

Costs

• Docker images remain an external cache and the first start can require a sizable download.
• The CLI, rather than Compose YAML, is required to inspect the complete generated service topology.
• db/supabase/ is one level deeper than the CLI’s common repository-root example; commands must use --workdir db until F1-006 wraps them.
• A CLI upgrade can alter service images even when application SQL is unchanged, so upgrades require lifecycle replay.
• Docker Desktop may publish the CLI-managed ports on all host interfaces even when the dedicated bridge requests loopback binding. The stack must remain disposable and empty until F1-031 adds a verified control.

Alternatives Considered

Hand-Maintained Full Supabase Compose

This provides direct YAML visibility but duplicates upstream service wiring and makes the repository responsible for coordinated image, role, health and gateway updates. It was rejected as a large, drifting maintenance surface.

PostgreSQL-Only Compose

This is smaller, but cannot verify PostgREST RPC/API behavior and does not match the target Supabase runtime closely enough for migration and policy work. It was rejected as insufficient parity.

Full Supabase CLI Stack

Starting every optional service is simple but consumes more memory, images and ports than this phase needs. Optional services are disabled until demanded.

Machine-Global Supabase CLI

It avoids a package dependency but makes contributor and CI behavior depend on ambient machine state. Exact project pinning was selected instead.

Revisit Conditions

• Supabase CLI can no longer run a public PostgREST stack without remote credentials or unrelated services.
• Required local behavior cannot be configured or inspected through the CLI.
• Production moves away from Supabase/PostgREST.
• Cross-platform contributors cannot reliably use the db work-directory layout.
• Supabase CLI or the active Docker runtime adds a supported, verifiable way to bind published local ports explicitly to loopback; F1-031 should adopt it.