AxiomDB Documentation
AxiomDB is a self-managed PostgreSQL control plane with Git-like branching, PASETO-secured auth, network allowlisting, and automated backups — built for developer teams who want managed-database convenience on their own infrastructure.
Welcome to AxiomDB — the self-managed Postgres control plane built for developers who refuse to give up infrastructure ownership. We give you the polished developer experience of a managed database cloud, while keeping your data on your own VPS.
Quickstart
Install the CLI, provision your first project, and connect an app in under five minutes.
Projects
Create isolated project workspaces with app_key / env scoping and multi-branch support.
Branches
Git-like database branches with independent credentials, metrics, and configurable lifespans.
Network Rules
CIDR-based IP allowlisting for runtime (PgBouncer) and direct (Postgres) ports.
Auth & SSO
PASETO v4 token auth, Sign in with Square, magic links, 2FA, and CLI PKCE flows.
API Reference
Full REST API for every gateway endpoint — projects, branches, network, backups, secrets.
What is AxiomDB?
AxiomDB has two surfaces:
| Surface | Description |
|---|---|
| axiomdb-gateway | A Rust/Axum REST API that is the control plane. Handles auth, project provisioning via a Redis job queue, branch management, network rules, backup orchestration, and real-time monitoring. |
| dbs (ops console) | A Next.js web dashboard where teams manage projects, browse branches, inspect tables, visualize network rules, configure backups, and run the SQL editor. |
Both surfaces connect to the same control-plane PostgreSQL database. The actual user databases live in a data-plane PostgreSQL instance on your VPS, accessed through PgBouncer.
Architecture at a glance
┌──────────────────────────────────────────────────────────────┐
│ Client Layer │
│ Browser (dbs console) · axiomdb-cli · REST consumers │
└────────────────────────┬─────────────────────────────────────┘
│ HTTPS Bearer PASETO v4
┌────────────────────────▼─────────────────────────────────────┐
│ AxiomDB Gateway (Rust / Axum) │
│ /api/v1/auth /api/v1/projects /api/v1/branches │
│ /api/v1/network /api/v1/backups /api/v1/monitoring │
│ /api/v1/secrets /api/v1/jobs /api/v1/health │
├──────────────────────────────────────────────────────────────┤
│ Control-plane PostgreSQL (tenant-isolated, RLS enabled) │
│ Redis (project-command stream + worker consumer groups) │
├──────────────────────────────────────────────────────────────┤
│ square-dbctl (CLI wrapper on VPS) │
│ ↳ provision · branch-create · network-rules · backups │
├──────────────────────────────────────────────────────────────┤
│ Data-plane PostgreSQL + PgBouncer (user databases) │
│ db.squareexp.com:6432 (runtime / pooled) │
│ db.squareexp.com:5432 (direct / migrations) │
└──────────────────────────────────────────────────────────────┘Core concepts
Projects
A project is a workspace scoped to an app_key and an env (e.g. servers + prod). The combination forms a unique slug (servers-prod). Each project gets:
- A provisioned PostgreSQL database with three auto-created roles:
owner,runtime,readonly - A
mainbranch (default, protected, permanent) - Network policy defaulting to
restricted - An audit event log
Branches
A branch is a copy-on-write clone of a parent database. Every branch is a live, independent PostgreSQL database you can connect to. Branches support:
- Named references (e.g.
feature-x) or UUID references - Configurable lifespans:
7d,1m,6m,1y, orforever - Automatic expiry
- Independent CIDR network rules per branch
- Per-branch connection credentials (Prisma-ready
DATABASE_URL+DIRECT_URL)
Tenant isolation
Every resource (projects, branches, network rules, audit events) is tagged with a tenant_id derived from the Square IdP's OAuth2 ctx.tenant_id claim. PostgreSQL Row-Level Security (RLS) is enabled on all tables as a safety net, and every application query uses explicit WHERE tenant_id = $N clauses.
Connection strings
| Purpose | Host | Port | Format |
|---|---|---|---|
| Runtime (pooled, app traffic) | db.squareexp.com | 6432 | DATABASE_URL |
| Direct (migrations, Prisma deploy) | db.squareexp.com | 5432 | DIRECT_URL |
DATABASE_URL="postgresql://servers_prod_rw:...@db.squareexp.com:6432/sq_servers_prod?sslmode=require"
DIRECT_URL="postgresql://servers_prod_owner:...@db.squareexp.com:5432/sq_servers_prod?sslmode=require"For branches, the database name changes to the branch database (e.g. sq_servers_prod_br_feature-x).
How is this guide?