DEV Community: Sualeh Fatehi

SchemaCrawler Has Three Programmatic Models - Here Is When to Use Each One

Sualeh Fatehi — Sun, 06 Sep 2026 20:42:01 +0000

Your database already contains one of the most valuable maps of your application: its schema. The problem is that this map is usually trapped behind JDBC metadata calls, vendor-specific system tables, and a sprawling tangle of hundreds of objects.

SchemaCrawler is an open-source database schema discovery and documentation tool. Connect it to almost any JDBC-accessible database and it turns raw metadata into searchable documentation, database diagrams, lint reports, machine-readable output, and a rich Java API. It is designed for the moments when you inherit an undocumented database, need to understand the blast radius of a change, or want to make schema knowledge available to developers and AI agents without relying on tribal knowledge.

The command line is a fast way to explore and document a schema. The Java API is where SchemaCrawler becomes a building block: you can create a custom report, power an internal developer portal, enforce design rules in CI, or teach an agent how your data fits together.

You connect to a database and call SchemaCrawler. What do you get back?

Not one enormous, do-everything object. SchemaCrawler gives you three increasingly expressive models:

Catalog for physical database metadata.
ERModel for inferred entity-relationship meaning.
ImportanceModel for dependency topology, table importance, and domain clustering.

Think of them as three lenses over the same database. Start with facts. Add data-model semantics when you need them. Reach for graph analysis when you need to understand what is central, connected, or naturally grouped.

1. `Catalog`: the facts-on-the-ground model

Catalog is SchemaCrawler's foundational model. It is the in-memory result of crawling database metadata through JDBC, and it represents the physical objects your database actually exposes.

It gives you schemas, tables, views, columns, indexes, primary keys, foreign keys, routines, sequences, synonyms, users, data types, and database/driver information. Every other model in this article starts here.

import schemacrawler.schema.Catalog;
import schemacrawler.schemacrawler.SchemaCrawlerOptions;
import schemacrawler.tools.utility.SchemaCrawlerUtility;
import us.fatehi.utility.datasource.DatabaseConnectionSource;

DatabaseConnectionSource connectionSource = /* configure JDBC connection */;
SchemaCrawlerOptions options = SchemaCrawlerOptions.builder().toOptions();

Catalog catalog = SchemaCrawlerUtility.getCatalog(connectionSource, options);

catalog.getTables().forEach(table -> {
  System.out.printf("%s: %d columns%n",
      table.getFullName(),
      table.getColumns().size());
});

The API is deliberately direct. Need a table by schema and unqualified name? Use lookupTable. Need all tables in a schema? Use getTables(schema). Need routines, sequences, or synonyms? The Catalog has those too.

Use `Catalog` when...

You are documenting or inspecting the literal database structure.
You need DDL-oriented facts: columns, nullability, indexes, constraints, triggers, comments, and privileges.
You are writing a schema linter, migration check, documentation generator, or custom report.
You want to decide what is present before making a higher-level interpretation.

Catalog is the right answer for questions such as:

Which tables have no primary key?

Which views reference this table?

Does ORDERS have an index beginning with CUSTOMER_ID?

It is intentionally not an opinionated business model. A table is a table, even if it looks suspiciously like a join table or a subtype. That restraint is a feature: physical metadata remains the trustworthy base layer.

2. `ERModel`: turn tables and keys into a data model

Physical metadata tells you that BOOK_AUTHORS has two foreign keys. It does not, by itself, tell you that the table is probably expressing a many-to-many relationship between BOOKS and AUTHORS.

That is the job of ERModel.

Build it from the catalog:

import schemacrawler.ermodel.model.ERModel;
import schemacrawler.tools.utility.SchemaCrawlerUtility;

ERModel erModel = SchemaCrawlerUtility.buildERModel(catalog);

erModel.getEntities().forEach(entity ->
    System.out.println(entity.getFullName()));

erModel.getRelationships().forEach(relationship ->
    System.out.println(relationship.getFullName()));

SchemaCrawler infers entities and relationships from the schema metadata already present in the Catalog. That includes foreign keys, primary keys, unique indexes, and table shape. The result distinguishes meaningful model concepts such as:

Strong entities and weak entities.
Subtypes and their supertypes.
One-to-one, one-to-many, and many-to-many relationships.
Bridge tables, represented as many-to-many relationships rather than ordinary entities.
Implicit relationships inferred from catalog metadata.
Tables and references that could not be modeled.

This is an important distinction: a bridge table is not merely "a table with two foreign keys." SchemaCrawler's inference uses the surrounding metadata to determine whether the pattern actually represents a many-to-many relationship. That is why application code should reuse ERModel instead of recreating a quick-but-fragile join-table heuristic.

ERModel also gives you focused lookups:

erModel.lookupEntity("PUBLIC.BOOKS.BOOKS")
    .ifPresent(entity -> System.out.println(entity.getEntityType()));

erModel.lookupRelationship("PUBLIC.BOOKS.BOOKAUTHORS")
    .ifPresent(relationship -> System.out.println(relationship.getCardinality()));

Relationship names are meaningful identifiers. Depending on the relationship, a name can correspond to a bridge table, a foreign key, or an implicit relationship. Use the model's lookup methods rather than inventing identifiers from table names.

Use `ERModel` when...

You need to explain the schema as a domain model, not just list its objects.
You are drawing ER diagrams or exposing relationship-aware tooling.
You need entity classification, cardinality, supertypes, or bridge-table reasoning.
You are helping an AI agent or a developer understand the meaning behind foreign keys.

Use it for questions such as:

Is this table a strong entity, a subtype, or a bridge table?

What relationship does this foreign key represent?

Which tables are not accounted for by the inferred data model?

One practical rule: do not use ERModel as a replacement for Catalog. It is a semantic interpretation of the catalog, not a second source of database facts. Keep the Catalog nearby when you need to inspect the actual columns, keys, or index definitions that support an inference.

3. `ImportanceModel`: find what matters and what belongs together

An ER model answers, "What does this relationship mean?" An importance model answers a different class of question:

What should I understand first, what could this change affect, and which parts of this schema form a coherent domain?

SchemaCrawler's importance module builds an immutable ImportanceModel from a Catalog:

import schemacrawler.importance.model.ImportanceModel;
import schemacrawler.importance.model.TableImportance;
import schemacrawler.importance.model.implementation.ImportanceModelBuilder;

ImportanceModel importanceModel = ImportanceModelBuilder.builder(catalog).build();

catalog.getTables().stream()
    .map(table -> new Object[] {
        table,
        table.<TableImportance>getAttribute(TableImportance.class.getName())
    })
    .sorted((left, right) ->
        ((TableImportance) left[1]).compareTo((TableImportance) right[1]))
    .forEach(entry -> {
      var table = (schemacrawler.schema.Table) entry[0];
      var importance = (TableImportance) entry[1];
      System.out.printf("%3d %s%n",
          importance.importanceScore(),
          table.getFullName());
    });

Behind that small API is a proper directed dependency graph, implemented with JGraphT. Vertices represent tables, views, routines, and synonyms. Typed edges represent:

Foreign keys.
Implied associations.
View dependencies.
Routine dependencies.
Synonym resolution.

The catalog graph is exposed read-only through getCatalogGraph(), while lookupByVertexId() maps graph vertices back to their SchemaCrawler objects. That makes the graph useful both for built-in analysis and for your own JGraphT algorithms.

Importance is more than "most foreign keys wins"

When the importance model is built, SchemaCrawler calculates topology metrics for every vertex:

In-degree and out-degree.
Betweenness centrality.
Dependency reachability: what the object transitively depends on.
Impact reachability: what can be reached when dependency edges are traversed backward.

For tables and views, it combines those signals with physical and ER-derived traits into a reproducible, catalog-relative score from 0 to 100. Structural signals contribute 50% of the score; entity role, attribute columns, row count, foreign key count, trigger count, and self-reference contribute the other 50%.

That blend avoids a classic graph-analysis trap. A bridge table can have high betweenness simply because it sits between two entities. The importance calculation knows that a bridge table is structurally useful without mistaking it for the business entity at the center of your system.

The computed TableImportance is stored as an attribute on each table, so you can reuse it without rebuilding your own scorecard.

Clusters reveal domains hiding in plain sight

SchemaCrawler also detects table clusters: groups of related tables and views that often correspond to a functional area of the application.

importanceModel.getTableClusters().forEach(tableCluster -> {
  System.out.printf("Anchor: %s%n", tableCluster.anchorVertexId());
  tableCluster.memberVertexIds().forEach(System.out::println);
});

The clustering process intentionally ignores dependency direction for this purpose. A customer table and an order table are closely related whether the foreign-key arrow points from orders to customers or the other way around. SchemaCrawler takes the table/view subgraph, treats it as undirected for affinity, and runs deterministic label-propagation clustering.

Only clusters with at least three members are reported. Within each one, members are ordered by importance, and the highest-ranked member becomes its anchor. The result is stable enough to use in reports, onboarding material, or an AI-assisted schema exploration workflow.

Use `ImportanceModel` when...

You inherited a large, undocumented database and need a sensible starting point.
You need blast-radius analysis before changing a table, view, or routine.
You want to identify central tables without over-rewarding thin bridge tables.
You want to group a sprawling schema into likely business domains.
You want to apply custom JGraphT traversals or graph algorithms to schema dependencies.

This is the model for questions such as:

What are the five most important tables to learn first?

What depends on this table, directly or transitively?

Which tables belong to the same likely functional area?

Pick the smallest lens that answers the question

Here is the cheat sheet:

If you need to...	Start with...
Inspect columns, indexes, keys, routines, or database metadata	`Catalog`
Explain entity roles, cardinality, subtypes, or many-to-many relationships	`ERModel`
Rank central objects, analyze impact, find paths, or identify domains	`ImportanceModel`

The models are complementary, not competing. The most effective workflow is usually:

Catalog -> ERModel -> ImportanceModel
 facts     meaning    topology and priorities

Start with the catalog to establish what is real. Build the ER model when the shape of the schema needs interpretation. Build the importance model when the question becomes "where do I start?" or "what is connected to what?"

That progression turns raw JDBC metadata into something much more useful: a map of the database, a model of its relationships, and a guide to the parts that deserve your attention first.

For a deeper dive into scores, metrics, and the importance command, see Rank Your Database Tables by Importance with SchemaCrawler.

Rank Your Database Tables by Importance with SchemaCrawler

Sualeh Fatehi — Sun, 06 Sep 2026 20:22:22 +0000

You've just been handed a database with 400 tables and no documentation. Where do you even start?

Most people start guessing. Maybe the table with the most rows? Maybe the one with the longest name, because surely someone spent a lot of time on it? Maybe just alphabetical order, because at least it's deterministic? None of these actually tell you which tables matter.

SchemaCrawler has a better answer: build a graph of your schema's dependencies, run some graph theory on it, blend in a bit of data-modeling common sense, and hand you a single ranked list. That's the importance command, and this article walks through why it exists, how the score is computed, and how you can plug it into an AI agent so it can explore your schema the same way an experienced engineer would.

Why importance, not just size

Row count and column count are cheap proxies for "this table matters," but they're misleading. A CUSTOMERS table with a thousand rows and a dozen well-designed foreign keys pointing at it is probably far more important to your application's logic than a million-row EVENT_LOG table nobody queries directly. Size measures volume. It doesn't measure how central a table is to the way the rest of the schema depends on it.

What you actually want to know is: if I had to explain this schema to a new teammate, or if I had to change this table and needed to know what else might break, which tables would I need to understand first?

That's a graph problem, not a row-counting problem.

Graph theory made accessible

SchemaCrawler builds a directed graph over your entire catalog: tables, views, routines, and synonyms are nodes, and foreign keys, view dependencies, routine table access, and synonym resolution become edges. Once that graph exists, some classic graph metrics fall out of it for free, computed once for every table and view:

In-degree and out-degree — how many things point at this table, and how many things this table points at.
Betweenness centrality — computed on an undirected view of the graph, this measures how often a table sits on the shortest path between two other tables. High betweenness means a table is a structural bridge — remove it, and other parts of the schema become harder to reach from each other.
Dependency reachability count — how many other objects this table transitively depends on.
Impact reachability count — how many other objects would be reachable (and therefore potentially affected) if you changed this table, by walking dependency edges backward into it.

If you've ever used a graph library like JGraphT to analyze a social network or a road network, this will feel familiar — a database schema is just another kind of graph, and the same centrality and reachability concepts apply directly.

Why centrality alone isn't enough — bridge tables versus real entities

Here's the catch: betweenness centrality, on its own, tends to reward bridge tables — the thin many-to-many association tables (think BOOK_AUTHORS linking BOOKS to AUTHORS) that sit between two other entities purely to connect them. A bridge table can have very high betweenness centrality simply because it's structurally in the middle of a lot of shortest paths, even though it might only have two or three foreign key columns and carry no meaningful business data of its own.

Meanwhile, a rich strong entity table like BOOKS — with real attribute columns, a solid primary key, indexes, and a well-understood business meaning — might have lower betweenness centrality just because it's not sitting between other tables in the graph.

If you rank purely by centrality, bridge tables can out-rank the tables that actually carry your business data. That's backwards from what most people mean when they ask "which tables are important."

SchemaCrawler fixes this by computing a composite importance score — an integer from 0 to 100 — that blends structural graph signals with data-modeling signals:

Structural Half

betweenness centrality — graph‑based influence measure
impact reachability — propagation potential across dependencies
total degree — combined in‑ and out‑degree

Data‑Modeling Half (50%)

entity role — conceptual importance in schema
attribute column count — structural richness
row count — data volume
foreign key count — relational connectivity
trigger count — behavioral complexity
self‑referencing — recursive relationships

The entity role term draws on SchemaCrawler's entity-relationship classification (strong entity, weak entity, subtype, non-entity) plus one graph-specific addition, bridge_table, and weights them so that strong and weak entities rank above bridge tables within that term:

entity type	score
strong_entity	1.00
weak_entity	0.85
subtype	0.70
bridge_table	0.55
non_entity	0.30
unknown	0.10

Two dampeners then shave points off tables with design smells — no primary key (-15%) or no indexes at all (-10%) — because a table that's missing these fundamentals is less trustworthy as a "load-bearing" part of your schema, no matter how central it looks structurally.

The result: a genuinely central, richly-attributed entity table scores highest. A well-connected bridge table can still score respectably (structural signals are half the formula, after all), but it no longer beats out the entities it's connecting purely by an accident of graph position.

Try it yourself

docker run \
  --mount type=bind,source="$(pwd)",target=/home/schcrwlr/share \
  --rm -it \
  schemacrawler/schemacrawler \
  /opt/schemacrawler/bin/schemacrawler.sh \
  --server=sqlite \
  --database=sc.db \
  --info-level=standard \
  --command=importance \
  --output-format=text \
  --output-file=share/importance.txt

Add --table-filter='.*\.BOOKS.*' with a regular expression to narrow the report to matching tables and views. Output is available as text, json, or yaml, sorted by importance score (descending), with betweenness centrality as a tie-breaker. Communities are calculated once when SchemaCrawler builds the schema graph, then reused in the report.

Here is an excerpt of what the output looks like in JSON format:

{
  "clusters" : [ {
    "id" : "a61b0ea7-c688-3e35-ab3b-b7593f7fd788",
    "anchor_table_full_name" : "PUBLIC.BOOKS.BOOKS",
    "total_cluster_size" : 4,
    "member_table_full_names" : [ "PUBLIC.BOOKS.BOOKS", "PUBLIC.\"PUBLISHER SALES\".SALES", "PUBLIC.\"PUBLISHER SALES\".REGIONS", "PUBLIC.\"PUBLISHER SALES\".SALESDATA" ]
  } ],
  "tables" : [ {
    "table_full_name" : "PUBLIC.BOOKS.BOOKS",
    "table_importance" : {
      "importance_score" : 73,
      "table_traits" : {
        "self_referencing" : true,
        "entity_model_type" : "strong_entity"
      },
      "table_counts" : {
        "attribute_column_count" : 5,
        "column_count" : 7,
        "foreign_key_count" : 1,
        "index_count" : 3,
        "trigger_count" : 0
      },
      "importance_metrics" : {
        "in_degree" : 3,
        "out_degree" : 1,
        "betweenness_centrality" : 6.0,
        "dependency_reachability_count" : 0,
        "impact_reachability_count" : 2
      }
    }
  } ]
}

Letting an AI agent use this directly

This is where it gets genuinely useful for AI-assisted workflows. The SchemaCrawler AI MCP Server exposes these same metrics as tools an AI agent can call directly, without you having to explain your schema by hand:

table_importance — returns graph importance metrics for tables and views, including dependency centrality, table counts, and traits. Accepts an optional regular expression filter (table_name) and an optional maximum table count (max_tables, defaulting to 5; pass 0 or a negative integer to return all tables).
table_path — finds the shortest forward dependency path from one table or view to another, preferring foreign-key relationships and falling back to implied associations only when no formal foreign key exists.

Put these together, and an AI agent connected to your database through the MCP server can answer questions like "what are the five most important tables in this schema, and why?" or "what's the shortest dependency path from ORDERS to SHIPPING_ADDRESSES?" — grounded in actual graph analysis of your schema, not a guess based on table names. That turns a cold, undocumented database into something an AI coding assistant can reason about the same way a human engineer familiar with the system would.

Where to go next

If you want the full formula, the complete weight tables, and sample JSON output, see the graph metrics and importance page on the SchemaCrawler website. If you want to see this in action against your own database, all you need is the importance command and a JDBC connection — no separate setup required.

Understand SchemaCrawler's programmatic models. See SchemaCrawler Has Three Programmatic Models - Here Is When to Use Each One

Migrate from SchemaSpy to SchemaCrawler Without Rewriting Your Runbooks

Sualeh Fatehi — Wed, 26 Aug 2026 23:10:12 +0000

If you already use SchemaSpy to document a database, moving to SchemaCrawler does not have to mean replacing every script at once.

The latest SchemaCrawler release includes a SchemaSpy-compatible shim. It accepts common SchemaSpy command-line arguments, connects to the database, and runs SchemaCrawler Scribe to produce documentation in Google Open Knowledge Format (OKF).

That gives you a gradual migration path: keep the command-line shape your team knows, while changing the output from a generated website bundle to a set of Markdown files that can live in Git.

Start with the SchemaSpy command you already have

The shim is called schemaspy and is included in the SchemaCrawler Docker image and the other SchemaCrawler installers.

For example, a SchemaSpy command for a SQLite database might look like this:

schemaspy \
  -t sqlite \
  -db ./sc.db \
  -u sa \
  -p "" \
  -o ./schema-output.zip

With SchemaCrawler installed, the same command produces an OKF bundle. The adapter translates the SchemaSpy options and invokes SchemaCrawler Scribe behind the scenes.

You can use the Docker image without installing Java locally:

docker run --rm -it \
  --mount type=bind,source="$(pwd)",target=/home/schcrwlr/share \
  schemacrawler/schemacrawler \
  schemaspy \
  -t sqlite \
  -db /home/schcrwlr/sc.db \
  -u sa \
  -p "" \
  -o share/schema.zip

On Windows PowerShell, use a backtick instead of a backslash for line continuation. The Docker mount makes the database and generated ZIP available in your current directory.

To see the database types supported by the adapter, run:

schemaspy -dbhelp

In Docker:

docker run --rm -it schemacrawler/schemacrawler schemaspy -dbhelp

The shim is intended to make migration practical, not to promise that every SchemaSpy-specific option has an identical meaning. Supported options are translated, compatibility options may be accepted as no-ops, and unsupported options report an explicit error. Check the adapter documentation when converting a more specialized command.

What Google OKF changes

SchemaSpy's usual output is a browser-oriented HTML report. That is useful when someone wants to click through a schema, but HTML is not always convenient as a source artifact. It is difficult to review meaningfully in a pull request, search with ordinary text tools, or give to another tool without first scraping the pages.

Google OKF uses Markdown files with YAML frontmatter and links between related documents. A generated bundle contains files such as:

index.md
tables/
  authors.md
  books.md
cross-references/
  index.md

The exact tree depends on the database, but the important property is that the documentation is ordinary text. Developers can open it in Visual Studio Code, review it in GitHub, and diff one schema snapshot against another.

The pages can include:

tables, columns, keys, constraints, triggers, and references
routines such as functions and stored procedures
cross-reference pages for relationships
Mermaid diagrams embedded in Markdown
optional lint reports for schema design issues

The YAML frontmatter also makes each document easier for static-site generators and indexing tools to understand. For an AI agent, the result is a collection of small, named, linked documents instead of one opaque report. For a developer, it is still just Markdown.

Run Scribe directly when you are ready

Once the compatibility shim is working, you can switch to SchemaCrawler's native command line. This makes the output options explicit and gives you access to SchemaCrawler features such as linting and row counts.

Here is a Docker example that writes an expanded OKF directory instead of a ZIP file:

docker run \
  --mount type=bind,source="$(pwd)",target=/home/schcrwlr/share \
  --rm -it \
  schemacrawler/schemacrawler \
  /opt/schemacrawler/bin/schemacrawler.sh \
  --server=sqlite \
  --database=/home/schcrwlr/sc.db \
  --info-level=maximum \
  --command scribe \
  --output-format okf \
  --title "Books Database" \
  --expanded-output \
  --include-lint \
  --load-row-counts \
  --output-file=share/schema.zip

The compatibility command is a good first step. The native command is a good long-term choice for a new automation job.

Check the documentation into GitHub

An OKF directory is a natural build artifact for a documentation repository. A simple repository layout might be:

.
├── .github/workflows/schema-docs.yml
├── schema/
│   ├── index.md
│   ├── tables/
│   └── cross-references/
└── README.md

You can generate the files on a schedule or whenever your schema migrations are merged. Commit the generated Markdown to a branch, or publish it as the Pages source from a dedicated documentation repository.

Checking in generated output has a useful side effect: schema changes become visible in ordinary pull requests. A changed column, new foreign key, or removed table appears as a text diff. The database remains the source of truth, while Git records how its documented shape changed over time.

Do not commit database passwords or connection strings containing secrets. Store credentials in GitHub Actions secrets and pass them to the container as environment variables or workflow inputs.

Publish the OKF bundle with GitHub Pages

GitHub Pages can publish Markdown content using Jekyll. Because OKF pages include YAML frontmatter, the generated directory can be used as the source for a Pages site. A minimal workflow can generate the documentation and deploy it:

name: Publish schema documentation

on:
  workflow_dispatch:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Generate OKF documentation
        run: |
          mkdir -p public
          docker run --rm \
            --mount type=bind,source="$PWD",target=/home/schcrwlr/share \
            schemacrawler/schemacrawler \
            /opt/schemacrawler/bin/schemacrawler.sh \
            --server=sqlite \
            --database=/home/schcrwlr/share/sc.db \
            --info-level=maximum \
            --command scribe \
            --output-format okf \
            --title "Books Database" \
            --expanded-output \
            --include-lint \
            --output-file=/home/schcrwlr/share/public

      - name: Configure Pages
        uses: actions/configure-pages@v5

      - name: Build with Jekyll
        uses: actions/jekyll-build-pages@v1
        with:
          source: public
          destination: _site

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: _site

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

For a database that is not a file in the repository, replace the SQLite connection with your database server and provide the connection values through GitHub Actions secrets. You may also choose to commit the generated schema directory and use a separate Pages workflow that publishes that checked-in directory.

After enabling GitHub Pages for the repository, the workflow publishes index.md as the entry point and keeps the links to table and cross-reference pages intact. The result is a browsable schema reference at the same URL your team can use in tickets, pull requests, and onboarding notes.

A practical migration sequence

You do not need to change everything in one pull request:

Replace the SchemaSpy executable with the SchemaCrawler schemaspy shim.
Confirm that your database connection and filtering options produce the expected OKF bundle.
Add the generated Markdown to a Git repository and review the first schema diff.
Publish the directory with GitHub Pages if a hosted reference site is useful.
Move mature scripts to the native scribe command and add options such as --include-lint.

SchemaSpy and SchemaCrawler both work with relational database metadata over JDBC, so the database connection remains familiar. The main change is what you do with the result: instead of treating documentation as a report to regenerate and distribute, you can treat it as structured source material that belongs in your repository.

Learn more

SchemaCrawler Scribe + Google OKF: AI-Ready Database Docs You Can Keep in Git

Sualeh Fatehi — Tue, 14 Jul 2026 23:58:09 +0000

If your database documentation is always behind production, this is for you.

SchemaCrawler Scribe generates structured database documentation directly from live schema metadata, using Google Open Knowledge Format (OKF).

The result is documentation that works for both developers and AI agents, without creating a second documentation workflow.

Source code: SchemaCrawler/schemacrawler-scribe

The Problem SchemaCrawler Scribe Solves

Most teams end up in one of two modes:

Manual docs that drift from reality
Generated docs that are hard to read, hard to diff, or hard to reuse

SchemaCrawler Scribe targets the middle ground:

readable Markdown that developers can review
structured content that AI systems can parse
plain text artifacts that belong in version control

This turns documentation into part of your engineering workflow, not a side task.

What You Get With SchemaCrawler Scribe

AI-agent-friendly database documentation
Documentation generated directly from schema metadata
Localized output (German, French, and more)
Mermaid diagrams embedded in Markdown
Artifacts that are both human-readable and machine-parseable
Straightforward use in VS Code and other Markdown tooling

Why Google OKF is a Strong Format for Database Docs

SchemaCrawler Scribe outputs in Google Open Knowledge Format (OKF), which gives you one format that serves multiple use cases:

Human-friendly: Markdown pages are readable in editors, code review tools, and docs portals
AI-friendly: structured sections and metadata make extraction and grounding more reliable
Git-friendly: text output is diffable, reviewable, and easy to version
Tool-friendly: open format reduces lock-in and keeps migration options open
Team-friendly: works well in Visual Studio Code and any Markdown-centric workflow

In short: one documentation artifact that supports people, automation, and long-term maintainability.

If You Use SchemaSpy Today, This Will Feel Familiar

SchemaCrawler Scribe is in the same family of tooling as SchemaSpy: both crawl schema metadata and generate browsable documentation.

Like SchemaSpy-style documentation workflows, Scribe covers:

per-table pages (columns, keys, constraints, triggers, references)
cross-reference pages (what references what)
routine documentation (functions and stored procedures)
relationship visualization (Mermaid in Markdown)
lint and anomaly reporting in generated output

So if your team already likes auto-generated schema docs and relationship views, SchemaCrawler Scribe keeps that experience while producing Google OKF Markdown artifacts that are easier to review in Git and consume with AI tooling.

Usage

Run standard SchemaCrawler from the command line or Docker. Use the scribe command with okf output format.

Tips:

Use --title to label the generated documentation set
By default, output is zipped; add --expanded-output to generate a directory tree instead
Add --include-lint to generate schema design issue reports

docker run \
  --mount type=bind,source="$(pwd)",target=/home/schcrwlr/share \
  --rm -it \
  schemacrawler/schemacrawler \
  /opt/schemacrawler/bin/schemacrawler.sh \
  --server=sqlite \
  --database=sc.db \
  --info-level=maximum \
  --command scribe \
  --output-format okf \
  --title "Books Database" \
  --expanded-output \
  --include-lint \
  --load-row-counts \
  --output-file=share/schema

If you are using PowerShell, replace each trailing backslash with a backtick for line continuation.

Also see

SchemaCrawler AI MCP Server

How to Diff Database Migrations Automatically in CI/CD

Sualeh Fatehi — Sun, 21 Jun 2026 16:16:25 +0000

Database regressions rarely start with application code. They start when a migration changes a column type, removes an index, or introduces a nullable relationship that your code assumed was mandatory. The pull request looks fine, tests pass, and then production fails because the shape of the database drifted.

You can catch this in CI/CD by generating a text snapshot of your schema and diffing it as part of every pull request.

SchemaCrawler is a practical fit for this workflow because it outputs stable, diff-friendly schema text and runs cleanly in GitHub Actions through the SchemaCrawler Action (which uses Docker) or the SchemaCrawler Local Action (which installs SchemaCrawler on your runner).

The approach below gives you two protections:

A readable schema diff in your build logs.
A failed CI check when the schema changes unexpectedly.

Step 1: Generate Diff-Friendly Schema Snapshots Locally

Start by proving the workflow on your machine. Use two SQLite files (for example, before and after applying a migration) and compare the generated schema snapshots. Let us say that the files are called "database-before.db" and "database-after.db" on your local file system.

# Schema Before Migration
docker run \
--mount type=bind,source="$(pwd)",target=/home/schcrwlr/share \
--rm -it \
schemacrawler/schemacrawler \
/opt/schemacrawler/bin/schemacrawler.sh \
--server=sqlite \
--database=share/database-before.db \
--info-level=standard \
--command=schema \
--output-format=text \
--output-file=share/schema-before.txt

# Schema After Migration
docker run \
--mount type=bind,source="$(pwd)",target=/home/schcrwlr/share \
--rm -it \
schemacrawler/schemacrawler \
/opt/schemacrawler/bin/schemacrawler.sh \
--server=sqlite \
--database=share/database-after.db \
--info-level=standard \
--command=schema \
--output-format=text \
--output-file=share/schema-after.txt

# Diff
diff -u schema-before.txt schema-after.txt

If you are using PowerShell on Windows, replace each trailing backslash with a back-tick.

The output is plain text, so your diffs are reviewable in pull requests and easy to archive as artifacts.

Step 2: Add Schema Diff to GitHub Actions

Now automate the same check in CI/CD. The workflow below runs on pull requests, generates one schema snapshot from the base branch and one from the PR branch, then fails if they differ.

It uses schemacrawler/SchemaCrawler-Action to run SchemaCrawler in the pipeline. You can also use SchemaCrawler Local Action.

name: Detect Database Schema Drift

on:
  pull_request:
    branches: [ main ]

jobs:
  schema-diff:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout PR branch
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      # In a real project, replace this with your migration/build step
      # that creates the database file used for comparison.

      - id: schema-head
        name: Generate schema snapshot (PR)
        uses: schemacrawler/SchemaCrawler-Action@v17.11.3
        with:
          entrypoint: /schemacrawler.sh
          args: >
            --server=sqlite
            --database=/home/schcrwlr/sc.db
            --info-level=standard
            --command=schema
            --output-format=text
            --output-file=schema-pr.txt

      - name: Checkout base branch commit
        run: git checkout ${{ github.event.pull_request.base.sha }}

      # Run your base-branch migration/build step here as well.

      - id: schema-base
        name: Generate schema snapshot (base)
        uses: schemacrawler/SchemaCrawler-Action@v17.11.3
        with:
          entrypoint: /schemacrawler.sh
          args: >
            --server=sqlite
            --database=/home/schcrwlr/sc.db
            --info-level=standard
            --command=schema
            --output-format=text
            --output-file=schema-base.txt

      - name: Diff schema snapshots
        run: |
          git checkout ${{ github.sha }}
          if ! diff -u schema-base.txt schema-pr.txt > schema.diff; then
            echo "Schema drift detected between base and PR."
            cat schema.diff
            exit 1
          fi

      - name: Upload schema diff artifact
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: schema-diff
          path: schema.diff
          if-no-files-found: ignore

Step 3: Make the Differences Actionable

A failing check is useful only if developers can fix it quickly. Use these conventions:

Keep the diff in CI logs so reviewers can see what changed.
Upload schema.diff as a build artifact for larger diffs.
Decide policy per repository: just produce an informative report without failing, or fail on every schema change, or fail only when specific objects change.

If your schema changes are expected, the PR should include both migration code and reviewer-approved schema diff output. If a diff is unexpected, you have caught a regression before merge.

This is the core CI/CD hook:

Catch database schema regressions in pull requests before they reach production.

Notes for Production Databases

For PostgreSQL, MySQL, SQL Server, Oracle, and other JDBC databases, keep the same pattern and change only connection options. The strongest setup is:

Provision an ephemeral database in CI.
Apply base branch migrations and snapshot schema.
Apply PR branch migrations and snapshot schema.
Diff snapshots and fail on unexpected changes.

You can start with SQLite to validate the workflow and then switch to your production engine without changing the review model.

If you want a ready-made starting point, look at the SchemaCrawler Action usage example and adapt the workflow to your migration process.

Reverse Engineer Any Database into dbdiagram.io, PlantUML, Mermaid, or QuickDBD - Then Keep Designing

Sualeh Fatehi — Sat, 30 May 2026 20:06:07 +0000

Most database diagram tools stop at documentation. They connect to your database, inspect the schema, and generate a report or a picture. That is useful, but it does not help if your next step is design work.

What if you want to start from an existing database, open the result in a design tool, add a few new tables, adjust relationships, and then turn that updated design back into SQL?

SchemaCrawler supports that workflow.

SchemaCrawler can connect to any database with a JDBC driver and generate editable output in four useful formats:

DBML for dbdiagram.io
PlantUML for PlantText, IntelliJ, and other PlantUML tools
Mermaid for GitHub, GitLab, Notion, and the Mermaid Live Editor
QuickDBD for QuickDatabaseDiagrams.com

That gives you a practical round-trip workflow:

Connect to an existing database
Export the schema into DBML, PlantUML, Mermaid or QuickDBD
Edit the design in the tool you already use
Generate DDL from the updated design when you need SQL again

SchemaSpy is strong when you want a browsable HTML report for stakeholders. But HTML is the end of the line. You can read it, click through it, and share it, but you cannot open it in a design tool and keep working. If you need reverse engineer -> edit design -> generate DDL, SchemaCrawler is the better fit.

In this article, I will use the Northwind sample SQLite database for all examples.

Step 1: Connect

Make sure you have Docker installed. Then download the Northwind sample SQLite database into your current directory.

All commands below mount your current directory into the SchemaCrawler container, so the generated files are written back to your machine.

If you are using PowerShell on Windows, replace the trailing backslash on each line with a back-tick "`".

Step 2: Export

Export to DBML for dbdiagram.io

DBML is the best choice if you want to keep designing and later generate SQL from the updated model.

sh docker run \ --mount type=bind,source="$(pwd)",target=/home/schcrwlr/share \ --rm -it \ schemacrawler/schemacrawler \ /opt/schemacrawler/bin/schemacrawler.sh \ --server=sqlite \ --database=share/northwind.db \ --info-level=standard \ --command=script \ --script-language=python \ --script=dbml.py \ --output-file=share/northwind.dbml

Open dbdiagram.io, paste in the contents of northwind.dbml, and you immediately have an editable diagram based on the live database.

Export to PlantUML

PlantUML is a good choice if your team keeps diagrams in source control or already uses PlantUML in docs and architecture notes.

Open northwind.puml in PlantText or your IDE and keep editing.

Export to Mermaid

Mermaid is the best choice if you want diagrams that render directly in Markdown-based tools such as GitHub, GitLab, and Notion.

Paste northwind.mmd into the Mermaid Live Editor or commit it straight into your documentation.

Export to QuickDBD

QuickDBD is a good choice when you want fast, text-first schema editing in a dedicated diagram editor.

Paste northwind.quickdbd into QuickDatabaseDiagrams.com to continue editing.

Step 3: Edit

This is the part most reverse-engineering tools do not support well.

Once you have exported the live schema into an editable design language, you are no longer stuck with a read-only report. You can continue designing.

For example, imagine that after reverse-engineering northwind you want to add a table for storing playlist tags.

In DBML, you could extend the exported design with something like:

`dbml
Table PlaylistTag {
PlaylistTagId integer [pk]
PlaylistId integer [not null]
TagName varchar [not null]
}

Ref: PlaylistTag.PlaylistId > Playlist.PlaylistId
`

That is the key distinction in this workflow:

you start from what is actually in production
you bring that schema into an editable format
you extend the design instead of redrawing it from scratch

The same idea works with PlantUML, Mermaid, and QuickDBD. Add entities, adjust relationships, rename columns, or reorganize sections of the model for clarity. SchemaCrawler gets you to a clean starting point from a live database instead of forcing you to recreate the schema by hand.

Step 4: Generate DDL

DBML is especially useful because it can be turned back into SQL.

Install the DBML CLI:

sh npm install -g @dbml/cli

Then generate SQL from your updated design:

sh dbml2sql northwind.dbml --postgres

Or for MySQL:

sh dbml2sql northwind.dbml --mysql

Now you have a full round-trip flow:

reverse engineer from a live database
edit the design in a modeling tool
generate SQL from the updated design

That is a much more useful workflow than producing a static HTML report and stopping there.

Worked Example: northwind from Live Database to Editable Design

Here is the full DBML flow in one sequence.

1. Export northwind to DBML

2. Open the result in dbdiagram.io

Paste the contents of northwind.dbml into dbdiagram.io.

3. Extend the model

Add new tables, fields, and relationships directly in DBML.

4. Generate SQL

sh dbml2sql northwind.dbml --postgres

At that point you have gone from a real database to an editable design and back into SQL without manually redrawing anything.

When to Choose Each Output Format

Choose DBML if you want the strongest design-tool workflow and the option to generate SQL later.
Choose PlantUML if your team prefers text-based diagrams in source control or already uses PlantUML in architecture docs.
Choose Mermaid if you want diagrams that live directly inside Markdown, GitHub, GitLab, or internal docs.
Choose QuickDBD if you want rapid text-based editing in the QuickDatabaseDiagrams editor and an easy way to iterate on schema shape.

You do not need to choose only one forever. The same database can be exported to all four, depending on what the next step in your workflow looks like.

Why This Matters

Reverse engineering is only half the job.

Developers often inherit an existing database and need to answer more than "what tables are there?" They need to ask:

what should we add next?
how do we model the next feature without breaking what exists?
how do we propose changes in a format that is easy to review?
how do we get from the current schema to future DDL with less manual work?

SchemaCrawler helps because it starts with the live database and produces output you can keep working with.

That is the real value of DBML, PlantUML, Mermaid, and QuickDBD export. Not just nicer diagrams, but a better workflow.

Try It Yourself

Start with the northwind sample database and generate one of the editable formats above. Once you have the workflow working locally, switch the connection to PostgreSQL, MySQL, SQL Server, Oracle, DB2, or any other JDBC database supported by SchemaCrawler.

If you want to customize the generated output, you can find and edit the built-in scripts:

SchemaSpy vs SchemaCrawler - Which Database Documentation Tool is Right for You?

Sualeh Fatehi — Tue, 26 May 2026 23:47:18 +0000

Both SchemaSpy and SchemaCrawler are free, open-source tools for documenting and analysing relational databases over JDBC. Both have been around for over 20 years. Both can generate entity-relationship diagrams. Yet the two tools are more different than they look.

Disclosure: I work on SchemaCrawler, so take this with appropriate scepticism. I have tried to represent SchemaSpy fairly.

What SchemaSpy Does Best

SchemaSpy's primary strength is its interactive HTML report. After a single run, you get a navigable website: clickable table pages, hyperlinked foreign keys, anomaly reports, and embedded ER diagrams for every table. It is exactly the kind of output you hand to a non-technical stakeholder, a consultant, or a new team member who needs to understand the data model quickly.

SchemaSpy also detects implied relationships - potential foreign keys that are not formally declared in the schema. It provides an orphan table page that surfaces tables with no relationships. These are genuinely useful for legacy databases.

If your goal is a shareable, browsable report that looks great in a browser, SchemaSpy delivers.

What SchemaCrawler Does Best

SchemaCrawler's strength is everything a developer needs before and after the report: searching, diffing, linting, scripting, and integration.

Diff-able text output

SchemaCrawler's "schema" command produces clean, structured text output - not HTML. Run it against production and staging, diff the outputs in git, and see exactly what changed. This is the foundation of schema change tracking in CI/CD.

Schema lint

The "lint" command catches design problems automatically: missing primary keys, nullable columns in unique constraints, redundant indices, tables with no relationships, and more. The lints can be extended to enforce your organization's rules, such as specific naming conventions.

Grep - regex search across the entire schema

--grep-tables and --grep-columns let you search all tables, columns, stored procedures, triggers, and foreign keys by regular expression. Find every column referencing a concept across a 500-table database in a single command. Combine it with --parents and --children to pull the related tables automatically.

Multiple output formats

Text, HTML, JSON, CSV, Markdown, and ER diagrams (via Graphviz). The Markdown output is useful for documentation-as-code; the JSON output is useful for tooling.

Schema extension with PlantUML and dbdiagram.io

SchemaCrawler can generate output in PlantUML and dbdiagram.io formats directly from your live database. This means you can start from what is actually in the database and then edit the diagram to model proposed additions or changes - something neither SchemaSpy nor most ERD tools support directly.

Scripting - Python, JavaScript

--command=script runs a script against live schema metadata. Generate custom reports, validate naming conventions, transform output - without writing a Java application.

Full Java API

SchemaCrawler is a JDBC metadata API. Embed it in a Java application and work with tables, columns, indexes, foreign keys, and routines as Java objects. SchemaSpy has no public API.

GitHub Actions integration

There is an official SchemaCrawler GitHub Action in the marketplace. Run lint, diff, and schema documentation generation as part of any CI/CD workflow. SchemaSpy has no equivalent.

Feature Comparison

Capability	SchemaCrawler	SchemaSpy
Interactive HTML report	✅	✅
Clickable navigation between tables	✅	✅
ER diagrams	✅	✅
Diff-able text output	✅	❌
Extensible schema lint / design checks	✅	❌
Grep / regex search across schema	✅	❌
Markdown, JSON, CSV output	✅	❌
PlantUML and dbdiagram.io output	✅	❌
Scripting (Python, JS, Groovy)	✅	❌
Java API	✅	❌
GitHub Actions integration	✅	❌
Implied relationship detection	✅	✅
Orphan table detection	✅	✅

Decision Guide

Choose SchemaSpy if…

Your primary output is a shareable, interactive HTML report for non-technical stakeholders
You want clickable navigation between related tables out of the box
You need implied/ virtual foreign key detection for a legacy schema with missing FK declarations

Choose SchemaCrawler if…

You need to track schema changes in version control - diff text output between environments
You want to catch design problems automatically - schema lint in CI
You need to search across a large schema - find all tables or columns matching a pattern
You are building schema checks into a CI/CD pipeline - GitHub Actions integration
You need output in Markdown, JSON, or CSV as well as HTML
You want to model future schema designs in PlantUML or dbdiagram.io, starting from your live database
You want to write scripts that process schema metadata programmatically
You are building a Java application that needs database metadata as objects

Can You Use Both?

Yes. They serve genuinely different workflows.

Use SchemaSpy to generate the stakeholder-facing HTML report. Use SchemaCrawler for diff, lint, and grep in your development and CI/CD workflow. The two tools are not competitors - they complement each other.

Try SchemaCrawler

The full documentation is at schemacrawler.com. The source is at github.com/schemacrawler/SchemaCrawler.

3-way Boolean Anti-pattern

Sualeh Fatehi — Sat, 14 Feb 2026 18:22:36 +0000

In Java, the "3-way Boolean" anti-pattern is what you get when you use the boxed type Boolean (instead of primitive boolean) and you implicitly allow it to represent three states:

true
false
null ← the third, often accidental, state

That "third state" becomes a trap because most code reads like it's dealing with a simple yes/ no flag, but at runtime it can behave differently (or crash) when the value is null.

Why it's an anti-pattern

It creates implicit tri-state logic without making it explicit
A variable named enabled, isReady, shouldRetry, etc. strongly implies binary logic, but Boolean quietly allows null, which means unknown, not set, not loaded, not applicable, or sometimes just "bug".
It can throw NullPointerException (NPE) during unboxing
Common expressions like these will NPE if the Boolean is null:

   Boolean flag = getFlag();     // could be null
   if (flag) {                   // auto-unboxing -> NPE if null
       // ...
   }

This exact failure mode is commonly seen during upgrades or refactors because the code compiles fine but fails at runtime.

It leads to confusing "null means false... except when it doesn't" logic People often "fix" the NullPointerException by doing inconsistent checks:

   if (flag != null && flag) ...
   // elsewhere
   if (Boolean.TRUE.equals(flag)) ...
   // elsewhere
   if (Boolean.FALSE.equals(flag)) ...

Now your codebase has multiple semantic interpretations of null.

Generate MCP Tool Schemas Directly From Java Code

Sualeh Fatehi — Thu, 20 Nov 2025 02:59:44 +0000

If you are building an MCP server, every tool you expose needs an inputSchema. MCP servers written with Spring AI support often start with a simple data class for tool inputs. Then come changes: a new field, a renamed property, or updated constraints. The JSON schema in the tool registration rarely keeps up - that means clients may send invalid payloads. By generating the schema from the source of truth — the Java type — you remove that drift.

Writing that JSON by hand is repetitive, easy to get wrong. MCP supports only a specific sub-type of the JSON Schema specification. The MCP JSON Schema library keeps the parameter schema and the code in lockstep by generating the MCP-compatible JSON Schema from a Jackson 3 annotated Java class or record.

What you get:

Use of Jackson 3 annotations for naming, required fields, and descriptions that carry over into the schema
Use of Jakarta Bean Validation to adds meaningful constraints to the schema (for example, @Max,@Min, @Positive, @PositiveOrZero, @Negative, @NegativeOrZero on numbers, or @Size, @NotBlank on strings)
Automatic handling of required fields, defaults, enums, and descriptions
Output that targets the MCP JSON Schema subset, not the entire JSON Schema specification

How it works

Add a dependency to us.fatehi:mcp-json-schema in Maven or Gradle.

<dependency>
    <groupId>us.fatehi</groupId>
    <artifactId>mcp-json-schema</artifactId>
    <version>1.0.1</version>
</dependency>

Define a parameters type as a Jackson‑annotated record or class and let the library produce the inputSchema JSON. Use annotations to describe intent, and let the library translate that into the MCP schema format.

For example:

import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.annotation.JsonPropertyDescription;
import tools.jackson.databind.PropertyNamingStrategies;
import tools.jackson.databind.annotation.JsonNaming;

@JsonNaming(PropertyNamingStrategies.KebabCaseStrategy.class)
public record SampleParameters(
    @JsonPropertyDescription("Type of database table dependant objects.")
    @JsonProperty(defaultValue = "NONE", required = true)
    DependantObjectType dependantObjectType,

    @JsonPropertyDescription("Table name.")
    String tableName) {

  public enum DependantObjectType 
    { NONE, COLUMNS, INDEXES, FOREIGN_KEYS, TRIGGERS }
}

Next, generate the MCP inputSchema:

import us.fatehi.mcp_json_schema.McpJsonSchemaUtility;

// Provide this value as the tool's input_schema 
// in your Spring AI MCP server implementation
String inputSchemaJson = 
  McpJsonSchemaUtility.inputSchema(SampleParameters.class);

Prefer a JsonNode for programmatic changes? Use:

var schemaNode = 
  McpJsonSchemaUtility.generateJsonSchema(SampleParameters.class);

The source code is available at sualeh/mcp-json-schema

Why Your Claude Skills Deserve Better: Escape the Sandbox with MCP Skill Hub

Sualeh Fatehi — Mon, 27 Oct 2025 12:21:07 +0000

If you've been working with Claude skills, you've probably felt the frustration of hitting sandbox limitations. Your Python code can't access files, make network requests, or interact with your local system. That's where the MCP Skill Hub comes in – it takes your existing Claude skills and unleashes their full potential locally.

The Claude Skills Sandbox Problem

Claude skills are great for quick demonstrations, but they're severely limited:

❌ No file-system access
❌ No network requests
❌ No system commands
❌ No persistent storage
❌ No real-world integrations

Your skills can show examples and explain concepts, but they can't actually do the work.

Skills That Actually Work

The MCP Skill Hub changes everything. It takes your existing Claude Skills (same YAML frontmatter format, same Markdown content) and runs them locally through the Model Context Protocol.

Check out the examples in srprasanna/mcp-skill-hub for working code.

What Changes When You Go Local

Before (Claude Sandbox):

"Here's how you would read an Excel file..."
"This code demonstrates the concept..."
"In a real environment, you could do this..."

After (MCP Local):

Your skill actually reads files from your computer
Real database connections, API calls, file operations
Integration with your actual development workflow

Beyond Claude: Any Agent, Any Model

Here's the kicker – you're not locked into Claude anymore. The MCP Skill Hub works with:

Claude Desktop (obvious choice)
Cline/Cursor (VS Code integration)
Open WebUI (local models)
Any MCP-compatible agent

Your skills become portable across the entire AI ecosystem.

Getting Started is Dead Simple

The server enforces a clean folder structure that makes sense:

~/my-skills/
├── excel-automation/
│   ├── SKILL.md          ← Your existing skill content
│   └── examples/         ← Working Python scripts
├── database-queries/
│   ├── SKILL.md
│   └── examples/
└── file-processing/
    ├── SKILL.md
    └── templates/

Run it with Docker:

docker run -i --rm \
  -v ~/my-skills:/skills:ro \
  srprasanna/mcp-skill-hub

Hot-reload is built-in – edit your skills and see changes instantly without restarting.

Production Ready Features

🔄 Hot-reload – edit skills without restarting
🐳 Docker support – run anywhere containers run
📊 Rich metadata – categories, tags, complexity levels
🔍 Search tools – find skills by query or category
📝 Full documentation – comprehensive guides and examples
✅ Type-safe – modern Python 3.13+ with full type hints

The Bottom Line

Your Claude skills are just the beginning. The MCP Skill Hub takes that same familiar format and removes all the limitations. Your skills can finally do real work – read files, make API calls, automate your actual workflow.

And since it's MCP-compliant, you can use those skills with any compatible AI agent, not just Claude.

Ready to escape the sandbox? Check out the MCP Skill Hub on GitHub or install directly from the MCP Registry.

Your skills deserve to run free. 🚀

The MCP Skill Hub is open source (MIT license) and available on Docker Hub. It's production-ready with comprehensive testing and documentation.

Revolutionize Your Database Development with SchemaCrawler MCP Server

Sualeh Fatehi — Sat, 24 May 2025 22:21:28 +0000

Imagine having an AI assistant that actually understands your database schema and helps you make sense of your tables and columns, helps you craft perfect SQL queries that actually work, and saves you from hours of documentation diving. The SchemaCrawler MCP Server is here, and it it free and open source.

Forget complex installations and configuration headaches. The SchemaCrawler MCP Server runs in a Docker container, meaning you can get up and running with just a few commands, using your favorite MCP Client in "Agent" mode.

What Can It Do For You?

🔍 Explore Your Database Structure

View all tables and views at a glance
Examine column details including data types and constraints
Understand relationships between tables with foreign key information

🛠️ Improve Your Database Design

Find design issues with the built-in schema linting
Discover missing indexes that could improve performance
Identify nullable columns in unique constraints

📝 Simplify SQL Development

Understand table schemas before writing queries
See sample data to better understand the information you're working with
Generate proper SQL based on your database structure

Getting Started in 4 Easy Steps

Clone https://github.com/schemacrawler/SchemaCrawler-MCP-Client-Usage
Start the Server

   docker-compose -f schemacrawler-mcpserver.yaml up -d

Verify It's Running
Check server health at http://localhost:8080/health
Connect in VS Code
The server is already configured in .vscode/mcp.json - just open VS Code and start asking questions!

Connect to Your Own Database

Want to use this with your own database? No problem!

Stop the current server

   docker-compose -f schemacrawler-mcpserver.yaml down -t0

Edit the connection details
Update schemacrawler-mcpserver.yaml with your database connection information
Restart the server

   docker-compose -f schemacrawler-mcpserver.yaml up -d

Start Exploring Today!

Simply ask questions about your database in VS Code's chat panel:

"What tables are available in my database?"
"Show me the columns in the Books table"
"What foreign keys reference the Authors table?"
"Are there any design issues with my database schema?"
"Write SQL to find books and their authors"

Calculate the DORA Lead Time Metric in Python

Sualeh Fatehi — Thu, 10 Apr 2025 23:03:47 +0000

DORA (DevOps Research and Assessment) metrics have become the gold standard for measuring software delivery performance. Among these metrics, Lead Time for Changes is a good indicator of your team's efficiency to deliver changes in production. Let us understand what this metric is, why it matters, and how you can calculate it using Jira and GitHub data with Python code.

What is the DORA Lead Time Metric?

Lead Time for Changes measures the duration from when code is first committed until it is successfully deployed to production. In simpler terms, it answers the question: "How long does it take for a code change to go from a developer's machine to serving users in production?"

According to DORA research, organizations typically fall into these performance categories:

Elite performers: Less than one hour
High performers: Between one day and one week
Medium performers: Between one week and one month
Low performers: Between one month and six months

A shorter lead time indicates:

Faster delivery of features to users
Quicker bug fixes and security patches
More agile response to changing requirements
Less work-in-progress building up
Reduced context switching for developers

So, lead time is a powerful indicator of your development process efficiency. Long lead times often signal bottlenecks in your development pipeline that need addressing.

Calculating Lead Time

If you use Jira and GitHub, you can calculate lead time by connecting data from both platforms. The calculation involves several steps:

Projects → Releases → Stories → Pull Requests → Commits

Projects: First, gather all software projects from Jira
Releases: For each project, collect released versions within a specified date range
Stories: Identify all Jira stories associated with each release
Pull Requests: For each story, find the linked GitHub pull requests
Commits: Within each pull request, analyze all commits

For each pull request, lead time is calculated as:

lead_time = release_date - earliest_commit_date + 1

The key here is using the earliest commit date rather than the pull request creation date. This captures the true beginning of work, even if the pull request was created later. The final DORA lead time metric is calculated by averaging all individual lead times over a specified time period, for a given set of projects.

Manage This in Jira and GitHub

To effectively use this approach, you need to understand how to manage the key components in Jira. Create Jira releases (or "versions") for each planned release, and set release dates when versions are published. Mark versions as "Released" once deployed. Assign the release to a project. In this context projects typically represent teams, products, or components. Stories are work items (features, bugs, etc.) included in releases. Use the Jira GitHub integration to connect your repositories. Reference Jira issues in pull request titles or descriptions** (e.g., "PROJ-123: Add new feature"). Use smart commits in your commit messages.

Using Python to Generate lead Time Reports

The dora-lead-time package provides a simple way to calculate and visualize lead time metrics. It connects to your Jira and GitHub data, calculates lead times, and generates reports. Here is how you might use the package to generate a monthly lead time report:

First set up your tokens to access Jira and GitHub. Set the following environmental variables.

Create ATLASSIAN_TOKEN containing the API token for Atlassian Jira access.
Create JIRA_INSTANCE for your Jira instance URL (e.g., company.atlassian.net)
Create EMAIL for your Atlassian account email address.
Create personal access tokens for each GitHub organization, for example, GITHUB_TOKEN_ORG1, GITHUB_TOKEN_ORG2, etc. to authenticate API requests to specific GitHub organizations. Each organization you need to access requires its own token.
Create an environmental variable GITHUB_ORG_TOKENS_MAP which is a JSON string mapping organization names to environment variable names. For example: GITHUB_ORG_TOKENS_MAP={"Org1": "GITHUB_TOKEN_ORG1", "Org2": "GITHUB_TOKEN_ORG2"}

You can optionally set

SQLITE_PATH which is the path where the SQLite database will be created.
START_DATE and END_DATE to define the date range for which to calculate lead time metrics, using ISO date strings (YYYY-MM-DD).

Here is a complete examples which you can put in a ".env" file:

GITHUB_TOKEN_ORG1=your_personal_access_token_for_org1
GITHUB_TOKEN_ORG2=your_personal_access_token_for_org2
GITHUB_ORG_TOKENS_MAP={"Org1": "GITHUB_TOKEN_ORG1", "Org2": "GITHUB_TOKEN_ORG2"}
ATLASSIAN_TOKEN=your_atlassian_api_token
JIRA_INSTANCE=your_company.atlassian.net
EMAIL=your_email@your_company.com
SQLITE_PATH=./releases.db
START_DATE=2023-01-01
END_DATE=2023-12-31

Then run code similar to the following to generate a lead time report:

from datetime import date
from dora_lead_time.lead_time_report import LeadTimeReport

# Initialize the report generator
report = LeadTimeReport("releases.db")

# Define the scope
project_keys = ["FRONTEND", "BACKEND", "MOBILE"]
start_date = date(2025, 1, 1)
end_date = date(2025, 12, 31)

# Generate a monthly report
monthly_data = report.monthly_lead_time_report(project_keys, start_date, end_date)

# Display and visualize the report
print(monthly_data)

# Create a visualization
plt = report.show_plot(monthly_data, title="2025 Monthly Lead Time", show_trend=True)
plt.savefig('lead_time_trend.png')

The full code is available on GitHub.

The report allows you to:

Track lead time trends over months
Compare performance across different projects
Identify when process changes impact lead time
Set targets based on DORA performance levels

Additionally, the project includes SQL-based outlier reports to identify issues like:

Projects without releases
Releases with open stories
Stories in multiple releases
Stories without pull requests

Conclusion

Calculating the DORA Lead Time metric provides valuable insights into your software delivery performance. By connecting data from Jira and GitHub, this approach gives you an accurate measurement that truly reflects your development process. The real power comes from using this data to identify bottlenecks and continuously improve your delivery pipeline. Whether you're aiming to move from "medium" to "high" performer status or already pursuing "elite" performance, measuring lead time is an essential step in the journey.