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)"

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)"

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
```

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