---

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.

Metric	Raw SQL Dump	Schemap AI Context	Difference
Token Footprint	Full raw schema estimate	Compiled context	Measured per schema
Relationship Mapping	Implicit / Scattered	Explicit FK Graph	Instant JOIN Clarity
AI Readiness Score	Unmeasured	Diagnosed (e.g. 78/100)	Actionable Fix Roadmap
Agent Rule Files	None	CLAUDE.md & AGENTS.md	Native Agent Integration

---

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

Command	Purpose	JSON Output Flag
schemap doctor	Onboarding health check & diagnostic	schemap doctor --json
schemap context	Compile database_context.md context map	schemap context --format=json
schemap agents	Generate CLAUDE.md and AGENTS.md	N/A
schemap benchmark	Measure raw SQL vs Schemap token savings & latency	schemap benchmark --json
schemap score	Analyze AI Readiness Score (0-100) & issue roadmap	schemap score --json
schemap inspect	Inspect raw database table & column metadata	schemap inspect --json
schemap diff	Track structural schema changes (+, ~, -)	N/A

---

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