# Share SchemaSpy Database Docs — A Browsable Schema on a Link

Canonical: https://commareports.com/share-schemaspy-docs
Published: 2026-09-01

> SchemaSpy generates a browsable HTML view of a database schema with relationship diagrams. Publish it to Comma so the schema is a URL, questions land on the table, and each run is a revision.

# 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

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

Drag `schema-docs/` into [the app](https://commareports.com/):
`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:

```bash
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](/comment-on-html).
- **Documentation that cannot go stale.** A [routine](/docs/routines)
  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](/docs/sharing).

## 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 →](https://commareports.com/)**

### Related

- [pgBadger reports](/share-pgbadger-report) — the runtime view of the same database
- [dbt docs](/share-dbt-docs) · [OpenAPI docs](/share-openapi-docs)
- [Routines](/docs/routines) · [Publish from CI](/docs/ci)