Account and Onboarding

Welcome to AxiomDB! In this guide, we'll walk you through everything you need to know to go from zero setup to a fully functioning AxiomDB workspace with your application connected. By the time we're done, you'll have your own organization, a new project, a protected main branch, an allowlisted device, and your first Prisma migration up and running. Let's get started!

Before we begin

Before we dive in, let's make sure you have a few things ready to go:

Step 1 — Sign up with Square IdP

To keep things secure and simple, AxiomDB delegates authentication to Square IdP, which is your organization's centralized identity provider. This means you won't need to create or remember yet another password for AxiomDB—your identity is safely managed via OAuth2/OIDC with PASETO v4 tokens.

Signing up via the Web Console

Here is how you can sign up using your browser:

1. Head over to the Ops Console at https://axiomdb.squareexp.com.
2. Click the Sign in with Square button.
3. You'll be whisked away to the Square IdP authorization page.
4. Go ahead and log in using your usual organizational credentials.
5. Once you're authenticated, the IdP will send you back to us with an authorization code.
6. Our gateway will quickly swap that code for security tokens and set up your user record.
7. You'll land right on the Projects page—which means your workspace is ready to roll!

Signing up via the CLI

If you prefer working in the terminal, the CLI uses a handy browser-based OAuth2 PKCE flow. The best part? It doesn't require a client secret:

npm install -g axiomdb-cli
axm login

Here's what happens behind the scenes when you run this:

1. The CLI generates a PKCE code verifier and challenge to keep the connection secure.
2. It opens up your default browser and points it to the Square IdP authorization endpoint.
3. It starts up a temporary local server on your machine to listen for the response.
4. In your terminal, you'll see a prompt: Complete sign-in in browser...
5. After you log in via the browser, it redirects back to your local server with an authorization code.
6. The CLI wraps things up by exchanging the code for tokens and saving your session locally.
7. If the automatic redirect doesn't work for some reason, don't worry! You can easily copy and paste the authorization code or the full redirect URL manually.

Double-checking your session

Once you've signed in, you can verify that everything is working and see who you're logged in as by running:

axm whoami

This command will show you your user ID, email address, the organization you belong to, and your active role.

Step 2 — Set up your organization

When you log in for the first time, AxiomDB automatically links your user account to an organization. Think of an organization as your team's main workspace—it holds all your projects, team members, billing details, and audit logs.

Understanding organization fields

Here is a quick look at the main fields for an organization:

Inviting your teammates

Sharing is caring! If you're an organization owner or admin, you can easily invite teammates using either the Web Console or the API:

# Via console
# Navigate to Settings > Team > Invite Member

# Via API
curl -X POST https://api.axiomdb.squareexp.com/api/v1/organizations/<org-id>/invitations \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"email": "teammate@example.com", "role": "developer"}'

Invitations are sent via email, stay valid for 7 days, and can be revoked at any time by owners or admins. As soon as your teammate accepts, their account is linked up and they'll be added to the organization.

Who can do what? (Role Matrix)

To help keep permissions organized, here's a breakdown of what each role in your organization can access:

Step 3 — Install the CLI

The easiest way to work with AxiomDB is through our command-line tool, the axm CLI. Under the hood, it's a fast Rust binary that we distribute through npm so it works seamlessly on any operating system.

Let's get it installed:

npm install -g axiomdb-cli

Once that's done, let's verify that it installed correctly by checking the help menu:

axm -h

Note: The CLI is exposed as axm, but if you're used to typing the longer axiom binary, that still works too for backward compatibility.

How the CLI communicates (Architecture)

The CLI talks directly to the AxiomDB Gateway at api.axiomdb.squareexp.com using secure HTTPS connections. It saves your login session tokens locally inside ~/.axiomdb/ and lets you configure multiple profiles so you can switch between environments easily.

┌──────────────┐     HTTPS      ┌───────────────────┐     Redis      ┌──────────────┐
│   axm CLI    │ ──────────────▶ │  AxiomDB Gateway  │ ──────────────▶│ square-dbctl │
│  (terminal)  │ ◀────────────── │  (Axum + PASETO)  │ ◀──────────────│  (provisioner)│
└──────────────┘    responses    └───────────────────┘    commands    └──────────────┘
       │                               │
       │ local session                 │ control-plane DB
       ▼                               ▼
  ~/.axiomdb/                    PostgreSQL metadata

Step 4 — Spin up your first project

Next, let's create a project. Think of a project as the container for all your database branches, network policies, backups, and settings. Remember, you don't connect directly to a project itself—instead, you'll connect to the individual branches inside it!

Run the following command to get started:

axm projects create --name "Square Experience" --app-key square_experience --env main

Here's what those options mean:

What happens behind the scenes

When you create a project, our gateway goes to work setting up a few things for you automatically:

1. Metadata Setup — We add a new project entry to our database and set its status to active.
2. Main Branch Creation — We automatically set up a protected main branch that is designed to stay active permanently (forever).
3. Database Spin-up — We tell square-dbctl to run CREATE DATABASE sq_<app_key>_<env> to create your actual PostgreSQL database.
4. Role Configuration — We create three specific PostgreSQL database roles for security:
   • <app_key>_<env>_owner — Used for running database migrations (equipped with CREATEDB privileges).
   • <app_key>_<env>_rw — Your main role for general read and write access during runtime.
   • <app_key>_<env>_ro — A read-only role perfect for running analytics queries safely.
5. Secure Credentials — We generate strong, secure passwords and save them in an encrypted secrets file (~/.creds/zone.env).
6. PgBouncer Setup — We register your runtime role with the PgBouncer connection pooler user list.
7. Network Safety — We set your initial network policy to a secure, restricted mode with no allowed IP ranges.
8. Logging — We write project.created and branch.created events to your audit log for traceability.

What the project response looks like

Once the setup completes, you'll get a detailed JSON response back like this:

{
  "project": {
    "id": "proj_a1b2c3d4",
    "name": "Square Experience",
    "app_key": "square_experience",
    "env": "main",
    "status": "active"
  },
  "main_branch": {
    "id": "br_e5f6g7h8",
    "branch_name": "main",
    "database_name": "sq_square_experience_main",
    "lifespan": "forever",
    "protected": true,
    "status": "active"
  }
}

Step 5 — Set your active project

To save you from typing the project ID with every single command, you can set an active project for your current session:

axm projects list
axm projects use <project-id>

Once your active project is set, you can run much simpler commands, like these:

axm branches list
axm branches urls --name main

Step 6 — Allow your device to connect

Because we prioritize security, AxiomDB starts off in a secure, restricted network mode. Your computer or server won't be able to connect to PostgreSQL until you explicitly allow its IP address.

Letting the CLI auto-detect your IP

The absolute fastest way to allow your current machine is with this CLI command:

axm network allow --current

This command automatically grabs the public IP address you're connecting from and adds a /32 CIDR rule for your active project.

Adding your IP in the Web Console

If you'd rather do it in the browser, just follow these simple steps:

1. Click on the Network tab in the console menu.
2. Click the My IP button—the console will auto-detect and show your current public IP.
3. Take a quick look at the JSON payload.
4. Click Save JSON—this instantly updates the firewall rules in PostgreSQL, PgBouncer, and UFW.
5. Now, go ahead and try connecting or running your database migration again!

Let's look at the network payload structure

Here is how a network rule looks under the hood:

{
  "policy": {
    "apply": false,
    "mode": "restricted"
  },
  "rules": [
    {
      "cidr": "203.0.113.10/32",
      "expires_in": "7d",
      "label": "My current IP",
      "ports": "both",
      "scope": "project"
    }
  ]
}

Here's what each field does:

How we apply network rules under the hood

When you save a network rule, AxiomDB performs a few steps to keep your configuration clean and secure:

1. First, we validate the CIDR format and check if there are any conflicting rules.
2. We write the rule to our network_rules table.
3. We generate new configuration blocks for PostgreSQL (pg_hba.conf), PgBouncer, and your firewall (UFW).
4. We run square-dbctl to apply the updates using special configuration markers, ensuring we don't mess with any of your server's other system settings.
5. Finally, we write a network.rule.created event to the audit logs, keeping track of who added the rule, their IP, and the browser they used.

Step 7 — Get your branch connection URLs

Now that your IP is allowlisted, you're ready to connect! Run this command to get the connection strings for your branch:

axm branches urls --name main

This will give you two connection URLs that you can paste directly into your .env file:

DATABASE_URL="postgresql://square_experience_rw:***@db.squareexp.com:6432/sq_square_experience_main?sslmode=require"
DIRECT_URL="postgresql://square_experience_owner:***@db.squareexp.com:5432/sq_square_experience_main?sslmode=require"

Using the Connect Modal

In the browser console, you can also click the Connect button on any branch. This opens a modal containing:

• Pre-formatted .env configurations tailored for popular tools like Prisma, Drizzle, Kysely, node-postgres, SQLAlchemy, Django, Laravel, Go pgx, and Rust SQLx.
• Easy copy buttons for each connection string.
• Quick setup steps specific to your chosen framework.
• A friendly security reminder about keeping your passwords safe.

Step 8 — Run your first database migration

With your .env file set up, you're ready to run your first database migration! Let's kick it off with Prisma:

npx prisma migrate dev --name init

How does this work? Prisma uses the pooled DATABASE_URL (running on port 6432 via PgBouncer) to query your database while your app is running, and uses the direct DIRECT_URL (running on port 5432) when applying schema updates, managing locks, or creating temporary shadow databases.

Step 9 — Take a tour of the dashboard

Head back to the web console and check out your project dashboard! Here's a quick look at the features you can play around with:

• Branches — Keep track of all active, expired, and protected database branches, complete with their current status, storage usage, and active connections.
• Tables — Take a look at your live schema, browse through table rows, and view your database structure visually using our Schema Flow tool.
• Network — Add or update your IP allowlists, see what access mode you're using, and look over network changes.
• Backups — Create manual snapshots, view backup health, or restore a backup straight into a brand new branch.
• Monitoring — Watch real-time metrics showing database storage size, active connections, query load, and migration statuses.
• Audit — Keep your security team happy by reviewing logs for every sensitive action, complete with timestamps, IP addresses, and user info.
• Settings — Set up automatic branch cleanups, manage allowed CORS origins, configure Data API tokens, or update team permissions.

Step 10 — Create your first database branch

One of AxiomDB's coolest features is branching! This lets you test out database schema changes in complete isolation without ever touching your production data. Let's create one:

axm branches create --name feature-auth --source main --lifespan 7d

When you run this, AxiomDB spins up a brand new, isolated database for you (sq_square_experience_main_br_feature-auth), generates unique credentials, and replicates your main schema onto it. Your new branch gets its own database connection URLs, its own network allowlists, and its own set of audit logs.

What to read next

Troubleshooting common issues

If you hit a snag, here are some quick ways to fix the most common issues:

Getting a "Connection refused" or "timeout" error?

• Why it's happening: Your computer's IP address hasn't been added to the project's network allowlist.
• How to fix it: Simply run axm network allow --current in your terminal, or head to the Network page in the web console to add it manually.

Getting an "Authentication failed" error when connecting to Postgres?

• Why it's happening: Your credentials might have been rotated, or you might be using an old, expired URL.
• How to fix it: Fetch a fresh set of connection strings by running axm branches urls --name <branch-name> and update your .env file.

Seeing a "Branch limit exceeded" error?

• Why it's happening: You've hit the limit of 10 active branches for your project.
• How to fix it: Clean up some space by deleting an unused branch with axm branches delete <branch-name>, or drop us a line if you need a limit increase!

CLI is telling you "No active project selected"?

• Why it's happening: The CLI doesn't know which project you want to work on yet.
• How to fix it: List your projects using axm projects list, and then select one with axm projects use <project-id>.