Quick Start

Quick Start

Get a REST API, MCP tools, and an OpenAPI spec from your database in under 5 minutes.

Prerequisites

• A stable Rust toolchain (edition 2024) — or use Nix
• A running PostgreSQL instance (or use SQLite for zero-dependency testing)

Option A: PostgreSQL

# Build the CLI
cargo build --release --bin pgvis

# Point it at your database
export PGVIS_DSN="postgres://user:password@localhost/mydb"
./target/release/pgvis serve

pgvis introspects all tables, views, and functions in the public schema and starts serving on http://localhost:3000.

Option B: SQLite (No Server Required)

# Use any existing SQLite database
export PGVIS_DSN="sqlite:./mydata.db"
./target/release/pgvis serve

pgvis auto-detects SQLite from the DSN and uses the main schema.

First Requests

List rows

curl "http://localhost:3000/api/public/users"

Response:

[
  {"id": 1, "name": "Alice", "email": "alice@example.com"},
  {"id": 2, "name": "Bob", "email": "bob@example.com"}
]

Select specific columns

curl "http://localhost:3000/api/public/users?select=id,name"

Filter rows

# Exact match
curl "http://localhost:3000/api/public/users?name=eq.Alice"

# Numeric comparison
curl "http://localhost:3000/api/public/items?price=gte.100"

# Pattern matching
curl "http://localhost:3000/api/public/items?name=ilike.*widget*"

Order and paginate

# Order by price descending, take first 10
curl "http://localhost:3000/api/public/items?order=price.desc&limit=10"

# Cursor-based pagination (efficient for large datasets)
curl "http://localhost:3000/api/public/items?order=id.asc&cursor_column=id&cursor_value=42&limit=10"

Embed related resources

# Get orders with their items (via foreign key)
curl "http://localhost:3000/api/public/orders?select=id,total,items(*)"

Create a row

curl -X POST "http://localhost:3000/api/public/items" \
  -H "Content-Type: application/json" \
  -H "Prefer: return=representation" \
  -d '{"name": "Widget", "price": 9.99}'

Call a function

curl -X POST "http://localhost:3000/api/public/rpc/add" \
  -H "Content-Type: application/json" \
  -d '{"a": 2, "b": 3}'

MCP for AI Agents

Claude Desktop (stdio transport)

Add to your Claude Desktop MCP configuration (~/.config/claude/mcp.json):

{
  "mcpServers": {
    "mydb": {
      "command": "./target/release/pgvis",
      "args": ["--dsn", "postgres://user@localhost/mydb", "mcp"]
    }
  }
}

Claude can now query your database using natural language — pgvis generates typed tools for every table and function.

Read-only mode (safer for LLMs)

{
  "mcpServers": {
    "mydb": {
      "command": "./target/release/pgvis",
      "args": ["--dsn", "postgres://user@localhost/mydb", "mcp", "--read-only"]
    }
  }
}

HTTP transport (alongside REST)

pgvis --dsn "postgres://user@localhost/mydb" serve --mcp-http
# MCP available at POST /mcp

OpenAPI Document

# Print the OpenAPI 3.0 spec to stdout
pgvis --dsn "postgres://user@localhost/mydb" openapi > openapi.json

Inspect Schema Cache

# Dump the introspected schema as JSON (tables, columns, relationships, routines)
pgvis --dsn "postgres://user@localhost/mydb" inspect

Nix Users

# Development shell with all dependencies
nix develop

# Or build the binary directly
nix build
./result/bin/pgvis serve --dsn "postgres://user@localhost/mydb"

Next Steps

• Installation — Docker, Nix, cargo install
• REST API Guide — full query DSL with all 30+ operators
• MCP Guide — tool generation, resources, transport options
• Configuration — environment variables, TOML config, CLI flags