Skip to content
Discord Get Started

Anonymous and Claimed Databases

DB9 lets you start without signing up. The first time you run db9 create without credentials, the CLI auto-registers an anonymous account, gives you a bearer token, and creates your database. When you are ready, run db9 claim to link an SSO identity and remove the trial limits.

This page explains the full lifecycle: how anonymous accounts work, what limits apply, how claiming works, and what happens to your databases.

Decision Summary

Section titled “Decision Summary”
AnonymousClaimed
Database limit5Unlimited
Auth methodBearer token (auto-refreshed)SSO (Auth0) or API key
Token lifetime90 days (auto-refresh)90 days (re-login to renew)
FeaturesFull access to all featuresFull access to all features
Upgrade pathdb9 claimAlready upgraded

Key point: anonymous accounts have full feature access — SQL, extensions, branching, cron, tokens, and SDK access all work. The only restriction is the 5-database limit.

How Anonymous Accounts Work

Section titled “How Anonymous Accounts Work”

Automatic registration

Section titled “Automatic registration”

When you run db9 create without credentials (no DB9_API_KEY environment variable and no stored token), the CLI:

  1. Calls the anonymous registration endpoint
  2. Receives a bearer token (90-day TTL) and an anonymous secret
  3. Stores both in ~/.db9/credentials (file permissions: owner-only, 0600)
  4. Creates your database

No email, password, or browser interaction required.

Credential storage

Section titled “Credential storage”

The CLI stores credentials locally:

Output
~/.db9/credentials

This file contains the bearer token, customer ID, anonymous ID, and anonymous secret. It is created with owner-only read/write permissions.

Automatic token refresh

Section titled “Automatic token refresh”

When your bearer token expires (after 90 days), the CLI automatically refreshes it using your anonymous secret. This happens transparently on the next command — you do not need to re-register or re-create anything.

The refresh endpoint issues a new 90-day token each time, so as long as you use the CLI at least once every 90 days, your session persists indefinitely.

Limits

Section titled “Limits”

Anonymous accounts are limited to 5 databases (branches count toward this limit). Attempting to create a sixth database returns an error:

Output
Anonymous account database limit reached (max 5). Run 'db9 claim' to upgrade your account.

All other features are unrestricted:

  • SQL execution, transactions, and all data types
  • All 9 extensions (http, fs9, embedding, vector, pg_cron, etc.)
  • Database branching (branches count toward the 5-database limit)
  • Cron jobs, connect tokens, and user management
  • TypeScript SDK access
  • CLI output formats (--output json, --output csv)

Claiming Your Account

Section titled “Claiming Your Account”

Claiming links your anonymous account to a verified SSO identity (Auth0), removes the database limit, and preserves all existing databases.

Interactive claim

Section titled “Interactive claim”
Terminal
db9 claim

This opens a browser for Auth0 authentication. After you sign in, the account is claimed.

Non-interactive claim (CI/CD)

Section titled “Non-interactive claim (CI/CD)”
Terminal
db9 claim --id-token <AUTH0_JWT>

Use this when you already have an Auth0 ID token (e.g., from a prior authentication flow).

Auto-claim on login

Section titled “Auto-claim on login”

If you have an anonymous account and run db9 login, the CLI automatically detects the anonymous credentials and claims the account before completing login. No separate db9 claim step needed.

Terminal
db9 login  # Detects anonymous account → auto-claims → completes SSO login

What Happens When You Claim

Section titled “What Happens When You Claim”

The claim operation is atomic. In a single update:

  1. Email is set to your verified SSO email
  2. Database limit is removed (set to unlimited)
  3. Anonymous secret is deleted (no longer needed)
  4. SSO identity is linked (issuer + subject ID)
  5. Anonymous flag is cleared

Your databases stay

Section titled “Your databases stay”

All databases created under the anonymous account remain owned by the same customer ID. Nothing is deleted, migrated, or interrupted. Your connection strings and credentials continue to work.

Credentials change

Section titled “Credentials change”

After claiming, the anonymous refresh mechanism is disabled (the secret is deleted). To get new tokens:

  • Run db9 login for interactive SSO authentication
  • Use db9 login --api-key <KEY> with a pre-created API token for automation

Token continuity

Section titled “Token continuity”

Your existing bearer token continues to work until it expires (90 days from last refresh). After expiry, use db9 login to get a new SSO-based token.

Edge Cases

Section titled “Edge Cases”

SSO identity already linked

Section titled “SSO identity already linked”

If the SSO identity you authenticate with is already linked to a different DB9 account, the claim fails with an error. You cannot merge two separate accounts.

Email conflict

Section titled “Email conflict”

If another account already uses the same email address, the claim fails. Each email can be associated with only one DB9 account.

No anonymous account to claim

Section titled “No anonymous account to claim”

Running db9 claim without an existing anonymous account (e.g., after db9 logout) returns an error. You must have anonymous credentials stored locally.

Check your current state

Section titled “Check your current state”

Run db9 status to see whether you are anonymous, claimed, or logged out.

Lost credentials

Section titled “Lost credentials”

If you delete ~/.db9/credentials before claiming, the anonymous account still exists on the server but you cannot access it. There is currently no recovery mechanism for lost anonymous credentials.

Authentication for Automation

Section titled “Authentication for Automation”

For CI/CD or headless environments where browser-based SSO is not practical:

  1. First run: Let db9 create auto-register an anonymous account
  2. Claim later: Run db9 claim --id-token <JWT> with a pre-obtained token
  3. Ongoing: Use db9 login --api-key <KEY> with a named API token

Or skip anonymous entirely:

Terminal
# Create an API token from a claimed account, then use it in CI
export DB9_API_KEY="your-api-token"
db9 create --name ci-test-db

Account Lifecycle Summary

Section titled “Account Lifecycle Summary”
Output
┌─────────────────────────────────────────────────┐
│  No credentials                                 │
│  └─ db9 create ─→ anonymous-register            │
│                    ├─ bearer token (90 days)     │
│                    ├─ anonymous secret            │
│                    └─ database limit: 5          │
├─────────────────────────────────────────────────┤
│  Anonymous account                              │
│  ├─ All features available                      │
│  ├─ Auto-refresh on token expiry                │
│  └─ db9 claim ─→ SSO verification               │
│                  ├─ email set                    │
│                  ├─ limit removed                │
│                  └─ secret deleted               │
├─────────────────────────────────────────────────┤
│  Claimed account                                │
│  ├─ Unlimited databases                         │
│  ├─ SSO login (db9 login)                       │
│  ├─ API key auth (db9 login --api-key)          │
│  └─ All existing databases preserved            │
└─────────────────────────────────────────────────┘

Next Pages

Section titled “Next Pages”