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)

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

Related MCP server: postgres-mcp-query-tool

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.