Database Backend Selection

Executive summary

Production Ring clones use DB_BACKEND_MODE=k8s-postgres-fcm — PostgreSQL for application data, Firebase Admin only for FCM push when configured. Legacy DATABASE_MODE is removed. Pick a mode before first boot.

Backend modes (architecture)

Adapters, FCM vs Firestore, DB_HYBRID_MODE

Database migrations

schema.sql + kingdom migration order

Quick Start

First clone with Postgres

DB_BACKEND_MODE decision

The three modes

`DB_BACKEND_MODE`	Application data	Firestore for DB?	Push
`k8s-postgres-fcm`	PostgreSQL (self-hosted, k3s, Docker)	No	FCM + Apple when configured
`supabase-fcm`	PostgreSQL on Supabase	No	Same FCM pattern
`firebase-full`	Firestore paths	Yes	Full Firebase stack

Implementation: lib/database/backend-mode-config.ts, lib/database/DatabaseService.ts, lib/database/BackendSelector.ts.

ConnectPlatform (connect-brand.com) is realtime collaboration — not a DB_BACKEND_MODE adapter. See Tunnel protocol.

Setup by mode

Recommended default

OSS self-host, k3s, Ringdom handoff, PaymentConductor, News Kingdom, data/schema.sql v4.

Set mode and connection in .env.local:
Optional: DB_POOL_SIZE, DB_TIMEOUT, DB_RETRIES.
Provision PostgreSQL 14+ (18 recommended locally) — Docker docker-compose.dev.yml, Homebrew bootstrap, or your cluster.
Apply schema and migrations:
Full order: Database migrations.
FCM (optional): set NEXT_PUBLIC_FIREBASE_* + service account from env.local.template. App data stays on Postgres.

What not to use

Legacy / invalid	Replacement
`DATABASE_MODE=firebase_only` / `postgresql_only`	`DB_BACKEND_MODE` values above
`npm run db:migrate` / `db:backup`	`./scripts/run-migration.sh`, `pg_dump`
`DB_HYBRID_MODE` as primary switch	`DB_BACKEND_MODE` — see architecture page

Changing modes later

Export data from source (Firestore export or pg_dump).
Provision target Postgres; apply migrations.
Update DB_BACKEND_MODE and connection secrets on staging.
Smoke-test auth, store, payments, news before production cutover.

Pre-launch checklist (Postgres-primary):

DB_BACKEND_MODE set — app starts clean
data/schema.sql + kingdom migrations applied
Backups configured (pg_dump, CNPG, provider snapshots)
FCM vars only if push required
004_payment_transactions.sql if using payments

Environment config

Secret groupings and locale vars

Payment integration

Requires Postgres ledger

Quick Start (new clone)

One deployment per customer — Ringdom pattern

Database Backend Selection

Executive summary

Backend modes (architecture)

Adapters, FCM vs Firestore, DB_HYBRID_MODE

Database migrations

schema.sql + kingdom migration order

Quick Start

First clone with Postgres

DB_BACKEND_MODE decision

The three modes

`DB_BACKEND_MODE`	Application data	Firestore for DB?	Push
`k8s-postgres-fcm`	PostgreSQL (self-hosted, k3s, Docker)	No	FCM + Apple when configured
`supabase-fcm`	PostgreSQL on Supabase	No	Same FCM pattern
`firebase-full`	Firestore paths	Yes	Full Firebase stack

Implementation: lib/database/backend-mode-config.ts, lib/database/DatabaseService.ts, lib/database/BackendSelector.ts.

ConnectPlatform (connect-brand.com) is realtime collaboration — not a DB_BACKEND_MODE adapter. See Tunnel protocol.

Setup by mode

Recommended default

OSS self-host, k3s, Ringdom handoff, PaymentConductor, News Kingdom, data/schema.sql v4.

Set mode and connection in .env.local:
Optional: DB_POOL_SIZE, DB_TIMEOUT, DB_RETRIES.
Provision PostgreSQL 14+ (18 recommended locally) — Docker docker-compose.dev.yml, Homebrew bootstrap, or your cluster.
Apply schema and migrations:
Full order: Database migrations.
FCM (optional): set NEXT_PUBLIC_FIREBASE_* + service account from env.local.template. App data stays on Postgres.

What not to use

Legacy / invalid	Replacement
`DATABASE_MODE=firebase_only` / `postgresql_only`	`DB_BACKEND_MODE` values above
`npm run db:migrate` / `db:backup`	`./scripts/run-migration.sh`, `pg_dump`
`DB_HYBRID_MODE` as primary switch	`DB_BACKEND_MODE` — see architecture page

Changing modes later

Export data from source (Firestore export or pg_dump).
Provision target Postgres; apply migrations.
Update DB_BACKEND_MODE and connection secrets on staging.
Smoke-test auth, store, payments, news before production cutover.

Pre-launch checklist (Postgres-primary):

DB_BACKEND_MODE set — app starts clean
data/schema.sql + kingdom migrations applied
Backups configured (pg_dump, CNPG, provider snapshots)
FCM vars only if push required
004_payment_transactions.sql if using payments

Environment config

Secret groupings and locale vars

Payment integration

Requires Postgres ledger

Quick Start (new clone)

One deployment per customer — Ringdom pattern

Database Backend Selection

Executive summary

Backend modes (architecture)

Adapters, FCM vs Firestore, DB_HYBRID_MODE

Database migrations

schema.sql + kingdom migration order

Quick Start

First clone with Postgres

DB_BACKEND_MODE decision

The three modes

`DB_BACKEND_MODE`	Application data	Firestore for DB?	Push
`k8s-postgres-fcm`	PostgreSQL (self-hosted, k3s, Docker)	No	FCM + Apple when configured
`supabase-fcm`	PostgreSQL on Supabase	No	Same FCM pattern
`firebase-full`	Firestore paths	Yes	Full Firebase stack

Implementation: lib/database/backend-mode-config.ts, lib/database/DatabaseService.ts, lib/database/BackendSelector.ts.

ConnectPlatform (connect-brand.com) is realtime collaboration — not a DB_BACKEND_MODE adapter. See Tunnel protocol.

Setup by mode

Recommended default

OSS self-host, k3s, Ringdom handoff, PaymentConductor, News Kingdom, data/schema.sql v4.

Set mode and connection in .env.local:
Optional: DB_POOL_SIZE, DB_TIMEOUT, DB_RETRIES.
Provision PostgreSQL 14+ (18 recommended locally) — Docker docker-compose.dev.yml, Homebrew bootstrap, or your cluster.
Apply schema and migrations:
Full order: Database migrations.
FCM (optional): set NEXT_PUBLIC_FIREBASE_* + service account from env.local.template. App data stays on Postgres.

What not to use

Legacy / invalid	Replacement
`DATABASE_MODE=firebase_only` / `postgresql_only`	`DB_BACKEND_MODE` values above
`npm run db:migrate` / `db:backup`	`./scripts/run-migration.sh`, `pg_dump`
`DB_HYBRID_MODE` as primary switch	`DB_BACKEND_MODE` — see architecture page

Changing modes later

Export data from source (Firestore export or pg_dump).
Provision target Postgres; apply migrations.
Update DB_BACKEND_MODE and connection secrets on staging.
Smoke-test auth, store, payments, news before production cutover.

Pre-launch checklist (Postgres-primary):

DB_BACKEND_MODE set — app starts clean
data/schema.sql + kingdom migrations applied
Backups configured (pg_dump, CNPG, provider snapshots)
FCM vars only if push required
004_payment_transactions.sql if using payments

Environment config

Secret groupings and locale vars

Payment integration

Requires Postgres ledger

Quick Start (new clone)

One deployment per customer — Ringdom pattern

Documentation

Quick entry (CTOs · auditors · agents)

Documentation

Quick entry (CTOs · auditors · agents)

Documentation

Quick entry (CTOs · auditors · agents)

Loading documentation...

Documentation

Quick entry (CTOs · auditors · agents)

Loading documentation...

Documentation

Quick entry (CTOs · auditors · agents)

Loading documentation...

Documentation

Quick entry (CTOs · auditors · agents)

Loading documentation...

Loading documentation...

Loading documentation...

Database Backend Selection

Backend modes (architecture)

Database migrations

Quick Start

The three modes

Setup by mode

What not to use

Changing modes later

Environment config

Payment integration

Quick Start (new clone)

Database Backend Selection

Backend modes (architecture)

Database migrations

Quick Start

The three modes

Setup by mode

What not to use

Changing modes later

Environment config

Payment integration

Quick Start (new clone)

Database Backend Selection

Backend modes (architecture)

Database migrations

Quick Start

The three modes

Setup by mode

What not to use

Changing modes later

Environment config

Payment integration

Quick Start (new clone)