Skip to content
Discord Get Started

DB9 with OpenAI Codex

The DB9 skill for OpenAI Codex 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, Codex 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 Codex’s skills/ directory. It includes CLI syntax, SQL patterns, extension usage, and security guidelines.

Prerequisites

Section titled “Prerequisites”
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 Codex if installed
db9 onboard


# Non-interactive, Codex only
db9 onboard --yes --agent codex


# Install for all detected agents at once
db9 onboard --yes --all

Scope

Section titled “Scope”

Codex currently supports user scope only. The skill is installed to:

~/.codex/skills/db9/SKILL.md

If the CODEX_HOME environment variable is set, the skill installs to $CODEX_HOME/skills/db9/SKILL.md instead.

Note: --scope project is not supported for Codex. If you pass --scope project --agent codex, the CLI will return an error. When using --all --scope project, Codex is automatically skipped with a warning.

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 codex


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

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 the skill file exists:

Terminal
cat ~/.codex/skills/db9/SKILL.md | head -5

Expected output:

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

Then start Codex and try a prompt:

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

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

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 delete any that start with "test-".

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.

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.

Update the Skill

Section titled “Update the Skill”

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

Terminal
db9 onboard --yes --agent codex

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 codex --force

Current Limitations

Section titled “Current Limitations”
  • User scope only — Codex does not currently support project-scoped skills. The skill is always installed to ~/.codex/skills/db9/SKILL.md (or $CODEX_HOME).
  • No direct database connection — Codex uses the db9 CLI, not a direct pgwire connection. All operations go through CLI commands or the REST API.
  • CLI must be authenticated — Before Codex 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 Codex but does not execute anything. All actual operations run through the db9 CLI with your normal permissions.

Next Pages

Section titled “Next Pages”