Generate database documentation with SchemaSpy & Docker (Windows, Linux, macOS)

Introduction

SchemaSpy is a tool that allows you to generate interactive HTML documentation from databases. In this guide, I will use Oracle as an example, but you can also use SchemaSpy with PostgreSQL, MySQL, SQL Server, etc. Thanks to Docker, you can easily run it on Windows, Linux, or macOS. Let's get started! 🚀

Prerequisites

Docker installed on your system:

• Docker Desktop
• JDBC driver. Tis image includes drivers for:
• MySQL
• MariaDB
• PostgreSQL
• jTDS

If you use any of these, you do not need to download any drivers.

Since this guide uses Oracle Database as an example, you will need to download the Oracle JDBC driver ojdbc11.jar from the Oracle website.

---

Getting Started

Step 1: Create the working directory

Open your terminal and run:

mkdir schemaspy-doc && cd schemaspy-doc
mkdir drivers output

Step 2: Add the JDBC driver

Move the downloaded driver (in this case ojdbc11.jar) into the drivers/ folder.

Step 3: Create schemaspy.properties

Create a schemaspy.properties file with the following content:

schemaspy.t=orathin-service
schemaspy.driver=oracle.jdbc.OracleDriver

schemaspy.host=server_or_ip
schemaspy.port=1521
schemaspy.db=db_name
schemaspy.u=database_user
schemaspy.p=database_password
schemaspy.schema=schema_name

schemaspy.norows=true
schemaspy.noviews=true
# Required in Oracle
schemaspy.cat=%

Not sure what value to use for the schemaspy.t parameter? 👀 Run:

docker run --rm schemaspy/schemaspy -dbHelp

You will get a list of supported database types and the parameters each one requires.

Step 4: Run SchemaSpy with Docker

On Linux/macOS:

docker run --rm \
  -v "$(pwd)/schemaspy.properties:/schemaspy.properties" \
  -v "$(pwd)/output:/output" \
  -v "$(pwd)/drivers:/drivers" \
  schemaspy/schemaspy

On Windows:

docker run --rm `
  -v "${PWD}/schemaspy.properties:/schemaspy.properties" `
  -v "${PWD}/output:/output" `
  -v "${PWD}/drivers:/drivers" `
  schemaspy/schemaspy

If you use localhost as the database host within the Docker container, it will not work because localhost points to the container itself, not to your host machine. ⚠️

Solution: Use host.docker.internal as the host to connect from the container to your local machine. For example:

schemaspy.host=host.docker.internal

Step 5: View the generated documentation

Once the command finishes, open the output/index.html file in your favorite web browser. You’ll find:

• Entity relationship diagrams
• Table structures
• Columns, indexes, relationships, etc
• A beautiful (and clickable!) and interactive HTML interface

Example Output 📸