ghost-database - Claude MCP Skill

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

### Install Script (macOS/Linux/WSL)

```bash
curl -fsSL https://install.ghost.build | sh
```

### Install Script (Windows PowerShell)

```powershell
irm https://install.ghost.build/install.ps1 | iex
```

### Debian/Ubuntu

```bash
curl -s https://packagecloud.io/install/repositories/timescale/ghost/script.deb.sh | sudo os=any dist=any bash
sudo apt-get install ghost
```

### Red Hat/Fedora

```bash
curl -s https://packagecloud.io/install/repositories/timescale/ghost/script.rpm.sh | sudo os=rpm_any dist=rpm_any bash
sudo yum install ghost
```

## Getting Started

**CLI**
```bash
ghost login                     # Authenticate with GitHub
ghost create                    # Create a new database (returns an ID, e.g. abc123)
ghost list                      # List all databases with their IDs
ghost connect <name-or-id>              # Get connection string
```

**MCP**
```
ghost_login()                   // Authenticate with GitHub
ghost_create({ name: "my-db" }) // → returns { id: "abc123", ... }
ghost_list()                    // List all databases with their IDs
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 delete my-app-db-experiment --confirm
```

**MCP**
```
ghost_fork({ name_or_id: "abc123", name: "my-app-db-experiment" })
// → returns { id: "def456", ... }

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
ghost create --from-share <token>

# Manage shares
ghost share list abc123
ghost share revoke <token>
```

**MCP**
```
ghost_share({ name_or_id: "abc123" })
// → returns { share_token: "...", url: "..." }

ghost_share({ name_or_id: "abc123", expires: "24h" })

// 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)
- You need non-Postgres databases