metabase / metabase/metabase

Expose Liquibase application DB schema dox from a web server route

Open
#14,387 3 comments 0 reactions 0 assignees View on GitHub
.Backend .DX .Team/DevEx Difficulty:Medium good first issue Operation/ Priority:P2 Type:Tech Debt
Dominant language
Clojure
Stars
49.3k
Forks
6.8k
Avg merge
1d 13h
Merged PRs (30d)
653

Description

Liquibase can generate dox about everything in the application DB, e.g.

![image](https://user-images.githubusercontent.com/1455846/104530074-06237180-55c0-11eb-95cb-8577f67d6c39.png)

Command to do this from CLI (needed to replace `:dependencies: because Liquibase was refusing to use Log4j):

```
lein update-in : assoc :dependencies '^:replace [[org.clojure/clojure "1.10.1"] [org.liquibase/liquibase-core "3.5.5"] [org.postgresql/postgresql "42.2.8"]]' -- \
update-in : dissoc :aliases -- \
with-profile -run \
run -m liquibase.integration.commandline.Main \
--changeLogFile=resources/migrations/000_migrations.yaml \
--url='jdbc:postgresql://localhost:5432/metabase?user=cam&password=cam' \
dbDoc target/liquibase
```

We could definitely invoke the equivalent code directly from Clojure. I think we should add routes under `/_debug/schema` and then lazily trigger the Liquibase dox generation as needed when you visit those routes. Should be easy enough.

This would make it easy for us to poke at stuff and maybe to debug people's latest weird MySQL issues.

I think we should look at this more generally and create a `_dev` portal with other statically generated pages that will make Metabase dev a little easier.

Other things we can consider exposing in a similar way:

* The auto-generated API documentation could be exposed this way
* We could expose some utilities that make it easier to inspect the application state/app DB (potentially risky so I say we only do these for local development via `lein`)
* If people are using H2, we could expose the [H2 web console](http://h2database.com/html/quickstart.html) this way as well
* we could expose something like https://github.com/camsaul/lein-instant-cheatsheet as well so you can look up fn dox as you're working on the code.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the Liquibase CLI command and resources/migrations/000_migrations.yaml to understand the existing schema documentation output. Then locate the web routing entry point and determine the scope of the proposed /_debug/schema route, including whether it is limited to local development. Done means the agreed route can lazily generate and serve the application DB documentation safely.

Written by the indexing model from the issue text.

Assessment

Tech stack
clojure, postgresql
Domain
backend, database, devtools
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.