AxiomDB

AxiomDB is a self-managed Postgres control plane built for terminal-first teams who demand the ergonomics of a managed platform without surrendering infrastructure sovereignty. It abstracts the operational complexity of PostgreSQL lifecycle management — provisioning, branching, credential rotation, network policy, backup orchestration, and audit — behind a unified API surface exposed through a web console, a Rust-powered gateway, and the axm CLI.

The mental model

AxiomDB separates the control plane from the data plane. The control plane manages metadata, authorization, provisioning orchestration, and audit. The data plane is vanilla PostgreSQL on your VPS — enhanced with PgBouncer pooling, automated role provisioning, network allowlisting, and backup integration.

Architecture overview

AxiomDB is composed of four primary runtime surfaces that work in concert to deliver a cohesive database management experience:

Control plane gateway

The AxiomDB Gateway is an Axum-based Rust service that exposes the /api/v1 REST API. It handles authentication via PASETO v4 tokens issued through Square IdP (OAuth2/OIDC), manages the control-plane PostgreSQL database, and dispatches provisioning commands through a Redis-backed command queue consumed by square-dbctl workers.

┌─────────────────────────────────────────────────────────────────┐
│                        AxiomDB Gateway                          │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────────┐│
│  │  Auth     │  │ Projects │  │ Branches │  │ Network/Backup/  ││
│  │  (PASETO) │  │  Router  │  │  Router  │  │ Monitoring/...   ││
│  └─────┬────┘  └─────┬────┘  └─────┬────┘  └────────┬─────────┘│
│        │             │             │                 │          │
│  ┌─────▼─────────────▼─────────────▼─────────────────▼────────┐ │
│  │                  Control-plane PostgreSQL                   │ │
│  │  users · projects · project_branches · network_rules ·      │ │
│  │  provisioning_jobs · audit_events · credential_events ·     │ │
│  │  network_policies · cors_origins · api_tokens               │ │
│  └─────────────────────────┬───────────────────────────────────┘ │
│                            │                                     │
│  ┌─────────────────────────▼───────────────────────────────────┐ │
│  │              Redis Command Queue (async jobs)                │ │
│  └─────────────────────────┬───────────────────────────────────┘ │
│                            │                                     │
│  ┌─────────────────────────▼───────────────────────────────────┐ │
│  │          square-dbctl worker (provisioning engine)           │ │
│  │  CREATE DATABASE · CREATE ROLE · GRANT · PgBouncer · UFW ·  │ │
│  │  pgBackRest · credential generation · network apply          │ │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

Web console

The Ops Console is a Next.js application that provides the operational UI for managing projects, branches, network rules, schema inspection, backups, monitoring, and team administration. It authenticates users through Square IdP and proxies API requests to the gateway.

CLI (axm)

The axm CLI is a Rust binary distributed via npm (axiomdb-cli). It authenticates through browser-based OAuth2 PKCE flow and provides terminal-native access to every gateway endpoint — project creation, branch management, URL generation, credential rotation, network allowlisting, monitoring, backup operations, and audit trail inspection.

Data plane

The data plane is your VPS running PostgreSQL 14+, PgBouncer on port 6432, and Nginx as the TLS termination proxy. Every branch gets its own database, its own set of Postgres roles (owner, runtime read/write, read-only), and its own credential pair. The gateway orchestrates provisioning through square-dbctl, which executes DDL commands, manages PgBouncer userlists, configures UFW rules, and integrates with pgBackRest for backup operations.

Standard connection contract

Every branch exposes two Prisma-ready URLs that follow a strict, portable contract:

DATABASE_URL="postgresql://<runtime-role>:<password>@db.squareexp.com:6432/<branch-db>?sslmode=require"
DIRECT_URL="postgresql://<owner-role>:<password>@db.squareexp.com:5432/<branch-db>?sslmode=require"

Database naming convention

Every database and role follows a deterministic naming pattern that makes infrastructure self-documenting:

# Main branch
Database: sq_<app_key>_<env>
Example:  sq_square_experience_main

# Child branches
Database: sq_<app_key>_<env>_br_<branch_slug>
Example:  sq_square_experience_main_br_feature-auth

# Roles
Owner:    <app_key>_<env>_owner
Runtime:  <app_key>_<env>_rw
Readonly: <app_key>_<env>_ro

Security baseline

AxiomDB enforces security at every layer of the stack:

• TLS everywhere — sslmode=require on every public connection. The db.squareexp.com certificate is trusted and auto-renewed into Postgres and PgBouncer.
• Role isolation — Runtime roles never get CREATEDB. Only the direct/migration owner role can create databases (required for Prisma shadow DBs).
• Credential masking — Secrets are masked by default in the UI and API. Full credentials are only returned from branch credential endpoints and are never logged.
• Network allowlisting — Restricted mode is the default. Only explicitly allowed CIDRs can reach Postgres. Public mode requires owner role and typed confirmation.
• Audit trail — Every mutation writes an audit event with actor, target, IP, user agent, old value, and new value.
• PASETO v4 tokens — Authentication uses PASETO v4 public tokens with Ed25519 signatures, verified against Square IdP key endpoints.

Daily workflow

1. Sign in through Square IdP (browser OAuth2 or CLI PKCE)
2. Create a project — the control plane provisions a protected `main` branch
3. Add your device IP in Network — the gateway detects and stores your CIDR
4. Open Connect on a branch — copy the Prisma env block
5. Run migrations using DIRECT_URL (port 5432, owner role)
6. Create short-lived branches for risky schema work or preview environments
7. Monitor health from the dashboard or CLI
8. Rotate credentials when needed — the gateway updates Postgres, PgBouncer, and the secret store atomically
9. Delete disposable branches when work is complete

What makes AxiomDB different

Technology stack