Skip to content
Discord Get Started

DB9 with Claude Code

The DB9 skill for Claude Code teaches the agent how to use the db9 CLI and SQL to create databases, run queries, manage files, create branches, and schedule jobs — all from natural language prompts.

What the Integration Provides

Section titled “What the Integration Provides”

Once the DB9 skill is installed, Claude Code can:

  • Create and manage databases (db9 create, db9 list, db9 delete)
  • Run SQL queries (db9 db sql)
  • Upload and query files via the filesystem (db9 fs)
  • Create database branches for safe experimentation (db9 branch)
  • Schedule recurring SQL jobs (db9 db cron)
  • Use built-in extensions: vector search, embeddings, HTTP from SQL, full-text search
  • Manage authentication and tokens

The skill file is a Markdown document installed to Claude Code’s skills/ directory. Claude Code automatically reads files from ~/.claude/skills/ (user scope) and ./.claude/skills/ (project scope) as context. The DB9 skill includes CLI syntax, SQL patterns, extension usage, and security guidelines. It also instructs Claude Code to periodically re-read the latest version from https://db9.ai/skill.md.

Prerequisites

Section titled “Prerequisites”
  • Claude Code installed and working
  • The db9 CLI installed:
Terminal
curl -fsSL https://db9.ai/install | sh

You do not need to be logged in to DB9 before onboarding. The skill installation does not send any tokens or credentials.

Install the DB9 Skill

Section titled “Install the DB9 Skill”

The recommended way to install the skill is via db9 onboard:

Terminal
# Interactive — auto-detects Claude Code if installed
db9 onboard


# Non-interactive, Claude Code only
db9 onboard --yes --agent claude


# Install for both user and project scope
db9 onboard --yes --agent claude --scope both

Scope options

Section titled “Scope options”
ScopeInstall locationWhen to use
--scope user (default)~/.claude/skills/db9/SKILL.mdSkill available in all projects
--scope project./.claude/skills/db9/SKILL.mdSkill scoped to this project only
--scope bothBoth locationsRecommended for active DB9 projects

Safety checks

Section titled “Safety checks”

Before making any changes, you can preview what db9 onboard will do:

Terminal
# Show where files would be written (zero changes)
db9 onboard --dry-run --agent claude


# Show resolved target paths
db9 onboard --print-locations --agent claude

The onboard command:

  • Never sends tokens or credentials anywhere
  • Backs up existing skill files before overwriting
  • Skips installation if the local version is already newer (use --force to override)
  • Uses atomic file writes to avoid partial installs

Verify the Installation

Section titled “Verify the Installation”

After installing, verify Claude Code can see the skill:

Terminal
# Check the skill file exists
cat ~/.claude/skills/db9/SKILL.md | head -5

Expected output:

Output
---
name: db9
version: 1.0.0
description: Serverless Postgres for AI agents...
---

Then start Claude Code and try a prompt:

Create a DB9 database called "test-app" and show me the connection string.

Claude Code should run db9 create --name test-app --show-secrets and return the connection details.

Example Prompts

Section titled “Example Prompts”

Once the skill is active, try these prompts with Claude Code:

Database management

Section titled “Database management”
Create a DB9 database for my project and set it as the default.
List all my DB9 databases and show which one is the default.

Schema and queries

Section titled “Schema and queries”
Create a users table with id, email, name, and created_at columns in my DB9 database.
Then insert three sample users and query them back.
Show me the schema of all tables in my DB9 database.

Vector search and embeddings

Section titled “Vector search and embeddings”
Create a documents table with a text column and vector embeddings.
Insert some sample documents and run a semantic similarity search.

File operations

Section titled “File operations”
Upload the README.md file to my DB9 database filesystem,
then query its contents using SQL.

Branching

Section titled “Branching”
Create a branch of my database called "experiment",
add a new column to the users table on the branch,
then delete the branch.

Scheduled jobs

Section titled “Scheduled jobs”
Set up a pg_cron job that runs VACUUM on my database every night at 3am.

Update the Skill

Section titled “Update the Skill”

The skill file is versioned. To update to the latest version:

Terminal
db9 onboard --yes --agent claude

If your local version is newer than the remote (e.g., you customized it), the update is skipped. Use --force to overwrite:

Terminal
db9 onboard --yes --agent claude --force

You can also point to a custom skill source:

Terminal
# From a URL
db9 onboard --agent claude --skill-url https://example.com/custom-skill.md


# From a local file
db9 onboard --agent claude --skill-path ./my-custom-skill.md

Current Limitations

Section titled “Current Limitations”
  • No direct database connection from Claude Code — Claude Code uses the db9 CLI to interact with databases, not a direct pgwire connection. All operations go through CLI commands or the REST API.
  • CLI must be authenticated — Before Claude Code can create or manage databases, you need to have run db9 login or db9 create (which auto-registers an anonymous account) at least once.
  • Anonymous account limits — Anonymous accounts are limited to 5 active databases. Run db9 claim to upgrade to a verified account and remove this limit.
  • Skill is read-only context — The skill file provides instructions to Claude Code but does not execute anything. All actual operations run through the db9 CLI with your normal permissions.

Next Pages

Section titled “Next Pages”