Migrate from SchemaSpy to SchemaCrawler Without Rewriting Your Runbooks

Description and use

Migrate database documentation from SchemaSpy to SchemaCrawler without rewriting scripts: use the shim, generate OKF Markdown bundles, commit to Git, and publish via GitHub Pages.

Problem

Teams using SchemaSpy for database documentation face difficulty migrating to SchemaCrawler without rewriting all scripts.

Outcome

Teams can migrate to SchemaCrawler while keeping existing CLI scripts, producing Markdown docs that integrate with Git workflows and GitHub Pages.

Workflow

• 1. Install SchemaCrawler (Docker image or installer) which includes the schemaspy shim.
• 2. Replace existing SchemaSpy command with the shim (e.g., schemaspy -t sqlite -db ./sc.db -u sa -p "" -o ./schema-output.zip).
• 3. Verify output is an OKF ZIP bundle or expanded directory.
• 4. Optionally run native SchemaCrawler commands (e.g., schemacrawler.sh --command scribe --output-format okf).
• 5. Commit generated Markdown to a Git branch or repository.
• 6. Set up a GitHub Actions workflow to generate OKF on schedule or on schema changes.
• 7. Deploy the OKF directory to GitHub Pages using Jekyll.
• 8. Store database credentials in GitHub Actions secrets and pass them to the container.

Evidence

The latest SchemaCrawler release includes a SchemaSpy-compatible shim.

Source

SchemaCrawler produces documentation in Google Open Knowledge Format (OKF).

Source

OKF uses Markdown files with YAML frontmatter and links between related documents.

Source