What does SchemaSpy produce?

A directory of HTML with a page per table, relationship diagrams and orphan/constraint analysis. Upload the directory so the diagrams and per-table pages come along with the entry page.

Why publish it instead of regenerating it locally?

Because most of the people with schema questions cannot connect to the database — analysts, new engineers, a partner team building an integration. Schema documentation is only useful where those people already are, which is a browser.

How do I keep it from going stale?

Regenerate on a routine and PATCH the same report id. Schema docs die when they are a one-off; on a schedule the URL is current by construction, and each run stays available as a revision.

Can people ask questions about a specific table?

Yes — anchored threads. 'Is this column still populated?' sits on the column, and the answer is there for the next person who wonders, which is the failure mode of a wiki page about a schema.

Is it safe to publish?

A schema is a fairly complete map of your data model, so keep it private or team-visible. SchemaSpy documents structure rather than rows, but structure is still worth protecting.

Share SchemaSpy database docs

Every team has a schema question queue, and it is answered by the same two people, from memory. What is orders.status_v2 for? Which table actually holds the current address? Is that foreign key still enforced?

SchemaSpy answers all of these mechanically — a page per table, relationship diagrams, constraint and orphan analysis — and produces a directory of HTML that lands wherever the job ran.

Publish it

java -jar schemaspy.jar \
  -t pgsql -db "$DB" -host "$HOST" -u "$DB_USER" \
  -o ./schema-docs

Drag schema-docs/ into the app: index.html becomes the report body, and the per-table pages, diagrams and CSS upload as assets with their references rewritten to the uploaded copies. Publishing the index alone gives you a contents page whose links go nowhere.

For CI, PATCH the same report id after each regeneration:

curl -fsS -X PATCH \
  "https://commareports.com/api/v1/reports/$COMMA_REPORT_ID" \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile html ./schema-docs/index.html \
        --arg title "Schema — $DB — $(date +%F)" \
        '{title: $title, html: $html}')"

What the URL changes

Questions land on the table. "Is this column still populated?" pinned where the answer will be found again. See commenting on HTML.
Documentation that cannot go stale. A routine regenerates it on a schedule, so the URL reflects the schema rather than the schema as of whenever someone last cared.
Onboarding without a database credential.
Private or team-visible — a schema is a map of your data model. See the sharing model.

Limits

Entry HTML: 5 MB. Assets: 25 MB per file, 250 MB and 500 files total — a database with several hundred tables generates a page and a diagram each and can pass 500 files. Publish per schema when it does.
Scripts run, sandboxed: allow-scripts, no allow-same-origin.
60 requests/minute per token.

Try it

Comma is free — unlimited reports, unlimited commenters, unlimited revision history.

Create your first report →

pgBadger reports — the runtime view of the same database
dbt docs · OpenAPI docs
Routines · Publish from CI

Share SchemaSpy database docs

Publish it

What the URL changes

Limits

Try it

Related