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. 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). To get a full connection string with credentials:

db9 create --name myapp --show-connection-string

Or generate a short-lived connect token:

db9 db connect-token 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://..."
console.log(db.adminUser);         // "admin"

instantDatabase() is idempotent — if a database named myapp already exists, it returns the existing one without re-running the seed SQL.

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
conn = psycopg2.connect(db["connection_string"])
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://..."

# 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

Use the returned connectionString with any PostgreSQL client library:

TypeScript
Python

import pg from 'pg';

const pool = new pg.Pool({ connectionString: db.connectionString });
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"])
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"

Anonymous account database limit reached — 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 — DB9 requires TLS. Make sure your client supports sslmode=require or equivalent. See Connect for details.

SDK authentication — The SDK auto-registers anonymously on first use, similar to the CLI. Credentials are stored locally and reused across runs.

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