[opensourcedex]

schemaspy is a free, open source documentation & knowledge base project written in HTML and released under LGPL-3.0. It has 3,736 GitHub stars, 357 forks and 303 open issues, and was last pushed 8 months ago. On this registry it ranks #40 of 100 tracked projects in Documentation & Knowledge Base, with 5 head-to-head comparisons available. It gained 5 stars over the last 30 tracked days.

What is schemaspy?

SchemaSpy is a standalone Java-based database metadata analyzer that reverse-engineers an existing database schema and produces a browsable HTML report with entity-relationship diagrams, for database administrators and developers who need to understand a data model they did not design.

What it is

SchemaSpy is a database metadata analyzer distributed as a standalone application with no GUI. It connects to a live database through JDBC, reads the catalog metadata, and generates a static HTML report containing entity-relationship diagrams, table listings, column definitions, constraints, and relationships. The report is a directory of plain HTML files, so it can be published on any web server or opened directly from the filesystem at DIRECTORY/index.html. SchemaSpy lives in the Java ecosystem and is published to Maven Central.

The concrete problem it solves is the absence of current, navigable documentation for databases that already exist. Teams inherit production schemas with hundreds of tables and no diagram, no data dictionary, and no reliable map of foreign keys. SchemaSpy replaces hand-drawn and quickly outdated ER diagrams by deriving documentation mechanically from the database itself, which means the output reflects what is actually deployed rather than what a wiki page claims. Because the report is regenerated on demand from the live catalog, it does not drift the way manually maintained documentation does.

Key capabilities

  • Generates an HTML report with entity-relationship diagrams from live database metadata, browsable from DIRECTORY/index.html.
  • Supports over a dozen database types out of the box, selectable with the -t flag; PostgreSQL 11 or later uses -t pgsql11, and the full list is printed by -dbhelp.
  • Accepts any database with a JDBC driver as a pluggable database type.
  • Distributes two JAR variants published to Maven Central: a bare-bone JAR at org.schemaspy:schemaspy and a fat JAR at org.schemaspy:schemaspy: :app with the app classifier.
  • Runs as a Docker image, schemaspy/schemaspy, including a snapshot tag for unreleased bug fixes and in-progress features.
  • Documents foreign keys through the -dp JDBC driver path, -db, -host, -port, -u, -p, and -o output directory arguments.
  • Targets data-dictionary and ER-diagram deliverables directly: the topic list names data-dictionary, database-diagrams, entity-relationship-diagram, er-diagram, and reverse-engineering.

Who uses it and how

  • Database administrators who need to hand developers a current map of a production schema rather than a stale diagram.
  • Developers joining a project with a large inherited schema, using the generated ER diagram to traverse relationships instead of reading DDL by hand.
  • Teams supporting on-demand database documentation, which the README names as the preferred way to document databases.
  • Environments running more than one database engine, since SchemaSpy covers over a dozen types and accepts any JDBC driver.
  • CI-style or repeatable runs where the report is regenerated and served as static HTML from the output directory.

Getting started

Download the latest release JAR from GitHub, or pull the Docker image schemaspy/schemaspy; SchemaSpy takes no GUI setup beyond providing a JDBC driver for the target database and invoking it with the connection flags described above.

How it compares

The facts do not name any paid products this project replaces, and they do not name comparable tools. SchemaSpy stands alone in this registry on the evidence provided: no competing database documentation generator is cited here, and the comparison rests only on its own declared scope of metadata analysis and HTML report generation.

When to use it — and when not to

SchemaSpy produces static output rather than a hosted service, so the operator must supply a database connection and a JDBC driver, and must have somewhere to serve or store the generated HTML directory. It is the wrong choice for anyone wanting a managed, continuously updated documentation portal, or for schemas without a JDBC driver and outside the supported database list. The honest limitations in the provided facts are the issue backlog and the fact that the README excerpt is cut off mid-section: 303 open issues against 3,723 stars signals active but unresolved maintenance load, and the repository does not supply a complete feature description here.

project readme (upstream, from github) — read inline

Logotype

Maven Central Docker Pulls Development Documentation Status Quality Gate Coverage Gitter

SchemaSpy is a database metadata analyzer. It helps your database administrators and developers visualize, navigate and understand your data model. With an easy-to-use HTML-based report, traversing the entity-relationship diagram has never been simpler. Our product showcase is available at http://schemaspy.org/sample/index.html.

SchemaSpy sample

Installation

SchemaSpy is a standalone application without GUI. Just download the latest JAR file or Docker image and you're ready to go! To use SchemaSpy from Maven, please see the Maven chapter below.

# replace '6.2.4' with latest version
curl -L https://github.com/schemaspy/schemaspy/releases/download/v6.2.4/schemaspy-6.2.4.jar \
    --output ~/Downloads/schemaspy.jar

For unreleased bug fixes and features-in-progress, download our snapshot JAR or use Docker tag snapshot

Maven

SchemaSpy releases two types of JAR files: a bare-bone JAR and a fat JAR including all dependencies. Both JARs are published to Maven Central. The fat JAR is also attached to releases on GitHub. The "maven central" badge at the top of this page will take you straight to the latest version on Maven Central.

The Maven GAV of the two artifacts is as follows:

  • bare-bone JAR: org.schemaspy:schemaspy:
  • fat JAR: org.schemaspy:schemaspy::app ← note the app classifier

Quick start

Let's assume you're using PostgreSQL (11 or later). First, download their JDBC driver.

curl -L https://jdbc.postgresql.org/download/postgresql-42.5.4.jar \
    --output ~/Downloads/jdbc-driver.jar

Then run SchemaSpy against your database and you're ready to browse it in DIRECTORY/index.html.

java -jar ~/Downloads/schemaspy.jar \
    -t pgsql11 \
    -dp ~/Downloads/jdbc-driver.jar \
    -db DATABASE \
    -host SERVER \
    -port 5432 \
    -u USER \
    -p PASSWORD \
    -o DIRECTORY

If you aren't using PostgreSQL, don't panic! Out of the box, SchemaSpy supports over a dozen different databases. List them by using -dbhelp. Still not enough? As long as your database has a JDBC driver you can plug it in to SchemaSpy.

Documentation and FAQs

We host our documentation on Read the Docs. Be sure to check out the section on troubleshooting common problems.

Main use cases

SchemaSpy covers a lot of use cases for database analysis and documentation. Be sure to check out the guides provided by the community later in this README.

On-demand database documentation

The preferred way to document databases is through entity-relationship (ER) diagrams. However, drawing these diagrams manually is such a time-consuming and error-prone process that we hardly ever draw them in practice. When the diagrams are drawn, they rarely stay up-to-date. With SchemaSpy, this is no longer a problem. The diagrams can be generated quickly and even as a part of your CI/CD workflow to ensure it's always up to date.

Your database in numbers

SchemaSpy can collect various kinds of interesting statistics to describe the shape and form of your database's structure. Drill down deeper into these statistics directly in the report or export them to excel or CSV for further QA analysis.

Keep the data confidential

Nowadays, a company's data can be their most valuable asset. Since SchemaSpy only reads structural information, it works just as well on an empty database replica. This means that the report can be shared for third party analysis without fear.

Detect sub-optimal constructs

SchemaSpy incorporates knowledge about best practices in database design. It can locate and report anomalies such as missing indexes, implied relationships, and orphan tables.

Community

Welcome to the SchemaSpy community! Just reading this file or using the tool means that you're a part of our community and contributing to the future of the project. We're grateful to have you with us!

Some of our community members have put extra effort into sharing SchemaSpy with more people, asked their companies to provide financial aid, or decided to improve the software. We wish we had the space to thank each of you individually because every Github star, tweet or other activity reminds us that our work is appreciated.

Special thanks

For creating the first five versions of SchemaSpy:

For perpetuating SchemaSpy ever since:

For creating tutorials and guides for the community:

Scientific usage

We are proud to note that SchemaSpy assists researchers in their work.

Build Instructions

Application

SchemaSpy is built using maven and we utilize the maven wrapper.
Windows mvnw.cmd package
Linux ./mvnw package
The resulting application can be found in target

Analyzing

You need your own SonarQube:
https://hub.docker.com/_/sonarqube/
Windows mvnw.cmd -P sonar clean verify -Dsonar.host.url=http://$(boot2docker ip):9000 -Dsonar.jdbc.url="jdbc:h2:tcp://$(boot2docker ip)/sonar"
Linux ./mvnw -P sonar clean verify

Watch results at:
Linux http://localhost:9000
Windows http://$(boot2docker ip):9000

Documentation

Built using Python
Create venv
Install dependencies pip install -r docs/requirements.txt
Navigate into docs
Windows make.bat clean && make.bat html
Linux make clean html
The resulting documentation can be found in docs/build/html

Frequently asked questions

Is schemaspy free to use?

schemaspy is open source under the LGPL-3.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does schemaspy do?

Database documentation built easy

What is schemaspy written in?

schemaspy is primarily written in HTML. Its source is publicly available at https://github.com/schemaspy/schemaspy, and it has 3,736 GitHub stars.