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.