Orbis Tertius

A tool to generate a human-readable data dictionary from the schema of an existing PostgreSQL database.

setup.py installs a Python command-line script orbis which probes the information_schema views (and a bit from system catalog tables) and generates a Markdown file per table, listing column details and descriptions, primary and foreign key columns, and relationships to and from other tables.

We then use Hugo to generate a static HTML site from this Markdown content. While Hugo itself must be installed as a prerequisite, a configuration file and Hugo Book theme are included.

Install and run locally

Installation

(Assuming macOS and homebrew)

• Clone this repo and cd into it: git clone https://github.com/nerium-data/orbis-tertius.git && cd orbis-tertius
• Create a python virtualenv and install with pip:

  python -m venv .venv
  source .venv/bin/activate
  pip install .

• Install Hugo with homebrew: brew install hugo

Usage

• Copy .env.sample to .env and edit the $DATABASE_URL and $SCHEMAS values to suit the desired documentation target database and schemas. $SCHEMAS defaults to public; you can specify multiple schema names separated by spaces (be sure to surround the whole list with double-quotes) -- see .env.sample for an example.
• Command orbis invokes script to generate the Markdown, which is saved in dictionary/content initially
• Hugo command to create HTML version of the data dictionary docs:

  hugo -s dictionary -d ../public --cleanDestinationDir --minify

Final Hugo output will be saved to public directory and can be served by any static site host.

Run with docker

• Clone repo and build the Docker image

  git clone https://github.com/nerium-data/orbis-tertius.git
  cd orbis-tertius
  docker build --rm -t orbis .

• Copy .env.sample to .env and edit the $DATABASE_URL and $SCHEMAS values to suit the desired documentation target database and schemas. $SCHEMAS defaults to public; you can specify multiple schema names separated by spaces -- see .env.sample for an example. [Note: be sure to remember that Docker is weird about quotation marks in env files]
• Run the built image, mounting the public volume to a local directory and passing .env file to the container environment

  docker run -it \
    -v $(pwd)/public:/public \
    --env-file=.env \
    orbis

Final Hugo output will be saved to public directory and can be served by any static site host. The raw Markdown output from orbis is included in public/markdown.

Alternative usage

I just wanted to point out that the inclusion of Hugo and the Hugo Book theme here are mainly for convenience/demonstration. Naturally, other themes could be used; if I had more supplementary content to include, I think the Doks theme is quite nice. Customization of any of these themes, or a fully custom theme would of course also be possible.

In fact, the raw Markdown files generated by orbis are suitable for use with any of a variety of static site generators, or import into another CMS, including Confluence, etc. One might also use wkhtmltopdf or Pandoc against them to generate documentation in PDF or other formats.

Orbis what now?

The project name is inspired by the fictional encyclopedia in Jorge Luis Borges's short story, "Tlön, Uqbar, Orbis Tertius".