Why Schemap?

Modern AI coding agents (Claude Code, Cursor, GitHub Copilot, Codex) struggle with complex production databases.

Raw pg_dump SQL dumps waste 10,000+ tokens, introduce noisy system metadata, cause broken multi-table JOINs, and force LLMs to guess business relationships.

Schemap solves this. Schemap is a deterministic CLI compiler that extracts database schemas, computes AI Readiness Scores, and generates compressed, token-optimized context maps (schemap_database_context.md, CLAUDE.md, AGENTS.md).

• Token-optimized context: Run schemap benchmark against your own schema to measure the raw-vs-compiled token footprint.
• Local-first & deterministic: Schema extraction and compilation run locally by default. Optional --enrich uses the configured OpenAI API, and licensed CI/CD usage performs an online license check.
• Sub-2ms Compilation: Compiles 200+ table database schemas in under 3 milliseconds.
• Multi-Database Support: PostgreSQL, MySQL, Turso / libSQL, SQLite, and Oracle.

Benchmark: Raw SQL vs. Schemap Context

Compression varies by schema. Run schemap benchmark to measure the token footprint, relationship coverage, AI Readiness Score, and generation latency for your own database.

Installation & Quick Start

Install Schemap globally as a developer CLI via pipx (recommended) or uv / pip:

pipx install schemap-tool

Alternative package managers:

• uv: uv tool install schemap-tool
• pip: pip install schemap-tool

1. Verify Installation

schemap --version
# Schemap 2.2.0

2. Upgrading Schemap

To upgrade an existing installation to the latest release:

pipx upgrade schemap-tool

(Or uv tool upgrade schemap-tool / pip install --upgrade schemap-tool)

3. Initialize Configuration

Generate a lightweight schemap.yaml config file with predefined domain mappings:

schemap init

Example schemap.yaml with domain mappings:

database:
  connection_url: "sqlite:///test.db"

output:
  file_path: "./schemap_database_context.md"

domain:
  mappings:
    cust: "Customer"
    tx: "Transaction"
    inv: "Invoice"
    acct: "Account"

For full boilerplate options (schema descriptions, table exclusions):

schemap init --full

4. Run Database Health Diagnostic (schemap doctor)

Diagnose database readiness and identify missing foreign keys, undocumented tables, or ambiguous column names:

schemap doctor

Output:

==================================================
 Schemap AI Database Health Check
==================================================
  Connection:            Connected (39 tables)
  Relationships Analyzed: 26
--------------------------------------------------
  AI Readiness Score:
  [###########---------] 53/100

  Top Issues Identified:
  - [Priority 1 - Missing Documentation] 39 tables lack descriptions/comments (-20 pts)
  - [Priority 2 - Disconnected Entities] 20 tables have no foreign keys (-7 pts)
  - [Priority 3 - Ambiguous Naming] 44 unresolved abbreviations detected (-20 pts)
--------------------------------------------------
 Recommendation: Run `schemap context` to generate AI-ready database context.
==================================================

5. Compile AI Database Context (schemap context)

Compile schemap_database_context.md containing relationship maps, central tables, and standard SQL JOIN snippets:

schemap context

4. Generate Agent Instruction Files (schemap agents)

Generate CLAUDE.md and AGENTS.md rules for your workspace:

schemap agents

5. Benchmark Context Efficiency (schemap benchmark)

Measure real-time token compression and compilation speed:

schemap benchmark

Complete CLI Reference

Supported Databases

• PostgreSQL (postgresql://user:password@localhost:5432/my_db)
• Turso / Remote libSQL (libsql://...)
• Local SQLite (sqlite:///path/to/db.sqlite3)
• MySQL (mysql://user:password@localhost:3306/my_db)
• Oracle (oracle://user:password@localhost:1521/my_db)

CI/CD Integration & Licensing

Automate context map updates on every migration commit with GitHub Actions:

• Free Tier: Full local CLI for databases up to 100 tables, including inspection, scoring, context, diffs, benchmarks, and exports.
• Pro Tier: Unlimited tables, CI/CD GitHub Actions integration, and production workflow support.

License management

Activate a purchased license globally with the schemap activate command. Use schemap status --verify to check it against the license service, and schemap logout to remove global credentials. The CLI resolves command-line, environment, global, and legacy project configuration credentials in that order. CI/CD should provide SCHEMAP_LICENSE_KEY through the repository secret store.

Key Terms & Keywords (SEO)

database context for AI agents • Claude Code database schema • Cursor rules database context • SQL token reduction • database schema to markdown • MCP database server • LangChain database tool • text-to-SQL prompt optimization • AI database schema generator