Ghost Database

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)

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

Install Script (Windows PowerShell)

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

Debian/Ubuntu

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

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

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

# 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

# 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

ghost resume abc123 --wait

MCP

ghost_resume({ name_or_id: "abc123" })

Inspect Schema

CLI

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

# 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 

# Manage shares
ghost share list abc123
ghost share revoke 

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

// Manage shares
ghost_share_list()
ghost_share_revoke({ share_token: "" })

CLI Command Reference

For a full list of commands and flags, run:

ghost --help
ghost  --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

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:

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: timescale
• Source: timescale/pg-aiguide
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.