terrabase-v2

License: Apache 2.0 Node PRs Welcome

LLM-assisted, safety-gated Postgres migrations, exposed as an MCP server.

A local LLM may draft migration SQL, but a deterministic rule engine over Postgres's own parser AST is the sole safety authority. Every write goes through a two-phase, approval-gated flow and lands in an append-only audit ledger.

The LLM proposes, the rules decide.

Layout (pnpm monorepo)

Package	Purpose
`packages/core`	shared types, zod schemas, errors, config, DSN redaction
`packages/pg-ast`	`libpg_query` (WASM) parse + traversal + typed node guards
`packages/pg-safety`	the 30-rule deterministic safety analyzer (the heart)
`packages/pg-introspect`	live schema → compact JSON model
`packages/pg-advisor`	`EXPLAIN (FORMAT JSON)` parsing + HypoPG index advice
`packages/pg-migrate`	append-only audit ledger + transactional, approval-gated apply
`packages/llm`	Ollama structured output + retry-on-zod-error
`apps/mcp-server`	the 5 MCP tools + two-phase orchestration

Full design: docs/specs/2026-07-07-terrabase-v2-design.md.

Quick start

pnpm install
pnpm build          # tsup builds every package
pnpm typecheck      # tsc --noEmit, strict
pnpm test           # vitest unit tests (run everywhere)

Configure via env (see .env.example): TERRABASE_DATABASE_URL, OLLAMA_HOST, OLLAMA_MODEL, TERRABASE_PG_VERSION.

Run the MCP server

pnpm mcp            # speaks MCP over stdio

Graceful degradation

The parser + rule engine run with no external services. If Ollama is down, pass sql directly to propose_migration. If there's no database, SQL is still parsed and analyzed offline against TERRABASE_PG_VERSION. Docker-backed integration tests skip automatically when Docker is unavailable.

MCP tools

inspect_schema — compact schema model (read-only)
propose_migration — intent→LLM-drafted SQL or raw sql → analyze → returns a SafetyReport + proposalId (applies nothing)
apply_migration — proposalId + approvalToken → gated, transactional apply → ledger
explain_query — parsed plan tree + flagged problems
advise_index — HypoPG-simulated index recommendations (Tier-1 catalog fallback)

Desktop app (Strata)

An Electron GUI over the same engine lives in apps/desktop. It runs the parser + rule engine locally, auto-discovers project databases, and renders the SafetyReport visually.

pnpm --filter @terrabase-v2/desktop dev

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for setup, the PR checklist, and the one non-negotiable rule (the LLM is advisory only). All participants are expected to follow our Code of Conduct.

Security

Found a vulnerability? Please report it privately — see SECURITY.md. Do not open a public issue for security reports.

terrabase