Skip to main content
Glama
Terrabase-in

terrabase

Official
by Terrabase-in
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

terrabase-v2

CI 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.

Related MCP server: pg-sentinel

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.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityStale
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers

  • psql-mcp

    maxswjeon
    A
    license
    Not graded
    quality
    A
    maintenance
    A hardened, read-only Postgres MCP server that enables LLMs to safely query databases without write, DDL, shell, or credential exposure.
    MIT

  • pg-sentinel

    anshujod
    A
    license
    Not graded
    quality
    B
    maintenance
    A PostgreSQL MCP server with three independent safety layers that allows LLMs to explore and query databases safely via read-only SELECT operations, with full audit logging and query plan intelligence.
    MIT

  • mcp-postgres-guard

    vladshykanov
    F
    license
    A
    quality
    B
    maintenance
    An MCP server that enables AI agents to securely interact with PostgreSQL databases with least-privilege scopes, PII masking, and human approval for writes.
    4
    -

  • moat-mcp

    vinnyang
    F
    license
    A
    quality
    B
    maintenance
    A security-hardened Postgres MCP server that enables LLM agents to run safe, read-only SQL queries with enforcement via SQL-AST inspection and read-only transactions.
    1
    -