Getting Started

Get AxiomDB running in under five minutes — from first login to your first live connection string.

Prerequisites

Before you begin, make sure you have:

A Square organization account (required for SSO / PASETO token issuance)
The axm CLI installed (or access to the AxiomDB web console at https://axiomdb.squareexp.com)
Network access to db.squareexp.com on ports 5432 and 6432

AxiomDB uses Sign in with Square as its primary auth flow. Your identity is verified by the Square IdP (authlayer) and a short-lived PASETO v4 public token is issued to the gateway.

Open https://axiomdb.squareexp.com in your browser. You will be redirected to the Square IdP authorization endpoint. After approving, you land on the Projects dashboard.

axm login
# Opens your browser to the Square IdP authorize endpoint
# The CLI uses PKCE (S256 code challenge) for the token exchange
# Tokens are stored locally and auto-refreshed

Magic-link login is also supported. Run axm login --magic-link your@email.com or use the Send magic link option on the sign-in page.

Step 2 — Create a project

A project represents one application in one environment. The identity key is the combination of app_key (your app name) and env (e.g. prod, dev, staging).

Click New Project on the dashboard.
Fill in Name, App Key, and Environment.
Click Create — the gateway enqueues a provisioning job and you see a real-time status update.

axm projects create \
  --name "Servers API" \
  --app-key servers \
  --env prod

POST /api/v1/projects
Authorization: Bearer <paseto-v4-token>
Content-Type: application/json

{
  "name": "Servers API",
  "app_key": "servers",
  "env": "prod"
}

Response (202 Accepted — provisioning is async):

{
  "job_id": "3fa85f64-...",
  "status": "queued",
  "name": "Servers API",
  "app_key": "servers",
  "env": "prod",
  "slug": "servers-prod"
}

What happens during provisioning?

The gateway publishes a message to the Redis stream axiomdb:project_commands. A background worker picks it up and calls square-dbctl provision --app servers --env prod on the VPS. This creates:

Resource	Name Pattern
PostgreSQL database	`sq_servers_prod`
Owner (migration) role	`servers_prod_owner`
Runtime (app) role	`servers_prod_rw`
Read-only role	`servers_prod_ro`
`main` branch	protected, permanent
Secret keys in zone.env	`DATABASE_URL_SERVERS_PROD`, `DIRECT_URL_SERVERS_PROD`

Step 3 — Allow your IP

AxiomDB databases are restricted by default. You must add a CIDR rule before connecting.

# Check your current IP
axm network my-ip

# Add an allowlist rule (project scope, both ports)
axm network allow \
  --project servers-prod \
  --cidr "203.0.113.10/32" \
  --label "My laptop" \
  --ports both

The gateway applies the rule to PgBouncer (port 6432) and PostgreSQL pg_hba.conf (port 5432) in real time.

Step 4 — Get connection credentials

axm projects credentials --project <project-id>

Or from the web console: open your project → Connections tab.

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"

Step 5 — Connect your framework

// schema.prisma
datasource db {
  provider  = "postgresql"
  url       = env("DATABASE_URL")
  directUrl = env("DIRECT_URL")
}

npx prisma migrate dev
# Uses DIRECT_URL for schema migration (bypasses PgBouncer)
# Uses DATABASE_URL for runtime queries (pooled)

import { drizzle } from 'drizzle-orm/node-postgres';
import { Pool } from 'pg';

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  ssl: { rejectUnauthorized: false },
});
export const db = drizzle(pool);

import { Pool } from 'pg';

export const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  ssl: { rejectUnauthorized: false },
});

from sqlalchemy import create_engine

engine = create_engine(
    os.environ["DATABASE_URL"],
    connect_args={"sslmode": "require"},
    pool_pre_ping=True,
)

import "github.com/jackc/pgx/v5/pgxpool"

pool, err := pgxpool.New(ctx, os.Getenv("DATABASE_URL"))

Next steps

Create a branch — isolate schema changes from main
Configure network rules — fine-grained CIDR allowlisting per project or branch
Set up 2FA — add TOTP or email 2FA to your account
View monitoring — real-time CPU, memory, and Postgres connection metrics

On this page