Startseite Erkunden Hilfe
Anmelden
flndrn
/
Briven
1
1
Fork 0
Dateien Issues 0 Pull-Requests 0 Wiki Actions
Branch: main
Branches Tags
Briven
/
docs
/
knowledge-base.md

knowledge-base.md 59 KB
Permalink Verlauf Originalformat

Doltgres - knowledge base

Briven Auth rebuild — SuperTokens knowledge base

Purpose: Library cabinet for LLM agents building new Briven Auth. These are reference docs from SuperTokens — borrow good product/architecture ideas. Briven Auth stays Briven-branded, multi-tenant on Briven Doltgres, not a raw SuperTokens install.

Date filed: 2026-07-22 URL count: 492 unique

How agents should use this

HARD RULE (flndrn, 2026-07-26 — never break)

Before any Auth change (magic link, OTP, OAuth/Konnos, sessions, MFA, passkeys, FDI, IdP, SSO, providers, secrets, allowed domains, enable/disable Auth, or any code under Auth surfaces):

  1. You must open this file first.
  2. You must open the matching SuperTokens section/URL below for that feature.
  3. You must not guess login behavior. SuperTokens is the product map; Briven implements Briven-branded on Doltgres.
  4. State in one plain sentence what the SuperTokens/KB behavior is, then code.

Also written into project root CLAUDE.md. Skipping this step is a rule violation, not a style preference.

Always

  1. Prefer Briven product rules (Doltgres-first, project isolation, pk_briven_auth_, no inventing Clerk).
  2. For any database / Doltgres / Postgres-wire problem, open the Doltgres / Dolt official knowledge base section at the bottom of this file first (URLs from AI_DOCS/dolt-reference/). Also read AI_DOCS/dolt-reference/00-doltgres-truth.md.
  3. When stuck on a login feature (sessions, passwordless, MFA, etc.), open the matching SuperTokens section below and keep Doltgres constraints from the Doltgres section.
  4. Translate Supabase/MySQL examples to Briven Doltgres using official Doltgres docs — do not invent.
  5. Do not paste SuperTokens branding into Briven UI — yellow Auth sub-dashboard, Briven styling.
  6. Never abandon SuperTokens Core or change Auth architecture after one SQL error without reading Doltgres docs and notifying flndrn.

Quickstart

Quickstart integrations

Authentication recipes

Additional verification (sessions, MFA, roles, captcha)

Post-authentication (sessions, users, dashboard)

Migration

Platform configuration

Deployment

References (SDKs, FDI, CDI, plugins, testing)

Briven-specific mapping notes

SuperTokens docs say Briven Auth must do
Supabase Briven Doltgres per project
MySQL migrate Migrate / store on Doltgres
Self-host Core Hosted by Briven platform (users do not run Core)
App domain backend SDK First-party auth on app + Briven Auth control plane
Dashboard Yellow Briven Auth sidebar section (sub-dashboard)

Briven Pay build

Briven database — Doltgres / Dolt official knowledge base

Purpose: Library cabinet for EVERY Briven build that touches SQL, Auth, backups, or Postgres-family compatibility. Source: (1) flndrn official www.doltgres.com list (PRIMARY, complete set below) + (2) URLs from AI_DOCS/dolt-reference/* (local notes + often dolthub.com MySQL-Dolt siblings) (already in this repo). Agents must open these — do not guess. HARD RULE: On any Doltgres / Postgres-wire error (including SuperTokens Core or any tool built for Postgres), search this section + AI_DOCS/dolt-reference/00-doltgres-truth.md before changing architecture. Never quit after one SQL error without reading these and notifying flndrn with options.

Local distilled files (always read first)

  • AI_DOCS/dolt-reference/00-doltgres-truth.md — authoritative DoltGres facts (Postgres-flavored)
  • AI_DOCS/dolt-reference/01-intro-install.md
  • AI_DOCS/dolt-reference/02-use-cases.md
  • AI_DOCS/dolt-reference/03-concepts-git.md
  • AI_DOCS/dolt-reference/04-concepts-sql.md
  • AI_DOCS/dolt-reference/05-rdbms-dolthub.md
  • AI_DOCS/dolt-reference/06-sqlref-server.md
  • AI_DOCS/dolt-reference/07-sqlref-version-control.md
  • DOLTGRES-FIRST.md — Briven hard product rule

Official DoltGres docs (www.doltgres.com) — PRIMARY for Briven

Filed from flndrn full URL list (2026-07-22). These are the real DoltGres product docs (Postgres-flavored). Prefer these over dolthub.com MySQL-Dolt pages when they overlap. Count: 51 URLs

Introduction

Concepts — git / version control

Concepts — SQL

Concepts — RDBMS

Guides

Reference — server

Reference — version control

Reference — SQL support (Postgres-family gaps live here)

Reference — clients

Reference — benchmarks

Introduction / install

Use cases

Concepts — overview + git / version control

Concepts — SQL

Concepts — RDBMS + DoltHub product

SQL reference — server ops

SQL reference — version control API

Blogs (product state / calling conventions)

GitHub install (Dolt sibling — only if needed for concept)

Agent workflow when something fails on Doltgres

  1. Read AI_DOCS/dolt-reference/00-doltgres-truth.md and the matching URL group above.
  2. Doltgres = Postgres family (port 5432, pg driver). Missing feature ≠ abandon the product.
  3. Prefer workarounds (SQL rewrite, session settings, driver, version, config) over stock Postgres.
  4. Notify flndrn with: error text, which doc URL you used, options A/B/C — before switching architecture.

Doltgres version pinning + upgrade process (flndrn, 2026-08-01)

Rule: Keep our Doltgres version in step with upstream. When DoltHub ships a new dolthub/doltgresql release, we evaluate and (after testing) move our pinned version along — because their releases carry the lock/concurrency/panic fixes we depend on. Do this as a manual, tested process — NOT an auto-updater/Watchtower/host-side poller (forbidden by infra/CLAUDE.md).

  • Where the version is pinned: infra/dokploy/compose.dokploy.yml — the doltgres, dolt-backup, and init services all use image: dolthub/doltgresql:<version> (a readable version tag, not an opaque @sha256 digest, so the version is visible + bumpable). Current pin: 0.57.2 (upgraded from 0.56.6 on 2026-08-01).
  • Watch for new releases: https://github.com/dolthub/doltgresql/releases and https://github.com/dolthub/doltgresql/issues (customer-tagged issues show active fixes).
  • Upgrade procedure (tested, no-guess):
    1. Read the new release notes for lock / GC / panic / connection-stability fixes.
    2. Validate data-read on a throwaway first: docker run the new image on a fresh volume (fresh-init), cp -a a copy of the live db dirs in, start, and confirm it reads them (select count(*) from information_schema.tables … on briven_control). Doltgres upgrades are forward-compatible in practice (0.56.6 → 0.57.2 read cleanly, no migration).
    3. Set behavior.auto_gc_behavior.enable: false in config.yaml (see incident below).
    4. Bump the tag in BOTH the repo compose and France /code compose, swap the prepared data into the live volume, and recreate via scripts/safe-redeploy-service.sh doltgres.
    5. Verify version (select dolt_version()), all DBs serve, API boots, then watch it hold under load past the previous failure window before calling it done.

INCIDENT 2026-08-01 — Doltgres locked-under-load → whole platform 404 (ROOT-CAUSE FIXED)

Symptom: api.briven.tech returns Traefik 404 page not found on every route (incl. /health); api container crash-loops stuck at applying migrations…; Doltgres is "healthy" but serves zero databases — every psql connect (even postgres/template1) returns FATAL: "database X does not exist", and trace logs show database "briven_control" is locked by another dolt process … holds an exclusive write lock even with the server stopped and no other process alive. Recurs within 4–50 minutes of normal API write load. All 22 DB dirs on disk are intact (.dolt/noms valid) — not data loss.

Root cause: Doltgres 0.56.6 (our pin) has a database-lock defect under concurrent write load. Upstream 0.57.1 shipped a lock-subsystem rewrite (LockSubsystem.TryLock) and 0.56.9 fixed an INSERT panic (a regression since 0.56.5 — our 0.56.6 was affected). 0.56.6 also predates the auto_gc_behavior config, and 0.57.1 enabled auto-GC by default (auto-GC "breaks all open connections"). NOT related to issue #2600 (that's app-level advisory locks). Verified against release notes, not guessed.

The SOLID fix (on Doltgres, per DOLTGRES-FIRST — no Postgres):

  1. Upgrade 0.56.6 → 0.57.2 (validated: 0.57.2 reads 0.56.6 data unchanged; briven_control 51 tables, briven_engine 23 — no migration).
  2. Disable auto-GC in config.yaml: under behavior: add auto_gc_behavior:\n enable: false (only valid on 0.57.x — 0.56.6 rejects the key with field auto_gc_behavior not found, which is how you know you must upgrade first).
  3. Recreate doltgres on 0.57.2 with the prepared data; restart API; watch it hold under load.

Emergency triage (temporary, if you must restore before upgrading): a cp -a of each DB dir to fresh inodes clears the stale lock and the server serves again — but on 0.56.6 it re-jams under load within minutes-to-an-hour. It is NOT a fix; only the version upgrade is. Recipe that reliably serves: fresh-init an EMPTY volume (entrypoint), then copy the DB dirs in — a populated-but-uninitialized data-dir will NOT serve; and never leave *.dirty/rollback DB copies inside the data-dir (Doltgres enumerates every subdir and one bad copy aborts the whole multi-DB load).

Gotchas hit during the fix: (a) the dolt-backup job's dolt_backup(sync-url) writes to every live DB and accelerates the lock/GC failure — keep it disabled until its method is reworked to cold snapshots; (b) a stray docker run --rm doltgres can linger and hold the volume lock — always docker rm -f; (c) load secrets into a shell var from docker inspect … DOLTGRES_PASSWORD / .env.prod — never literal in a command.

2026-08-02 — REBOOT-SAFETY PROVEN LIVE (corrects the "restart doesn't recover" belief)

A controlled live test on France settled the open question of whether 0.57.2 survives a restart/host-reboot:

  1. docker restart the healthy live doltgres → all 24 databases re-served within 8s, briven_control reachable, held steady across 64s of polling.
  2. docker restart the api → healthy + public /health+/ready = 200 within 8s, routing intact (/v1/ → 404, not 5xx).

Conclusion: Doltgres 0.57.2 is reboot-safe. The earlier "a plain docker restart does NOT recover it" note was wrong-cause — those restarts were of a container already poisoned by a full-deploy recreate under load; restarting an already-broken container can't help, but restarting a healthy one is clean (which is all a host reboot does).

The ONE remaining outage trigger is a full Dokploy deploy (compose up --build --remove-orphans) that recreates doltgres while it's under write load (re-runs the entrypoint on a live-but-busy data dir). So "100% production solid" = two locks, not a code change:

  • autoDeploy OFF (verified via Dokploy API 2026-08-02: briven-france compose autoDeploy: false) — a git push can no longer auto-rebuild.
  • Service-scoped redeploys only (scripts/safe-redeploy-service.sh <svc>, never recreates doltgres). Full compose.deploy only for the "red-panel → one green" rule (gotcha #13).

Proven-good under every normal op: load (373k-req + 10-writer stress, 0 errors), restart/ reboot (above), dolt_backup+restart (throwaway). Data is never lost — a not-serving state keeps every DB dir intact on the _doltgres_data volume; recovery recipe is the fresh-init+copy above. (Note: the Dokploy panel may show composeStatus: error from the 08-01 failed run — that is a stale badge, not live health; the running stack is healthy.)