Use this skill for persistent PostgreSQL storage in agent workflows — spin up databases on demand, test schema migrations safely on forks, and pass databases as assets between agents using Ghost. **Trigger when user asks to:** - Create a new PostgreSQL database quickly - Manage
Installs just this skill. Get the whole plugin for auto-invocation.
⚡ How it fires
How this skill gets triggered: by you, by Claude, or both.
Fires itselfClaude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/ghost-database
👁️ Context preview
The summary Claude sees to decide when to auto-load this skill.
Use this skill for persistent PostgreSQL storage in agent workflows — spin up databases on demand, test schema migrations safely on forks, and pass databases as assets between agents using Ghost. **Trigger when user asks to:** - Create a new PostgreSQL database quickly - Manage
📊 Stats
Stars1,793
Forks99
LanguagePython
LicenseApache-2.0
📦 Ships with pg-aiguide
</> SKILL.md
ghost-database.SKILL.md
---name: ghost-database
description: |
Use this skill for persistent PostgreSQL storage in agent workflows — spin up databases on demand, test schema migrations safely on forks, and pass databases as assets between agents using Ghost.
**Trigger when user asks to:**
- Create a new PostgreSQL database quickly
- Manage database lifecycle in agent workflows
- Fork a database to test changes safely
- Run analytics or heavy queries on a fork without impacting the production database
- Share a database snapshot so others can spin up their own copy
- Pass a database as an input or output between agents
- Create a database for agents
- Need many databases that are billed only when queried
- Set up the Ghost MCP server or CLI
**Note:** If the Ghost MCP server is already installed, use its tools directly — this skill is for environments without the MCP or as a reference for what's possible.
**Keywords:** Ghost, ghost.build, database, create database, fork database, PostgreSQL, managed Postgres, MCP, agent database, connection string
license: Apache-2.0
metadata:
author: tigerdata
---# Ghost Database Management
Ghost is a managed PostgreSQL service designed for agents. Your account is organized into Spaces, each with unlimited on-demand databases and forks sharing a pool of compute hours (billed in 15-minute chunks when queries are executed). Free tier: 100 hours/month, 1TB storage.
When you need continuous operation, promote any database to a **dedicated instance** — a separately billed, always-on database.
Additional features:
- **CLI and MCP native:** create and query databases from the terminal or any MCP-compatible agent
- **Instant forking:** full database copies in seconds for safe experimentation
- **Shareable snapshots:** share a database snapshot via URL — anyone with the link can spin up their own copy in their own space
- **MCP read-only mode:** `ghost config set read_only true` locks all MCP tools into read-only — SQL queries execute in read-only mode and destructive tools (`ghost_delete`, `ghost_password`, `ghost_rename`) are blocked
Website: https://ghost.build
## Installation
Multiple installation methods are provided. If you aren't sure, use the first one.
ghost_connect({ name_or_id: "abc123" }) // Get connection string
```
## Core Workflows
### Create and Query a Database
**CLI**
```bash
# Create a database (returns an ID like abc123)
ghost create my-app-db
# Run SQL directly
ghost sql abc123 "CREATE TABLE users (id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY, email TEXT NOT NULL UNIQUE, created_at TIMESTAMPTZ NOT NULL DEFAULT now())"
# Query it
ghost sql abc123 "SELECT * FROM users"
# Open interactive psql session
ghost psql abc123
```
**MCP**
```
ghost_create({ name: "my-app-db" })
// → returns { id: "abc123", ... }
ghost_sql({ name_or_id: "abc123", query: "CREATE TABLE users (id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY, email TEXT NOT NULL UNIQUE, created_at TIMESTAMPTZ NOT NULL DEFAULT now())" })
ghost_sql({ name_or_id: "abc123", query: "SELECT * FROM users" })
```
### Fork for Safe Experimentation
Forking creates a full copy of your database in seconds — same schema, same data. Use forks to test migrations, experiment with schema changes, or let agents explore without risk to your working database. You can fork a dedicated instance into an on-demand instance — useful for testing against a production copy without paying for always-on compute.
For a complete migration testing workflow using forks — including pre/post validation queries and rollback planning — see the `postgres-database-migration` skill.
**CLI**
```bash
# Fork a database (returns the fork's ID, e.g. def456)
ghost fork abc123 my-app-db-experiment
# Test changes on the fork
ghost sql my-app-db-experiment "ALTER TABLE users ADD COLUMN role TEXT NOT NULL DEFAULT 'user'"
# If it worked: apply to original
ghost sql abc123 "ALTER TABLE users ADD COLUMN role TEXT NOT NULL DEFAULT 'user'"
# If it failed: delete the fork, original is untouched
ghost_sql({ name_or_id: "def456", query: "ALTER TABLE users ADD COLUMN role TEXT NOT NULL DEFAULT 'user'" })
// If it worked: apply to original
ghost_sql({ name_or_id: "abc123", query: "ALTER TABLE users ADD COLUMN role TEXT NOT NULL DEFAULT 'user'" })
// If it failed: delete the fork, original is untouched
ghost_delete({ name_or_id: "def456" })
```
### Auto-Pause and Resume
Databases automatically pause after 30 days of idle time to conserve compute hours. Storage is retained. Resume a paused database when you need it again:
**CLI**
```bash
ghost resume abc123 --wait
```
**MCP**
```
ghost_resume({ name_or_id: "abc123" })
```
### Inspect Schema
**CLI**
```bash
ghost schema abc123
```
**MCP**
```
ghost_schema({ name_or_id: "abc123" })
```
Returns an LLM-optimized schema representation of all tables, columns, indexes, and constraints.
### Share a Database
Sharing creates a snapshot anyone can use to spin up their own copy — no access to your space required. Useful for sharing sample datasets, bug reproductions, or starter databases.
Agents can also use shares as a way to pass databases as assets: an agent can produce a database as output by sharing it (handing the recipient a URL to spin up their own copy), or accept a share token as input to start from a pre-populated database.
**CLI**
```bash
# Share a database (returns a share URL)
ghost share abc123
# Share with an expiry
ghost share abc123 --expires 24h
# Recipient creates their own database from the share token
// Recipient creates their own database from the share token
ghost_create({ from_share: "<token>" })
// Manage shares
ghost_share_list()
ghost_share_revoke({ share_token: "<token>" })
```
## CLI Command Reference
For a full list of commands and flags, run:
```bash
ghost --help
ghost <command> --help # e.g. ghost create --help
```
## MCP Integration
The Ghost MCP server gives agents full database lifecycle control — create, fork, query, inspect, resume, and delete databases without human intervention.
### Install the MCP Server
```bash
ghost mcp install
```
Supports: Claude Code, Cursor, Windsurf, Codex, Gemini, VS Code, Kiro.
### MCP Read-Only Mode
To give agents safe read-only access, enable read-only mode before starting the MCP server:
```bash
ghost config set read_only true
```
This locks all MCP tools into read-only: `ghost_sql` executes queries in read-only mode, and destructive tools (`ghost_delete`, `ghost_password`, `ghost_rename`) are blocked entirely.
## When to Use Ghost
**Good fit:**
- Persistent Postgres storage for agent workflows
- Giving each agent or even agentic execution a dedicated database
- Creating and discarding databases freely without cost anxiety
- Database forking for safe experimentation and migration testing
- Hard spending caps with predictable billing (compute hours in 15-minute chunks)
**Not the right fit:**
- You need a web dashboard (Ghost is CLI/MCP only)
