terrabase-v2

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

Register it with any MCP client (command: node apps/mcp-server/dist/index.js).

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.

License

Licensed under the Apache License 2.0. © 2026 Terrabase.in.