feat(stack): run OrioleDB through db.orioledb_version

[avallete]

Summary

TL;DR: The experimental local stack can now run OrioleDB through db.orioledb_version, on both the Docker and native runtimes. It uses the new slim-services OrioleDB release line (<upstream>-orioledb). A version without a published artifact fails closed, listing the supported ones.

Before

flowchart LR
  A["db.orioledb_version set"] --> B{"experimental stack?"}
  B -- yes --> C["error: unsupported by the experimental stack"]
  B -- no --> D["Compose: docker.io supabase/postgres:<v>-orioledb"]

Loading

After

flowchart LR
  A["db.orioledb_version set"] --> B{"OrioleDB pin in catalog?"}
  B -- no --> C["fail closed: lists published versions"]
  B -- yes --> D["stack: slim &lt;v&gt;-orioledb-rN<br/>docker or native"]
  D --> E["db diff / declarative shadow<br/>use the same pin"]
  D --> F["data reuse only within<br/>the OrioleDB line"]
  G["slim-services publishes<br/>&lt;v&gt;-orioledb-r0"] --> H["catalog sync opens<br/>add postgres PR"]
  H --> B

Loading

Why

OrioleDB is leaving experimental. The new stack rejected db.orioledb_version with db.orioledb_version is unsupported by the experimental stack. supabase/slim-services#315 now builds and publishes OrioleDB as its own Postgres release line, next to stock 15 and 17, so the stack can pin it like any other artifact.

What changed

• Catalog sync. -orioledb releases form their own catalog line (17-orioledb).
  • The first publish opens an add PR.
  • Later releases upgrade or hotfix that line on their own.
  • An OrioleDB release never touches the stock 17 pin, and the reverse.
  • Legacy tags without -rN are ignored.
• One version resolver. db.orioledb_version (and SUPABASE_DB_ORIOLEDB_VERSION) resolves to <v>-orioledb through one shared resolver. stack start, the db diff shadow and its cache key, and the versions output all use it.
  • The setting requires db.major_version = 17.
  • An unpinned version fails with the list of published versions.
  • postgresVersion("17") still resolves to stock.
• Data safety. The ready-marker, PG_VERSION and snapshot checks compare the engine line, not only the major. Stock and OrioleDB data, snapshots and shadow caches never mix.
  • Unmarked data, including data left behind by an interrupted first start, is refused for an OrioleDB request.
  • The error suggests supabase stack destroy.
  • Switching orioledb_version on a saved stack requires stack destroy, because the stack keeps its database version.
• test db. Maps OrioleDB to its major for pg_prove.
• Declarative shadow. Keeps the image-installed orioledb extension, which the shadow's own tables depend on. Its CREATE EXTENSION is replayed as IF NOT EXISTS in the shadow copy only.
• Compose. With SUPABASE_USE_SLIM_IMAGES, Compose maps supabase/postgres:<v>-orioledb to the pinned slim OrioleDB image. Unpinned versions stay on docker.io.
• Docs. stack-commands.md, SIDE_EFFECTS.md, packages/stack/ARCHITECTURE.md and ADR 0026.

It also pins the first published OrioleDB release, 17.11.0.002-orioledb-r0, added with the catalog sync's --release mode. Later OrioleDB releases arrive through the existing slim-release-published sync.

Linked issue

Part of CLI-2387. Depends on supabase/slim-services#315.

🤖 Generated with Claude Code

[github-actions]

🤖 AI Review

Both independent reviews were available; Codex reported no findings. Code inspection confirmed two minor diagnostic/recovery concerns and refuted the test-coverage finding. All three findings are preserved, with citations corrected to actual file lines. Tests were not run.

Findings

Severity	Location	Category	Sources	Claim
🟡 MINOR	packages/stack/src/storage/DockerDatabaseStorage.ts:843	error-handling	claude	The new checks for unfinished Docker database initialization report a major mismatch as “Initialized PostgreSQL major does not match the requested configuration” and provide no recovery guidance.
🟡 MINOR	packages/stack/src/services/Database.ts:679	ux	claude	An OrioleDB first start interrupted after PG_VERSION is written but before the ready marker is published cannot resume on a subsequent start, even when the data came from the requested artifact. The error directs users to destroy the stack.

Refuted findings (kept for transparency, not posted as review comments)

• apps/cli/src/commands/db/shared/pgdelta-declarative-shadow-prep.unit.test.ts:76 (test-coverage): The new “keeps an image-installed orioledb instead of dropping it” test is ineffective coverage because it passes without this PR; IMAGE_KEPT_EXTENSIONS affects filesForDeclarativeShadowLoad rather than prepareDeclarativeShadow.
  Refuted: Passing before the PR is accurate, but the test directly guards its named no-drop invariant through prepareDeclarativeShadow. Changing declaration classification to include OrioleDB would execute SHOW server_version at implementation line 172 and fail the empty-query assertion. The adjacent test at test-file lines 56-71 separately verifies the new IF NOT EXISTS rewrite, so that behavior is covered.

Stats

Claude findings: 3 · Codex findings: 0 · Confirmed: 2 · Refuted: 1 · Uncertain: 0

---

Models: claude-opus-5-5 + gpt-6.1-sol · Trigger: auto · Workflow run

This review runs once per PR. A maintainer can request another with a /ai-review comment.