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

Terminal

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:

Terminal

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

Verify:

Terminal

db9 --version

Create a database

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

Terminal

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:

Terminal

# 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:

Terminal

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):

Terminal

db9 db connect myapp

This prints the passwordless connection string. To get a full connection string with credentials:

Terminal

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

Or generate a short-lived connect token:

Terminal

db9 db connect-token myapp

Verify it works

Terminal

# 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:

Output

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

Path 2: TypeScript SDK

Install

Terminal

npm install get-db9

Create a database and run SQL

TypeScript

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.

Connect from your application

Use the returned connectionString with any PostgreSQL client library:

TypeScript

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' }]

Path 3: Agent onboarding

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

Terminal

# 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:

Terminal

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

• 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 — full SDK API and types
• Extensions — fs9, HTTP, pg_cron, vector search, and more
• Architecture — how DB9 works under the hood