Flux documentation

Flux is a PostgreSQL-first platform for running many isolated projects: each project gets a database surface, a REST API (PostgREST), routing identity, and authentication configuration. You evolve the system with SQL migrations, not a proprietary object layer.

What you will learn

  • Where to start if you are new vs. returning
  • The three ideas Flux keeps repeating
  • How the docs are organized

The idea

Flux orchestrates infrastructure (containers, routing, secrets) so you can treat each project as a small, repeatable backend. v2 shared packs many tenants onto a shared cluster with schema- and role-level isolation and a gateway at the edge. v1 dedicated gives a project its own Postgres and PostgREST when you need stronger physical separation.

The docs are ordered so you understand what Flux is and why it is trustworthy before you reach exhaustive CLI and environment reference.

How this site is organized

PathPurpose
IntroductionIdentity, philosophy, mental model
Getting startedInstall CLI → project → first request → auth
ConceptsDurable terms: projects, migrations, JWTs, RLS, engines, URLs
ArchitectureHow control plane, gateway, and data plane connect
SecurityTrust boundaries, secrets, threat model
GuidesOpinionated app integration paths
ExamplesEnd-to-end narratives
ReferenceCLI, env vars, config — after you have context

Core principles

  1. PostgreSQL-first — Your schema and SQL are the source of truth.
  2. Migration-first — Schema changes flow through migrations (flux push and friends).
  3. Coherent isolation — Pooled and dedicated are explicit deployment models with honest tradeoffs, not marketing tiers alone.

Minimal workflow

bash
curl -sL https://flux.vsl-base.com/install | bashexport FLUX_API_BASE="https://flux.vsl-base.com/api"export FLUX_API_TOKEN="flx_live_…"flux loginflux create "percept"flux list   # copy slug + 7-char hash for the project rowflux push db/migrations/0001_moods.sql --project percept --hash b915ec8

The --project and --hash values must match your flux list output (the line above uses example values). Alternatively, add slug and hash to flux.json so flux push can resolve the project without repeating flags—see Configuration.

Your app then calls the Service URL for the project (see Service URLs) with the right auth model for your engine.

Next steps