Hi all,
In the near future, we will introduce 4 major concepts for DBML: Schema, Multi-line String, Note and Annotation. Here is the draft proposal of those concepts. Suggestions and ideas are welcome !
Overall Structure of DBML Element
https://dbdiagram.io/d/5de91a62edf08a25543ec0d6
Schema
Schema ecommerce {
Table users {
id int [pk]
name varchar
}
}
// or
Table ecommerce.users {
id int [pk]
name varchar
}
Two syntaxes to define schema:
- Define schema explicitly
Schema <schema-name> { ... }
- Implicitly define schema through table name
Table <schema-name>.<table-name>
From the time the schema concept is introduced, tables that don't have prefix schema name will belong to the default public
schema. Exporting DBML to SQL will not export the default public
schema syntax if in the DBML code the public
schema is not explicitly defined.
Table users { // public schema syntax will not export to SQL
id int [pk]
name varchar
}
// is the same as
Table public.users { // public schema syntax will export to SQL.
id int [pk]
name varchar
}
Multi-line String
2 types of format for multi-line string:
Block Style
Similar to YAML Block Scalar. https://yaml-multiline.info/.
In DBML, the block string will be indented with respect to the closing (right) bracket }
. Syntax could be like this:
Note ecommerce: >+{
This is schema note.
This note can span over
multiple lines.
}
-
Block Style Indicator: indicates how newlines inside the block should behave.
- literal
|
style: newlines are kept
- folded
>
style: newlines are replaces by spaces
-
Block Chomping Indicator: controls what should happen with newlines at the end of the string.
- clip: put a single newline at the end of the string
- strip
-
: remove all newlines at the end of the string
- keep
+
: keep all newlines at the end of the string
-
Indentation Indicator: number of spaces to indent a block with respect to the closing (right) bracket. This will be guessed automatically from its first line. Need to explicitly specify this indicator if first line starts with extra space. Minimum number of spaces for indentation: 1
Flow Style: single-quoted string
In DBML:
'Several lines of text,\n
containing ''single quotes''. Escapes (like \n) don''t do anything.\n
\n
Newlines can be added by leaving a blank line.\n
··Leading whitespace on lines is ignored.'\n
Result:
Several lines of text, containing 'single quotes'. Escapes (like \n) don't do anything.
Newlines can be added by leaving a blank line. Leading whitespace on lines is ignored.
Note
Two types of note: inline note (already supported for fields) and short-form note
Short-form note
Note <element-name>: <content>
Note ecommerce: 'Contains all tables belong to ecommerce schema'
Note ecommerce.users: 'Contains all user information'
Note ecommerce.users.id: 'Id of user'
// multiple-line string
Note ecommerce: >{
Contains all tables
belong to ecommerce schema
}
Inline note
Schema ecommerce [note: 'Contains all tables belong to ecommerce schema'] {
Table users [note: 'Contains all user information'] {
id int [pk, note: 'Id of user']
name varchar
}
}
Annotation
Annotations helps to associate metadata (information) to the DBML elements.
@<annotation-name> {
// syntax of each annotation is independent. For example, the syntax of
// dbdiagram annotation can be different from the syntax of dbdocs
// annotation
}
Example of dbdiagram annotation:
Table users {
id int [pk]
name varchar
}
@dbdiagram {
darkmode: on
Table users {
headercolor: #f3f2f9
position {
x: 181
y: 212
}
}
}
Annotation can be placed anywhere in our DBML code. If it is placed inside an element, it will provide metadata for that element.
Table users {
id int [pk]
name varchar
status user_status
@postgresql { // annotation for this table users; use for exporting this table to PostgreSQL
id: [serial]
Indexes {
name: [type: gist]
}
}
@mysql { // annotation for this table users; use for exporting this table to MySQL
id: [auto_increment]
storage_type: memory
Indexes {
name: [type: hash]
}
}
}
Avantages of annotation
- Annotation syntax is independent. Anyone, any team can define their own annotation syntax and write the annotation parser plugin to parse them.
- From the view of DBML, annotation can be treated like comment. It does not affect the structure or the meaning of the database
- Annotation is a way to separate between high level data model (table, schema) and SQL low level implementation (indexes, storage type...)
- One DBML file can contains many kinds of annotation without any problem. For example, one DBML table can be associated with two database annotations (mysql, postgres ... ) for exporting purpose without polluting the original DBML code
- From the technical view, DBML dialect with syntax mixed into original DBML code is hard to implement and maintain. For annotation, we just need to write another specific annotation parser plugin.
- The render system in dbdiagram and dbdocs can render diagrams/documents base on annotations as well.
- The possibilities is endless. Our DBML will be easier to extend without worry how the mix specific database syntax into the general code.