DEV Community

Cover image for YAML-based Database Docu
Christian Himpe
Christian Himpe

Posted on

YAML-based Database Docu

I recently came across the modest yasql standard to document database schemas of SQL databases, which I now use to document my rather involved ArcadeDB schema. My favorite yasql features are:

  • Very readable,
  • Rich metadata fields,
  • A definitions object for custom "macros".

Here is a small example of a yasql docu:

database:
  name: "My DB"
  source: "PostgreSQL"
  project: "My Project"
  version: 1.0
  license: "CC-BY"
  authors:
    - "Me"

definitions:
  tiny: 255

tables:
  myTable:
    myCol: "VARCHAR(tiny)"
Enter fullscreen mode Exit fullscreen mode

NoSQL

Generally, NoSQL databases do not use tables to organize data. For example, ArcadeDB - a multi-model DBMS - provides a document model and a graph model. Hence, instead of a tables object, I use documents, vertexes, and edges objects:

documents:
  myDoc:
    myStr: "STRING (mandatory, notnull, readonly)"

vertexes:
  myVtx:
    myNum: "LONG (default 0)"

edges:
  myEdg:
    myLst: "LIST (max 255)"
Enter fullscreen mode Exit fullscreen mode

Alternatives

There are (open) alternatives available which provide the benefit of visualization as entity-relationship diagram. So why not use ...

  • ... DBML ? Because:
    • Column settings have to be from a very limited vocabulary.
    • C-Style comments // and /* */.
    • Insufficients metadata fields (in the project object).
  • ... D2 sql_table ? Because:
    • Every table needs a shape: sql_table, meaning a column cannot be named shape?
    • The constraint keyword is superfluous since a constraint is already delimited by curly braces { }.
    • No metadata fields.

Visualization

You can visualize a yasql-file using PlantUML, which provides a YAML renderer. For instance, you can find the rendering of the yasql sample here

Practically, I embed a plantuml verbatim block wrapping the yasql YAML, in a Markdown document:

```plantuml
@startyaml

# your yasql goes here ...

@endyaml
```
Enter fullscreen mode Exit fullscreen mode

This way, using the VScode PlantUML Plugin I can get live visualizations of my schema.

Postmark Image

Speedy emails, satisfied customers

Are delayed transactional emails costing you user satisfaction? Postmark delivers your emails almost instantly, keeping your customers happy and connected.

Sign up

Top comments (0)

Sentry image

See why 4M developers consider Sentry, “not bad.”

Fixing code doesn’t have to be the worst part of your day. Learn how Sentry can help.

Learn more