Quick Start

Pick the path that matches how you work: the CLI for terminal-first workflows, the TypeScript SDK for programmatic access, or the agent onboarding flow to give an AI coding agent its own database.

Path 1: CLI

Install

curl -fsSL https://db9.ai/install | sh

The installer downloads the db9 binary for your platform (macOS or Linux, x64 or arm64) and places it in /usr/local/bin by default.

To install elsewhere:

DB9_INSTALL_DIR="$HOME/.local/bin" curl -fsSL https://db9.ai/install | sh

Verify:

db9 --version

If you plan to use db9 fs mount on macOS, install macFUSE first:

brew install --cask macfuse

On Apple Silicon/macOS, you may also need to approve the macFUSE system extension in System Settings > Privacy & Security before mounts succeed.

Create a database

No signup needed — the CLI auto-registers an anonymous account on first use.

db9 create --name myapp

You’ll see the database ID, name, and state, plus a Connection String: line that includes the admin password. Save it now — it is shown only once. The database is ready to use immediately.

Run SQL

Use the built-in SQL interface to run queries:

# One-shot query
db9 db sql myapp -q "CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT)"
db9 db sql myapp -q "INSERT INTO users (name) VALUES ('alice'), ('bob')"
db9 db sql myapp -q "SELECT * FROM users"

Or open an interactive REPL:

db9 db sql myapp

The REPL supports multi-line SQL, tab completion, and \-backslash commands similar to psql.

Get connection info

To connect from any PostgreSQL client (psql, an ORM, or a driver):

db9 db connect myapp

This prints a temporary token-based connection string (valid for up to 10 minutes). For a long-lived connection string, use the one db9 create printed on its Connection String: line (db9 db status myapp shows it without the password). If you no longer have it, set a new admin password and print a new connection string:

db9 db reset-password myapp

Verify it works

# Check account status
db9 status

# List your databases
db9 list

# Run a round-trip test
db9 db sql myapp -q "SELECT 'hello from db9' AS greeting"

Expected output:

 greeting
─────────────────
 hello from db9

Path 2: TypeScript SDK

Install

npm install get-db9

Create a database and run SQL

import { instantDatabase } from 'get-db9';

const db = await instantDatabase({
  name: 'myapp',
  seed: `
    CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT);
    INSERT INTO users (name) VALUES ('alice'), ('bob');
  `,
});

console.log(db.databaseId);        // "t1a2b3c4d5e6"
console.log(db.connectionString);  // "postgresql://t1a2b3c4d5e6.admin@pg.d0000.db9.io:5432/postgres" (no password)
console.log(db.adminUser);         // "admin" is the role; the full username is "t1a2b3c4d5e6.admin"

instantDatabase() is idempotent — if a database named myapp already exists, it returns the existing one without re-running the seed SQL. That reuse call returns connectionString, adminUser and adminPassword as empty strings; Connect from your application shows how to connect either way.

import requests
import psycopg2
import os

headers = {"Authorization": f"Bearer {os.environ['DB9_API_KEY']}"}

# Create database
resp = requests.post(
    "https://api.db9.ai/customer/databases",
    json={"name": "myapp"},
    headers=headers,
)
db = resp.json()

# Run seed SQL. connection_string has no password; add admin_password (from this
# create response, or GET /customer/databases/{id}/credentials later).
conn = psycopg2.connect(db["connection_string"], password=db["admin_password"], sslmode="require")
conn.autocommit = True
cur = conn.cursor()
cur.execute("CREATE TABLE IF NOT EXISTS users (id SERIAL PRIMARY KEY, name TEXT)")
cur.execute("INSERT INTO users (name) VALUES ('alice'), ('bob')")
cur.close()
conn.close()

print(db["id"])                # "t1a2b3c4d5e6"
print(db["connection_string"]) # "postgresql://t1a2b3c4d5e6.admin@pg.d0000.db9.io:5432/postgres"

# Create database
curl -X POST https://api.db9.ai/customer/databases \
  -H "Authorization: Bearer $DB9_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "myapp"}'

# Run SQL (use the database_id from the response above)
curl -X POST "https://api.db9.ai/customer/databases/$DATABASE_ID/sql" \
  -H "Authorization: Bearer $DB9_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT)"}'

curl -X POST "https://api.db9.ai/customer/databases/$DATABASE_ID/sql" \
  -H "Authorization: Bearer $DB9_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "INSERT INTO users (name) VALUES ('"'"'alice'"'"'), ('"'"'bob'"'"')"}'

Connect from your application

The returned connection string carries no password, but it already contains the full PostgreSQL username (<tenant_id>.admin). The first component is the tenant ID DB9 uses for routing. The adminUser property shown above is only the role name (admin); for a direct PostgreSQL connection, use the username from the connection string, not admin by itself or the database name. The SDK’s adminPassword is set only on the call that created the database, so fetch the stored credentials with credentials(), which works on every run:

TypeScript
Python

import { createDb9Client } from 'get-db9';
import pg from 'pg';

const creds = await createDb9Client().databases.credentials(db.databaseId);
const url = new URL(creds.connection_string); // postgresql://<id>.admin@pg.d0000.db9.io:5432/postgres
url.password = creds.admin_password;
url.searchParams.set('sslmode', 'verify-full'); // node-postgres uses TLS only when asked

const pool = new pg.Pool({ connectionString: url.toString() });
const result = await pool.query('SELECT * FROM users');
console.log(result.rows);
// [{ id: 1, name: 'alice' }, { id: 2, name: 'bob' }]

import psycopg2

conn = psycopg2.connect(db["connection_string"], password=db["admin_password"], sslmode="require")
cur = conn.cursor()
cur.execute("SELECT * FROM users")
print(cur.fetchall())
# [(1, 'alice'), (2, 'bob')]
cur.close()
conn.close()

Path 3: Agent onboarding

Give an AI coding agent (Claude Code, Codex, OpenCode) access to DB9 with a single command:

# Install DB9 skills for Claude Code
db9 onboard --agent claude

# Or for all supported agents
db9 onboard --all

# Preview what will be installed without making changes
db9 onboard --agent claude --dry-run

The onboard command installs a DB9 skill file that teaches the agent how to create databases, run SQL, manage files, and use branching — all through the DB9 CLI.

Supported agents: claude, codex, opencode, agents.

Scope options:

Flag	Effect
`--scope user`	Install for all projects (default)
`--scope project`	Install for the current project only
`--scope both`	Install at both levels

Troubleshooting

db9: command not found — The binary isn’t on your PATH. Either move it or add the install directory:

export PATH="$HOME/.local/bin:$PATH"

Database limit reached (max 5) — Anonymous accounts can create up to 5 databases. Run db9 claim to upgrade your account via SSO and remove the limit.

Connection refused or timeouts — check the host and port first: use the ones in your connection string (pg.d0000.db9.io:5432; pg.db9.io on port 5433 or 5432 reaches the same server). A refusal from localhost or 127.0.0.1 means your client never received the connection string. TLS is not the likely cause: libpq’s default sslmode=prefer already negotiates TLSv1.3 against DB9. Set sslmode=require explicitly anyway — the server enforces no minimum, so an sslmode=disable inherited from a config file or platform default would connect in plaintext without warning. See Connect for details.

SDK authentication — The SDK does not register an account itself: it reads the token the CLI stores in ~/.db9/credentials. Run a CLI command such as db9 create (which registers an anonymous account on first use) or db9 login first; without a token the SDK throws No token available. Run `db9 login` or pass a token via Db9ClientOptions.

Next steps

Serverless Functions — deploy JavaScript/TypeScript with native SQL access
Connect — connection strings, psql, ORMs, drivers, and TLS options
Why DB9 for AI Agents — built-in embeddings, file system, HTTP, branching
Agent Workflows — the full agent lifecycle with DB9
CLI Reference — complete command reference
TypeScript SDK — server-side SDK API and types
Browser SDK — client-side data access with RLS
Extensions — fs9, HTTP, pg_cron, vector search, and more
Architecture — how DB9 works under the hood