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 namedshape
? - The
constraint
keyword is superfluous since a constraint is already delimited by curly braces{ }
. - No metadata fields.
- Every table needs a
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.
Top comments (0)