From fbbc7754140e5d7ce428db930294b4aff38b4835 Mon Sep 17 00:00:00 2001 From: Brandon Patram Date: Sun, 2 May 2021 00:53:36 -0400 Subject: [PATCH 01/17] formalize bootstraping diagram --- enriched.puml | 54 +++++++++++++++++------------------------ samples/examples.puml | 56 +++++++------------------------------------ 2 files changed, 30 insertions(+), 80 deletions(-) diff --git a/enriched.puml b/enriched.puml index ebbbc87..6a6c91b 100644 --- a/enriched.puml +++ b/enriched.puml @@ -3,8 +3,6 @@ ' === !$today = %date("yyyy-MM-dd") -!$confidential ?= %true() -!$hide_meta ?= %false() !$theme_data ?= { "textFont": "Helvetica", "codeFont": "Menlo", @@ -37,31 +35,24 @@ "borderThickness": 1.5 } -' !$title = "[Untitled] (set $title)" -' !$revision_name = "1" -' !$author_name = "Your Name" -' !$company_name = "Where you work" - -!procedure $add_std_header() +!procedure $add_header($author="", $revision="", $title="") !$header = "" - !if %variable_exists("$author_name") - !$header = $header + "Author: " + $author_name + "\n" + !if $author != "" + !$header = $header + "Author: " + $author + "\n" !endif - !if %variable_exists("$revision_name") && %variable_exists("$title") + !if $revision != "" && $title != "" !$header = $header + $title + " Rev. " + $revision_name + "\n" !endif - !$header = $header + "Rendered on " + $today - - !if %not($hide_meta) - header $header + !if $header != "" + header $header + "Rendered on " + $today !endif !endprocedure -!procedure $add_std_footer() +!procedure $add_footer($company="", $confidential="") !$footer = "" - !if %variable_exists("$company_name") - !$footer = $footer + $company_name + !if $company != "" + !$footer = $footer + $company !endif !if $confidential == %true() !if %strlen($footer) > 0 @@ -70,24 +61,18 @@ !$footer = $footer + "Confidential" !endif - !if %not($hide_meta) + !if $footer != "" + ' add linebreak for spacing footer \n$footer !endif !endprocedure -!procedure $add_std_title() - !if %not($hide_meta) && %variable_exists("$title") +!procedure $add_title($title="") + !if $title != "" title $title !endif !endprocedure -!procedure $add_std_info() - $add_std_header() - $add_std_footer() - $add_std_title() -!endprocedure - - ' === ' Styling/Layout Helpers ' === @@ -624,12 +609,17 @@ ' Library Macros/Procs ' === -!procedure $setup_std_diagram($style_name="generic") - !$diagram_style_proc_name = "$apply_" + $style_name + "_styles" - !assert %function_exists($diagram_style_proc_name) : "Could not apply styles for '" + $style_name + "'. Typo?" +!procedure Enrich($diagram="generic", $title="", $company="", $author="", $revision="", $confidential=%true()) + ' apply styles + !$diagram_style_proc_name = "$apply_" + $diagram + "_styles" + !assert %function_exists($diagram_style_proc_name) : "Unknown diagram type for '" + $diagram + "'." $apply_base_styles() %invoke_procedure($diagram_style_proc_name) - $add_std_info() + + ' add meta info + $add_header($author, $revision, $title) + $add_footer($company, $confidential) + $add_title($title) !endprocedure !define PK_TYPE INTEGER(11) diff --git a/samples/examples.puml b/samples/examples.puml index 7728e9f..7870395 100644 --- a/samples/examples.puml +++ b/samples/examples.puml @@ -4,12 +4,7 @@ @startuml example_activity !include_once ../enriched.puml - !$title = "Activity Diagram Styling" - !$company_name = "ACME Corp" - !$author_name = "John Smith" - !$revision_name = "2" - - $setup_std_diagram("activity") + Enrich("activity", $title="Activity Diagram Styling", $confidential=%false()) |Swimlane1| start @@ -34,12 +29,7 @@ @startuml example_sequence !include_once ../enriched.puml - !$title = "Sequence Diagram Styling" - !$company_name = "ACME Corp" - !$author_name = "John Smith" - !$revision_name = "2" - - $setup_std_diagram("sequence") + Enrich("sequence", $title="Sequence Diagram Styling", $confidential=%false()) participant participant as Foo actor actor as Foo1 @@ -84,12 +74,7 @@ @startuml example_state !include_once ../enriched.puml - !$title = "State Diagram Styling" - !$company_name = "ACME Corp" - !$author_name = "John Smith" - !$revision_name = "2" - - $setup_std_diagram("state") + Enrich("state", $title="State Diagram Styling", $confidential=%false()) state Todo<> { [*] --> Idle @@ -121,12 +106,7 @@ @startuml example_class !include_once ../enriched.puml - !$title = "Class Diagram Styling" - !$company_name = "ACME Corp" - !$author_name = "John Smith" - !$revision_name = "2" - - $setup_std_diagram("class") + Enrich("class", $title="Class Diagram Styling", $confidential=%false()) abstract class AbstractList abstract AbstractCollection @@ -168,12 +148,7 @@ @startuml example_er !include_once ../enriched.puml - !$title = "ER Diagram Styling" - !$company_name = "ACME Corp" - !$author_name = "John Smith" - !$revision_name = "2" - - $setup_std_diagram("er") + Enrich("er", $title="Entity Relationship Diagram Styling", $confidential=%false()) enum_mapping(REPORT_STATUS_ENUM, INT(11)) { enum_value(incomplete, 0) @@ -225,12 +200,7 @@ @startuml example_generic !include_once ../enriched.puml - !$title = "Generic Diagram Styling" - !$company_name = "ACME Corp" - !$author_name = "John Smith" - !$revision_name = "2" - - $setup_std_diagram() + Enrich($title="Generic Diagram Styling", $confidential=%false()) actor actor actor/ "actor/" @@ -278,12 +248,7 @@ @startuml example_usecase !include_once ../enriched.puml - !$title = "Generic Use Case Styling" - !$company_name = "ACME Corp" - !$author_name = "John Smith" - !$revision_name = "2" - - $setup_std_diagram("usecase") + Enrich("usecase", $title="Usecase Diagram Styling", $confidential=%false()) actor Guest as g package Professional { @@ -306,12 +271,7 @@ @startuml example_object !include_once ../enriched.puml - !$title = "Generic Object Styling" - !$company_name = "ACME Corp" - !$author_name = "John Smith" - !$revision_name = "2" - - $setup_std_diagram("object") + Enrich("object", $title="Object Diagram Styling", $confidential=%false()) package Package { From d0b43c925cc6371348c6b0c85f3a60b2b299fa4e Mon Sep 17 00:00:00 2001 From: Brandon Patram Date: Sun, 2 May 2021 01:09:45 -0400 Subject: [PATCH 02/17] update er pk type to use variable and procs --- enriched.puml | 25 +++++++++++++++++++++---- samples/examples.puml | 1 + 2 files changed, 22 insertions(+), 4 deletions(-) diff --git a/enriched.puml b/enriched.puml index 6a6c91b..cc082a3 100644 --- a/enriched.puml +++ b/enriched.puml @@ -622,7 +622,24 @@ $add_title($title) !endprocedure -!define PK_TYPE INTEGER(11) +' === +' ER Diagram Macros/Procs +' === + +!unquoted procedure USE_ID_TYPE($type) + !global $ID_TYPE = $type +!endprocedure + + +!procedure USE_UUIDS() + USE_ID_TYPE(UUID) +!endprocedure +!procedure USE_SEQ_IDS() + USE_ID_TYPE("INTEGER(11)") +!endprocedure + +' default to seq ids +USE_SEQ_IDS() !define table(name) entity name<> !define enum_mapping(name, type) enum name<> @@ -634,12 +651,12 @@ !define poly_can_be(from, to) from --|| to !define has_one_to_one(from, to) from ||--|| to !define has_many(from, to) from }--{ to -!define column_pk(name = "id") {field} {static}{method} # name: PK_TYPE +!define column_pk(name = "id") {field} {static}{method} # name: $ID_TYPE !define column_pk(name = "id", type) {static}{method} # name: type -!define column_fk(name) {method} + name: PK_TYPE +!define column_fk(name) {method} + name: $ID_TYPE !define column_fk(name, type) {method} + name: type !definelong column_fk_poly(name, type_type="VARCHAR", id_suffix = "_id", type_suffix = "_type") - {method} + name##id_suffix: PK_TYPE + {method} + name##id_suffix: $ID_TYPE {field} + name##type_suffix: type_type !enddefinelong !define column_non_nullable(name, type) {field} + name: type diff --git a/samples/examples.puml b/samples/examples.puml index 7870395..7033d2b 100644 --- a/samples/examples.puml +++ b/samples/examples.puml @@ -149,6 +149,7 @@ @startuml example_er !include_once ../enriched.puml Enrich("er", $title="Entity Relationship Diagram Styling", $confidential=%false()) + ' USE_UUIDS() enum_mapping(REPORT_STATUS_ENUM, INT(11)) { enum_value(incomplete, 0) From c4af055bd7f48790e3a069e11110ff8334006e91 Mon Sep 17 00:00:00 2001 From: Brandon Patram Date: Sun, 2 May 2021 01:35:19 -0400 Subject: [PATCH 03/17] rework setting db defaults --- enriched.puml | 25 +++++++++++++++---------- samples/examples.puml | 2 +- 2 files changed, 16 insertions(+), 11 deletions(-) diff --git a/enriched.puml b/enriched.puml index cc082a3..3d631b1 100644 --- a/enriched.puml +++ b/enriched.puml @@ -622,24 +622,29 @@ $add_title($title) !endprocedure + ' === ' ER Diagram Macros/Procs ' === -!unquoted procedure USE_ID_TYPE($type) - !global $ID_TYPE = $type +!procedure SET_SCHEMA_DEFAULTS($id_type="", $poly_type_type="", $poly_id_suffix="", $poly_type_suffix="") + !if $id_type != "" + !global $ID_TYPE = %upper($id_type) + !endif + !if $poly_type_type != "" + !global $POLY_TYPE_TYPE = %upper($poly_type_type) + !endif + !if $poly_id_suffix != "" + !global $POLY_ID_SUFFIX = %upper($poly_id_suffix) + !endif + !if $poly_type_suffix != "" + !global $POLY_TYPE_SUFFIX = %upper($poly_type_suffix) + !endif !endprocedure +SET_SCHEMA_DEFAULTS($id_type="INTEGER(11)", $poly_type_type="VARCHAR", $poly_id_suffix="_id", $poly_type_suffix="_type") -!procedure USE_UUIDS() - USE_ID_TYPE(UUID) -!endprocedure -!procedure USE_SEQ_IDS() - USE_ID_TYPE("INTEGER(11)") -!endprocedure -' default to seq ids -USE_SEQ_IDS() !define table(name) entity name<
> !define enum_mapping(name, type) enum name<> diff --git a/samples/examples.puml b/samples/examples.puml index 7033d2b..0834f11 100644 --- a/samples/examples.puml +++ b/samples/examples.puml @@ -149,7 +149,7 @@ @startuml example_er !include_once ../enriched.puml Enrich("er", $title="Entity Relationship Diagram Styling", $confidential=%false()) - ' USE_UUIDS() + SET_SCHEMA_DEFAULTS($id_type="UUID") enum_mapping(REPORT_STATUS_ENUM, INT(11)) { enum_value(incomplete, 0) From dd8e62b737d724eb19151f30ea5ae37801c1bf0d Mon Sep 17 00:00:00 2001 From: Brandon Patram Date: Sun, 2 May 2021 01:51:21 -0400 Subject: [PATCH 04/17] rework enums and tables to use procs --- enriched.puml | 17 ++++++++++++++--- samples/examples.puml | 12 ++++++------ 2 files changed, 20 insertions(+), 9 deletions(-) diff --git a/enriched.puml b/enriched.puml index 3d631b1..081f3c4 100644 --- a/enriched.puml +++ b/enriched.puml @@ -644,12 +644,23 @@ SET_SCHEMA_DEFAULTS($id_type="INTEGER(11)", $poly_type_type="VARCHAR", $poly_id_suffix="_id", $poly_type_suffix="_type") +!unquoted procedure Table($name) + Entity $name<
> +!endprocedure + +!unquoted procedure EnumType($name, $type) + Enum $name<$type><> +!endprocedure + +!unquoted procedure enum_value($name, $value) + {field} - $name: $value +!endprocedure +!unquoted procedure PolymorphicLink($name) + Abstract $name<> +!endprocedure) -!define table(name) entity name<
> -!define enum_mapping(name, type) enum name<> !define poly_assoc(name) abstract name -!define enum_value(name, value) {field} - name: value !define has_one(from, to) from }--|| to !define has_one_poly(from, to) from }-- to diff --git a/samples/examples.puml b/samples/examples.puml index 0834f11..669e612 100644 --- a/samples/examples.puml +++ b/samples/examples.puml @@ -151,14 +151,14 @@ Enrich("er", $title="Entity Relationship Diagram Styling", $confidential=%false()) SET_SCHEMA_DEFAULTS($id_type="UUID") - enum_mapping(REPORT_STATUS_ENUM, INT(11)) { + EnumType(REPORT_STATUS_ENUM, "INT(11)") { enum_value(incomplete, 0) enum_value(complete, 1) enum_value(not_applicable, 2) } - frame Items { - table(items_progress_report_caches) { + Frame Items { + Table(items_progress_report_caches) { --- column_pk() timestamps() @@ -167,7 +167,7 @@ column_non_nullable(photo_editing_work, REPORT_STATUS_ENUM) } - table(items) { + Table(items) { --- column_pk() omitted_columns() @@ -177,12 +177,12 @@ poly_assoc(ownable) - table(users) { + Table(users) { --- column_pk() } - table(organizations) { + Table(organizations) { --- column_pk() } From 22afd114e51ab9bdecdea27b760a2aaa246db999 Mon Sep 17 00:00:00 2001 From: Brandon Patram Date: Sun, 2 May 2021 02:04:27 -0400 Subject: [PATCH 05/17] add default pk col name as schema default --- enriched.puml | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/enriched.puml b/enriched.puml index 081f3c4..b332c12 100644 --- a/enriched.puml +++ b/enriched.puml @@ -627,7 +627,10 @@ ' ER Diagram Macros/Procs ' === -!procedure SET_SCHEMA_DEFAULTS($id_type="", $poly_type_type="", $poly_id_suffix="", $poly_type_suffix="") +!procedure SET_SCHEMA_DEFAULTS($id_name="", $id_type="", $poly_type_type="", $poly_id_suffix="", $poly_type_suffix="") + !if $id_name != "" + !global $ID_NAME = $id_name + !endif !if $id_type != "" !global $ID_TYPE = %upper($id_type) !endif @@ -642,7 +645,7 @@ !endif !endprocedure -SET_SCHEMA_DEFAULTS($id_type="INTEGER(11)", $poly_type_type="VARCHAR", $poly_id_suffix="_id", $poly_type_suffix="_type") +SET_SCHEMA_DEFAULTS($id_name="id", $id_type="INTEGER(11)", $poly_type_type="VARCHAR", $poly_id_suffix="_id", $poly_type_suffix="_type") !unquoted procedure Table($name) Entity $name<
> From bfaf35490d44465d2eb10b8bb99c4445c9aecbfe Mon Sep 17 00:00:00 2001 From: Brandon Patram Date: Sun, 2 May 2021 02:14:35 -0400 Subject: [PATCH 06/17] add partial tables --- enriched.puml | 8 ++++++++ samples/examples.puml | 13 ++----------- 2 files changed, 10 insertions(+), 11 deletions(-) diff --git a/enriched.puml b/enriched.puml index b332c12..0c796c0 100644 --- a/enriched.puml +++ b/enriched.puml @@ -651,6 +651,14 @@ SET_SCHEMA_DEFAULTS($id_name="id", $id_type="INTEGER(11)", $poly_type_type="VARC Entity $name<
> !endprocedure +!unquoted procedure PartialTable($name) + Table($name)<> { + --- + table_pk() + omitted_columns() + } +!endprocedure + !unquoted procedure EnumType($name, $type) Enum $name<$type><> !endprocedure diff --git a/samples/examples.puml b/samples/examples.puml index 669e612..7814edd 100644 --- a/samples/examples.puml +++ b/samples/examples.puml @@ -177,17 +177,8 @@ poly_assoc(ownable) - Table(users) { - --- - column_pk() - } - - Table(organizations) { - --- - column_pk() - } - - + PartialTable(users) + PartialTable(organizations) has_one(items_progress_report_caches, items) has_one_poly(items, ownable) From 2128240493b9af69b19675d4f4e8e00044139fa1 Mon Sep 17 00:00:00 2001 From: Brandon Patram Date: Sun, 2 May 2021 02:25:28 -0400 Subject: [PATCH 07/17] update table column procs --- enriched.puml | 50 +++++++++++++++++++++++++++++++++---------- samples/examples.puml | 12 +++++------ 2 files changed, 45 insertions(+), 17 deletions(-) diff --git a/enriched.puml b/enriched.puml index 0c796c0..726b548 100644 --- a/enriched.puml +++ b/enriched.puml @@ -659,6 +659,45 @@ SET_SCHEMA_DEFAULTS($id_name="id", $id_type="INTEGER(11)", $poly_type_type="VARC } !endprocedure +!unquoted procedure table_column($name, $type, $nullable=%true()) + !if $nullable == %false() + !$type = $type + " NOT NULL" + !endif + {field} + $name: $type +!endprocedure + +!unquoted procedure table_pk($name="", $type="") + !if $type == "" + !$type = $ID_TYPE + !endif + !if $name == "" + !$name = $ID_NAME + !endif + {method} # $name: $type NOT NULL +!endprocedure + +!unquoted procedure table_fk($name, $type="", $nullable=%false()) + !if $type == "" + !$type = $ID_TYPE + !endif + !if $nullable == %false() + !$type = $type + " NOT NULL" + !endif + {method} + $name: $type +!endprocedure + +!unquoted procedure table_timestamps($created=%true(), $updated=%true(), $destroyed=%false()) + !if $created == %true() + table_column(created_at, DATETIME, $nullable=0) + !endif + !if $updated == %true() + table_column(updated_at, DATETIME, $nullable=0) + !endif + !if $destroyed == %true() + table_column(destroyed_at, DATETIME) + !endif +!endprocedure + !unquoted procedure EnumType($name, $type) Enum $name<$type><> !endprocedure @@ -678,19 +717,8 @@ SET_SCHEMA_DEFAULTS($id_name="id", $id_type="INTEGER(11)", $poly_type_type="VARC !define poly_can_be(from, to) from --|| to !define has_one_to_one(from, to) from ||--|| to !define has_many(from, to) from }--{ to -!define column_pk(name = "id") {field} {static}{method} # name: $ID_TYPE -!define column_pk(name = "id", type) {static}{method} # name: type -!define column_fk(name) {method} + name: $ID_TYPE -!define column_fk(name, type) {method} + name: type !definelong column_fk_poly(name, type_type="VARCHAR", id_suffix = "_id", type_suffix = "_type") {method} + name##id_suffix: $ID_TYPE {field} + name##type_suffix: type_type !enddefinelong -!define column_non_nullable(name, type) {field} + name: type -!define column_nullable(name, type) {field} + name: type !define omitted_columns(name = "...") //name// - -!definelong timestamps() - column_non_nullable(created_at, DATETIME) - column_non_nullable(updated_at, DATETIME) -!enddefinelong diff --git a/samples/examples.puml b/samples/examples.puml index 7814edd..5f2986e 100644 --- a/samples/examples.puml +++ b/samples/examples.puml @@ -160,16 +160,16 @@ Frame Items { Table(items_progress_report_caches) { --- - column_pk() - timestamps() - column_fk(item_id) - column_non_nullable(photos_uploaded, REPORT_STATUS_ENUM) - column_non_nullable(photo_editing_work, REPORT_STATUS_ENUM) + table_pk() + table_timestamps($destroyed=1) + table_fk(item_id) + table_column(photos_uploaded, REPORT_STATUS_ENUM, $nullable=0) + table_column(photo_editing_work, REPORT_STATUS_ENUM, $nullable) } Table(items) { --- - column_pk() + table_pk() omitted_columns() column_fk_poly(ownable) } From f5e2d67186d07d98ceab9d3f61f9b18915417824 Mon Sep 17 00:00:00 2001 From: Brandon Patram Date: Sun, 2 May 2021 02:29:24 -0400 Subject: [PATCH 08/17] unify poly assoc and rel procs --- enriched.puml | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/enriched.puml b/enriched.puml index 726b548..91375f8 100644 --- a/enriched.puml +++ b/enriched.puml @@ -710,10 +710,13 @@ SET_SCHEMA_DEFAULTS($id_name="id", $id_type="INTEGER(11)", $poly_type_type="VARC Abstract $name<> !endprocedure) -!define poly_assoc(name) abstract name +!unquoted procedure has_one_poly($from, $as) + PolymorphicLink($as) + + $from }-- $as +!endprocedure !define has_one(from, to) from }--|| to -!define has_one_poly(from, to) from }-- to !define poly_can_be(from, to) from --|| to !define has_one_to_one(from, to) from ||--|| to !define has_many(from, to) from }--{ to From 5dd617c71e390f3966a71b95230794fe9ccd7ccc Mon Sep 17 00:00:00 2001 From: Brandon Patram Date: Sun, 2 May 2021 02:40:06 -0400 Subject: [PATCH 09/17] update omitted cols proc --- enriched.puml | 10 ++++++++-- samples/examples.puml | 2 +- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/enriched.puml b/enriched.puml index 91375f8..625a66e 100644 --- a/enriched.puml +++ b/enriched.puml @@ -655,7 +655,8 @@ SET_SCHEMA_DEFAULTS($id_name="id", $id_type="INTEGER(11)", $poly_type_type="VARC Table($name)<> { --- table_pk() - omitted_columns() + .. + omitted columns } !endprocedure @@ -716,6 +717,12 @@ SET_SCHEMA_DEFAULTS($id_name="id", $id_type="INTEGER(11)", $poly_type_type="VARC $from }-- $as !endprocedure +!procedure table_omission() +.. +omitted columns +.. +!endprocedure + !define has_one(from, to) from }--|| to !define poly_can_be(from, to) from --|| to !define has_one_to_one(from, to) from ||--|| to @@ -724,4 +731,3 @@ SET_SCHEMA_DEFAULTS($id_name="id", $id_type="INTEGER(11)", $poly_type_type="VARC {method} + name##id_suffix: $ID_TYPE {field} + name##type_suffix: type_type !enddefinelong -!define omitted_columns(name = "...") //name// diff --git a/samples/examples.puml b/samples/examples.puml index 5f2986e..2275688 100644 --- a/samples/examples.puml +++ b/samples/examples.puml @@ -170,7 +170,7 @@ Table(items) { --- table_pk() - omitted_columns() + table_omission() column_fk_poly(ownable) } } From a60f0da2765bb7e2493a7ab987ad820e47d267b3 Mon Sep 17 00:00:00 2001 From: Brandon Patram Date: Sun, 2 May 2021 02:40:21 -0400 Subject: [PATCH 10/17] fix example --- samples/examples.puml | 2 -- 1 file changed, 2 deletions(-) diff --git a/samples/examples.puml b/samples/examples.puml index 2275688..2583a9c 100644 --- a/samples/examples.puml +++ b/samples/examples.puml @@ -175,8 +175,6 @@ } } - poly_assoc(ownable) - PartialTable(users) PartialTable(organizations) From b72f985e1cad98493d83f243f851fd27b0fbe7aa Mon Sep 17 00:00:00 2001 From: Brandon Patram Date: Sun, 2 May 2021 03:01:30 -0400 Subject: [PATCH 11/17] remove enforced casing in schema defs --- enriched.puml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/enriched.puml b/enriched.puml index 625a66e..5dbdbba 100644 --- a/enriched.puml +++ b/enriched.puml @@ -632,16 +632,16 @@ !global $ID_NAME = $id_name !endif !if $id_type != "" - !global $ID_TYPE = %upper($id_type) + !global $ID_TYPE = $id_type !endif !if $poly_type_type != "" - !global $POLY_TYPE_TYPE = %upper($poly_type_type) + !global $POLY_TYPE_TYPE = $poly_type_type !endif !if $poly_id_suffix != "" - !global $POLY_ID_SUFFIX = %upper($poly_id_suffix) + !global $POLY_ID_SUFFIX = $poly_id_suffix !endif !if $poly_type_suffix != "" - !global $POLY_TYPE_SUFFIX = %upper($poly_type_suffix) + !global $POLY_TYPE_SUFFIX = $poly_type_suffix !endif !endprocedure From 3a6538ebc48535f1291f84453d5525b2ab270c3e Mon Sep 17 00:00:00 2001 From: Brandon Patram Date: Sun, 2 May 2021 03:01:52 -0400 Subject: [PATCH 12/17] table rel defs to procs --- enriched.puml | 40 ++++++++++++++++++++++++++++++++-------- samples/examples.puml | 4 ++-- 2 files changed, 34 insertions(+), 10 deletions(-) diff --git a/enriched.puml b/enriched.puml index 5dbdbba..0660c64 100644 --- a/enriched.puml +++ b/enriched.puml @@ -687,6 +687,23 @@ SET_SCHEMA_DEFAULTS($id_name="id", $id_type="INTEGER(11)", $poly_type_type="VARC {method} + $name: $type !endprocedure +!unquoted procedure table_poly_fk($as, $type_type="", $id_type="", $id_suffix="", $type_suffix="", $nullable=%false()) + !if $id_type == "" + !$id_type = $ID_TYPE + !endif + !if $type_type == "" + !$type_type = $POLY_TYPE_TYPE + !endif + !if $id_suffix == "" + !$id_suffix = $POLY_ID_SUFFIX + !endif + !if $type_suffix == "" + !$type_suffix = $POLY_TYPE_SUFFIX + !endif + table_fk($as##$id_suffix, $id_type, $nullable=$nullable) + table_column($as##$type_suffix, $type_type, $nullable=$nullable) +!endprocedure + !unquoted procedure table_timestamps($created=%true(), $updated=%true(), $destroyed=%false()) !if $created == %true() table_column(created_at, DATETIME, $nullable=0) @@ -723,11 +740,18 @@ SET_SCHEMA_DEFAULTS($id_name="id", $id_type="INTEGER(11)", $poly_type_type="VARC .. !endprocedure -!define has_one(from, to) from }--|| to -!define poly_can_be(from, to) from --|| to -!define has_one_to_one(from, to) from ||--|| to -!define has_many(from, to) from }--{ to -!definelong column_fk_poly(name, type_type="VARCHAR", id_suffix = "_id", type_suffix = "_type") - {method} + name##id_suffix: $ID_TYPE - {field} + name##type_suffix: type_type -!enddefinelong +!unquoted procedure has_one($from, $to) + $from }--|| $to +!endprocedure + +!unquoted procedure has_many($from, $to) + $from }--{ $to +!endprocedure + +!unquoted procedure has_one_to_one($from, $to) + $from ||--|| $to +!endprocedure + +!unquoted procedure poly_can_be($as, $to) + $as --|| $to +!endprocedure diff --git a/samples/examples.puml b/samples/examples.puml index 2583a9c..bc54c6e 100644 --- a/samples/examples.puml +++ b/samples/examples.puml @@ -164,14 +164,14 @@ table_timestamps($destroyed=1) table_fk(item_id) table_column(photos_uploaded, REPORT_STATUS_ENUM, $nullable=0) - table_column(photo_editing_work, REPORT_STATUS_ENUM, $nullable) + table_column(photo_editing_work, REPORT_STATUS_ENUM) } Table(items) { --- table_pk() table_omission() - column_fk_poly(ownable) + table_poly_fk(ownable, $nullable=1) } } From c663e469d51ab0f087e033e95d62584887bb4d69 Mon Sep 17 00:00:00 2001 From: Brandon Patram Date: Sun, 2 May 2021 03:10:35 -0400 Subject: [PATCH 13/17] add table layer element --- enriched.puml | 7 +++++++ samples/examples.puml | 8 +++++--- 2 files changed, 12 insertions(+), 3 deletions(-) diff --git a/enriched.puml b/enriched.puml index 0660c64..4abc46a 100644 --- a/enriched.puml +++ b/enriched.puml @@ -647,6 +647,13 @@ SET_SCHEMA_DEFAULTS($id_name="id", $id_type="INTEGER(11)", $poly_type_type="VARCHAR", $poly_id_suffix="_id", $poly_type_suffix="_type") +!procedure TableLayer($name, $color="") + !if $color != "" + !$color = "#back:" + $color + !endif + Frame $name <> $color +!endprocedure + !unquoted procedure Table($name) Entity $name<
> !endprocedure diff --git a/samples/examples.puml b/samples/examples.puml index bc54c6e..0c42f1c 100644 --- a/samples/examples.puml +++ b/samples/examples.puml @@ -157,7 +157,7 @@ enum_value(not_applicable, 2) } - Frame Items { + TableLayer("Items", $color="lightblue") { Table(items_progress_report_caches) { --- table_pk() @@ -175,8 +175,10 @@ } } - PartialTable(users) - PartialTable(organizations) + TableLayer("Identity") { + PartialTable(users) + PartialTable(organizations) + } has_one(items_progress_report_caches, items) has_one_poly(items, ownable) From 4f1b16248a7c57b68faefe21ecaccfbe936e4b01 Mon Sep 17 00:00:00 2001 From: Brandon Patram Date: Tue, 4 May 2021 12:18:46 -0400 Subject: [PATCH 14/17] update docs for bootstrapping --- README.md | 56 ++++++++++++++++++++++++++----------------------------- 1 file changed, 26 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index cf44003..85a1dfe 100644 --- a/README.md +++ b/README.md @@ -12,33 +12,28 @@ Features: ## Getting Started -At the top of your PlantUML file, you need to include `enriched.puml`. By default, nothing will immediately happen to your diagram, you must opt-in to applying individual features. To easily bootstrap a new diagram to apply the correct styles and insert document information, copyright, and confidentiality notices you can call `$setup_std_diagram("")`. The beginning of your diagram should look something like this: +At the top of your PlantUML file, you need to include `enriched.puml`. By default, nothing will immediately happen to your diagram, you must opt-in to applying individual features. To easily bootstrap a new diagram to apply the correct styles and insert document information, copyright, and confidentiality notices you can call `Enrich("")`. The beginning of your diagram should look something like this: ```puml !include_once https://raw.githubusercontent.com/bpatram/enriched-plantuml/master/enriched.puml -!$title = "My Diagram" -!$company_name = "ACME Corp" -!$author_name = "John Smith" -!$revision_name = "1" - -$setup_std_diagram("") +Enrich("", $title = "My Diagram") ``` ### Styling -When calling `$setup_std_diagram` you must pass in a diagram type name as the first argument in order to apply the correct styles for that diagram type. The current possible diagram types you can style are: +When calling `Enrich` you should pass in a diagram type name as the first argument in order to apply the correct styles for that diagram type. The current possible diagram types you can style are: -- `$setup_std_diagram("sequence")` -- `$setup_std_diagram("activity")` -- `$setup_std_diagram("state")` -- `$setup_std_diagram("class")` -- `$setup_std_diagram("usecase")` -- `$setup_std_diagram("object")` -- `$setup_std_diagram("deployment")` -- `$setup_std_diagram("er")` -- `$setup_std_diagram("generic")` -- `$setup_std_diagram()` (same as `$setup_std_diagram("generic")`) +- `"sequence"` +- `"activity"` +- `"state"` +- `"class"` +- `"usecase"` +- `"object"` +- `"deployment"` +- `"er"` +- `"generic"` +- Leaving it blank will only apply basic styling, not specific to any specific diagram type ### Formatting helpers @@ -47,27 +42,28 @@ When calling `$setup_std_diagram` you must pass in a diagram type name as the fi ### Inserting title blocks -When calling `$setup_std_diagram` it will attempt to insert a title block for you. You must define these variables _before_ making that call for it to work correctly. +Currently, title blocks are formatted as a header that appears in the top right of your diagram. This information will only be shown if you define certain variables when calling `Enrich`. -You'll want to define the following: +Here is a list of variables you can define when calling Enrich that relate to the title block: -- `!$author_name = "Your Name"` -- `!$revision_name = "Rev. 1"` (optional) +- `$author = "Your Name"` (optional) +- `$revision = "Rev. 1"` (optional) -### Inserting copyright and confidentiality notices +```puml +Enrich("", $author = "Your Name", $revision = "1") +``` -When calling `$setup_std_diagram` it will attempt to insert a footer with company information and to identify if your diagram is confidential or not. When you define these variables it must be done _before_ making the call to `$setup_std_diagram`. +### Inserting copyright and confidentiality notices -You can insert the name of your company or employer by defining the $company_name variable: +Currently, copyright and confidentiality notices are formatted as a footer that appears in the bottom center of your diagram. By default, all diagrams are treated as confidential. You can define a company name and/or override the default behavior by defining some additional variables when calling `Enrich`. -```puml -!$company_name = "Your Company" -``` +Here is a list of variables you can define when calling Enrich that relate to copyright/confidentiality: -By default, all diagrams are marked as confidential. To mark your diagram as not confidential: +- `$company = "Your Employer"` (optional) +- `$confidential = 0` (optional) ```puml -!$confidential = %false() +Enrich("", $company = "My Company", $confidential = 0) ``` ### Entity-relationship diagrams From 0ceafac38b36dc7beb83ff37d898f6ba008a33f8 Mon Sep 17 00:00:00 2001 From: Brandon Patram Date: Tue, 4 May 2021 12:43:47 -0400 Subject: [PATCH 15/17] update docs for erd --- README.md | 148 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 93 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index 85a1dfe..b201823 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,9 @@ Features: ## Getting Started -At the top of your PlantUML file, you need to include `enriched.puml`. By default, nothing will immediately happen to your diagram, you must opt-in to applying individual features. To easily bootstrap a new diagram to apply the correct styles and insert document information, copyright, and confidentiality notices you can call `Enrich("")`. The beginning of your diagram should look something like this: +At the top of your PlantUML file, you need to include `enriched.puml`. By default, nothing will immediately happen to your diagram, you must opt-in to applying individual features. To do so, you can easily bootstrap a new diagram by calling `Enrich("")`. + +The beginning of your diagram should look something like this: ```puml !include_once https://raw.githubusercontent.com/bpatram/enriched-plantuml/master/enriched.puml @@ -22,7 +24,7 @@ Enrich("", $title = "My Diagram") ### Styling -When calling `Enrich` you should pass in a diagram type name as the first argument in order to apply the correct styles for that diagram type. The current possible diagram types you can style are: +When calling `Enrich` you should pass in a diagram type as the first argument in order to apply the correct styles for that diagram type. The current possible diagram types you can style are: - `"sequence"` - `"activity"` @@ -33,7 +35,7 @@ When calling `Enrich` you should pass in a diagram type name as the first argume - `"deployment"` - `"er"` - `"generic"` -- Leaving it blank will only apply basic styling, not specific to any specific diagram type +- Leaving it blank will only apply basic styling, not specific to any diagram type ### Formatting helpers @@ -42,9 +44,9 @@ When calling `Enrich` you should pass in a diagram type name as the first argume ### Inserting title blocks -Currently, title blocks are formatted as a header that appears in the top right of your diagram. This information will only be shown if you define certain variables when calling `Enrich`. +Currently, title blocks are formatted as a header that appears in the top right of your diagram. This information will only be shown if you define certain arguments when calling `Enrich`. -Here is a list of variables you can define when calling Enrich that relate to the title block: +Here is a list of named arguments you can define when calling Enrich that relate to the title block: - `$author = "Your Name"` (optional) - `$revision = "Rev. 1"` (optional) @@ -55,9 +57,9 @@ Enrich("", $author = "Your Name", $revision = "1") ### Inserting copyright and confidentiality notices -Currently, copyright and confidentiality notices are formatted as a footer that appears in the bottom center of your diagram. By default, all diagrams are treated as confidential. You can define a company name and/or override the default behavior by defining some additional variables when calling `Enrich`. +Currently, copyright and confidentiality notices are formatted as a footer that appears in the bottom center of your diagram. By default, all diagrams are treated as confidential. You can define a company name and/or override the default behavior with some additional arguments passed when calling `Enrich`. -Here is a list of variables you can define when calling Enrich that relate to copyright/confidentiality: +Here is a list of named arguments you can define when calling Enrich that relate to copyright/confidentiality: - `$company = "Your Employer"` (optional) - `$confidential = 0` (optional) @@ -68,63 +70,110 @@ Enrich("", $company = "My Company", $confidential = 0) ### Entity-relationship diagrams -When building ER diagrams you'll want to make sure your diagram type is `"er"` when calling `$setup_std_diagram` to ensure styles are applied correctly. +When building ER diagrams you'll want to make sure your diagram type is `"er"` when calling `Enrich` to ensure styles are applied correctly. -#### Tables +#### Assumptions/defaults + +There are some assumptions made by this library when generating ER diagrams. These defaults can be overridden but have been optimized for diagraming databases created using ActiveRecord (a popular ORM for Ruby on Rails applications). You can call `SET_SCHEMA_DEFAULTS` with the following named arguments to override them. + +Below is a list of the named arguments you can pass along with the current defaults used: -To define a new table, use the `table` object. To set the table name pass it in as the first argument. Within your tables you can use additional macros to define the columns or fields on your table. +- `$id_name = "id"`: Default PK column name when calling `table_pk()`. +- `$id_type = "INTEGER(11)"`: Default PK/FK datatype when creating PK/FK columns. +- `$poly_type_type = "VARCHAR"`: Default datatype for polymorphic "type" columns. +- `$poly_id_suffix = "_id"`: Default text to append to the polymorphic name when creating FK column. +- `$poly_type_suffix = "_type"`: Default text to append to the polymorphic name when creating type column. + +Below is a simple example of changing the default to use a "UUID" datatype instead of sequential IDs for PK/FKs: ```puml -table(your_table_name) { - --- - ' define your fields... -} +SET_SCHEMA_DEFAULTS($id_type="UUID") ``` -#### Fields +#### Tables -In most databases the identifier or reference columns use the same datatype across all tables. By default primary and foreign keys are assumed to be an INTEGER(11) datatype, however you can change this behavior by overwriting `PK_TYPE` value to something else. If you use UUIDs for example you will want to do something like this: +To define a new table, use the `Table` element. To set the table name pass it in as the first argument. Within your table you can use additional macros to define the columns your table and to associate tables together (read on). ```puml -!define PK_TYPE UUID +Table(your_table_name) { + --- + ' define your fields here... +} ``` -Define a primary key field within your table using `column_pk()`. By default the field will be called 'id' but you can override this behavior by passing in a new name as the first argument. If its datatype differs from `PK_TYPE` (`INTEGER(11)` by default) you can define a new datatype by passing a second argument. +#### Primary keys + +Define a primary key field within your table using `table_pk()`. By default the field will be called 'id' with a datatype of 'INTEGER(11)' but you can override this behavior by passing in arguments or by changing the schema defaults via `SET_SCHEMA_DEFAULTS` ```puml -' to create a PK named 'id' -column_pk() +' to create a PK named 'id' (based on schema defaults) +table_pk() ' or with a custom field name -column_pk('identifier') +table_pk('identifier') ' or with a custom datatype -column_pk('id', 'UUID') +table_pk('id', 'UUID') ``` -Define a foreign key field within your table using `column_fk()`. You'll need to define the column name by passing in a name as the first argument. If its datatype differs from `PK_TYPE` (`INTEGER(11)` by default) you can define a new datatype by passing a second argument. +#### Foreign keys + +Define a foreign key field within your table using `table_fk()`. You'll need to define the column name by passing in a name as the first argument. By default the datatype will be 'INTEGER(11)' but you can override this behavior by passing in a second argument or by changing the schema defaults via `SET_SCHEMA_DEFAULTS`. By default, FK columns are non-nullable, you can override this behavior by passing in a `$nullable` named argument and setting it to true. ```puml ' to create a FK named 'other_table_id' -column_fk(other_table_id) +table_fk(other_table_id) ' or with a custom datatype -column_fk(other_table_id, 'UUID') +table_fk(other_table_id, 'UUID') + +' or if it is nullable +table_fk(other_table_id, $nullable=1) ``` -Define an ordinary field with either `column_non_nullable()` or `column_nullable()`. The first argument sets the column name and the second argument set its datatype. +#### Table columns + +Define an ordinary field with `table_column()`. The first argument sets the column name and the second argument set its datatype. You can pass additional data, like if it is nullable or not using named arguments. By default columns are nullable, you can override this by passing in a `$nullable` named argument and setting it to true. ```puml +' to create a nullable field (default behavior) +table_column(column_name, 'DATETIME') + ' to create a non-nullable field -column_non_nullable(column_name, 'DATETIME') +table_column(column_name, 'DATETIME', $nullable=0) +``` -' to create a nullable field -column_nullable(column_name, 'DATETIME') +#### Timestamp columns + +In most applications it is common to include some additional fields on your table to store "created_at" and "updated_at" timestamps (and sometimes "destroyed_at"). Instead of having to declare these fields on your table separately via `table_column()`, you can instead use `table_timestamps()`. You can configure which timestamp columns to add via named arguments. + +```puml +' to add 'created_at' and 'updated_at' timestamp columns (default behavior) +table_timestamps() + +' to add 'destroyed_at' timestamp column (in addition to created_at and updated_at) +table_timestamps($destroyed_at=1) + +' to add only a 'created_at' timestamp column +table_timestamps($updated_at=0) ``` -When making diagrams which only highlights a specific area of concern of your schema you may want to only need to partially define your tables. There is a handy macro, `omitted_columns()` to indicate that you are omitting some fields on your table. +#### Partial Tables -In most applications it is common to include some additional fields on your table to store "created_at" and "updated_at" timestamps. Instead of having to declare these fields on your table separately, you can instead simply use the `timestamps()` macro. +Often times you will find yourself only needing to diagram a single area of concern in your schema and not the entire schema. In this case there are some handy helpers provided. In the scenario where you just need to reference a table and handwave over its entire shape, you can use the `PartialTable` element. If you are diagraming out a table but want to handwave over irrelevant columns you can use `table_omission()`. + +``` +' creates a table with just a PK and 'omitted columns' +PartialTable(users) + +' or to create a table with a mix of omitted and defined columns +Table(users) { + table_pk() + table_timestamps() + table_omission() + table_fk(foo_id) +} +``` #### Relationships @@ -132,15 +181,15 @@ To define a many to one relationship use `has_one()`. To define a many to many relationship use `has_many()`. ```puml -table(books) { +Table(books) { --- - column_pk() - column_fk(author_id) + table_pk() + table_fk(author_id) } -table(authors) { +Table(authors) { --- - column_pk() + table_pk() } has_one(books, authors) @@ -150,31 +199,20 @@ has_one(books, authors) Polymorphic relationships are a non-standard concept when talking about modeling a data schema. However, most ORMs support this type of relationship so modeling them in your ER diagrams is a common challenge. Since a polymorphic relationship represents a relationship to differing tables we can represent the polymorphic relationship as an intermediate object between the table containing the foreign key and the tables that it could possibly be referencing. Below is a complete example to show how this works in practice. -Define a polymorphic foreign key and foreign key type fields on your table via `column_fk_poly()`. Define your polymorphic relationship intermediate object via `poly_assoc()`. +Define a polymorphic foreign key and foreign key type fields on your table via `table_poly_fk()`. Relate your table with the polymorphic fields to the intermediate object via `has_one_poly()`. Define the tables that your polymorphic relationship could reference via `poly_can_be()`. ```puml -table(items) { +Table(items) { --- - column_pk() + table_pk() - column_fk_poly(ownable) + table_fk_poly(ownable) } -poly_assoc(ownable) - -table(users) { - --- - column_pk() - omitted_columns() -} - -table(companies) { - --- - column_pk() - omitted_columns() -} +PartialTable(users) +PartialTable(companies) has_one_poly(items, ownable) poly_can_be(ownable, users) @@ -184,12 +222,12 @@ poly_can_be(ownable, companies) #### Enums -To represent enums in your schema, you can define an `enum_mapping` object. Pass in the enum name and its datatype as the first and second arguments. It appears similar to a table in your diagram but will be styled a bit differently and will contain the values of your enum. +To represent enums in your schema, you can define an `EnumType` element. Pass in the enum name and its datatype as the first and second arguments. It appears similar to a table in your diagram but will be styled a bit differently and will contain the values of your enum. To define your enum values use `enum_value()` and pass the name and value as the first and second arguments. ```puml -enum_mapping(MY_ENUM_NAME, INTEGER) { +EnumType(MY_ENUM_NAME, "INT(11")) { enum_value(my_value_one, 1) enum_value(my_value_two, 2) } From 011153b54f665233f95380e32149040a32db371e Mon Sep 17 00:00:00 2001 From: Brandon Patram Date: Tue, 4 May 2021 13:04:53 -0400 Subject: [PATCH 16/17] update changelog --- CHANGELOG.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index f64c3d5..5519914 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [Unreleased, 3.0.0] + +### Added + +- `PartialTable` element type for quickly defining a Table with omitted columns and a PK +- `TableLayer` element for grouping tables together +- Control which timestamp table columns are added when calling `table_timestamps()` +- Support for "destroyed_at" timestamp table column +- Setting and presenting table column nullability as a data type + +### Changed + +- `$setup_std_diagram` renamed to `Enrich` +- Define diagram info via names arguments to `Enrich` instead of global variables +- `PK_TYPE` replaced by calling `SET_SCHEMA_DEFAULTS` with named argument `$id_type` +- `table` element renamed to `Table` (case-sensitive) +- `enum_mapping` element renamed to `EnumType` (case-sensitive) +- `poly_assoc` merged into `has_one_poly` +- `timestamps` renamed to `table_timestamps` +- `omitted_columns` renamed to `table_omission` +- `column_fk_poly` renamed to `table_poly_fk` +- Omitted columns on tables is more clear +- Table foreign keys and polymorphic columns are non-nullable by default + ## [2.5.0] - 2021-04-29 ### Added From 4eb24d895f7fa5bd776a773eb4fdb94e5252762d Mon Sep 17 00:00:00 2001 From: Brandon Patram Date: Tue, 4 May 2021 13:07:03 -0400 Subject: [PATCH 17/17] reformat readme --- README.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index b201823..e6fde5f 100644 --- a/README.md +++ b/README.md @@ -68,11 +68,13 @@ Here is a list of named arguments you can define when calling Enrich that relate Enrich("", $company = "My Company", $confidential = 0) ``` -### Entity-relationship diagrams +--- + +## Entity-relationship diagrams When building ER diagrams you'll want to make sure your diagram type is `"er"` when calling `Enrich` to ensure styles are applied correctly. -#### Assumptions/defaults +### Assumptions/defaults There are some assumptions made by this library when generating ER diagrams. These defaults can be overridden but have been optimized for diagraming databases created using ActiveRecord (a popular ORM for Ruby on Rails applications). You can call `SET_SCHEMA_DEFAULTS` with the following named arguments to override them. @@ -90,7 +92,7 @@ Below is a simple example of changing the default to use a "UUID" datatype inste SET_SCHEMA_DEFAULTS($id_type="UUID") ``` -#### Tables +### Tables To define a new table, use the `Table` element. To set the table name pass it in as the first argument. Within your table you can use additional macros to define the columns your table and to associate tables together (read on). @@ -101,7 +103,7 @@ Table(your_table_name) { } ``` -#### Primary keys +### Primary keys Define a primary key field within your table using `table_pk()`. By default the field will be called 'id' with a datatype of 'INTEGER(11)' but you can override this behavior by passing in arguments or by changing the schema defaults via `SET_SCHEMA_DEFAULTS` @@ -116,7 +118,7 @@ table_pk('identifier') table_pk('id', 'UUID') ``` -#### Foreign keys +### Foreign keys Define a foreign key field within your table using `table_fk()`. You'll need to define the column name by passing in a name as the first argument. By default the datatype will be 'INTEGER(11)' but you can override this behavior by passing in a second argument or by changing the schema defaults via `SET_SCHEMA_DEFAULTS`. By default, FK columns are non-nullable, you can override this behavior by passing in a `$nullable` named argument and setting it to true. @@ -131,7 +133,7 @@ table_fk(other_table_id, 'UUID') table_fk(other_table_id, $nullable=1) ``` -#### Table columns +### Table columns Define an ordinary field with `table_column()`. The first argument sets the column name and the second argument set its datatype. You can pass additional data, like if it is nullable or not using named arguments. By default columns are nullable, you can override this by passing in a `$nullable` named argument and setting it to true. @@ -143,7 +145,7 @@ table_column(column_name, 'DATETIME') table_column(column_name, 'DATETIME', $nullable=0) ``` -#### Timestamp columns +### Timestamp columns In most applications it is common to include some additional fields on your table to store "created_at" and "updated_at" timestamps (and sometimes "destroyed_at"). Instead of having to declare these fields on your table separately via `table_column()`, you can instead use `table_timestamps()`. You can configure which timestamp columns to add via named arguments. @@ -158,7 +160,7 @@ table_timestamps($destroyed_at=1) table_timestamps($updated_at=0) ``` -#### Partial Tables +### Partial Tables Often times you will find yourself only needing to diagram a single area of concern in your schema and not the entire schema. In this case there are some handy helpers provided. In the scenario where you just need to reference a table and handwave over its entire shape, you can use the `PartialTable` element. If you are diagraming out a table but want to handwave over irrelevant columns you can use `table_omission()`. @@ -175,7 +177,7 @@ Table(users) { } ``` -#### Relationships +### Relationships To define a many to one relationship use `has_one()`. To define a many to many relationship use `has_many()`. @@ -195,7 +197,7 @@ Table(authors) { has_one(books, authors) ``` -#### Polymorphic Relationships +### Polymorphic Relationships Polymorphic relationships are a non-standard concept when talking about modeling a data schema. However, most ORMs support this type of relationship so modeling them in your ER diagrams is a common challenge. Since a polymorphic relationship represents a relationship to differing tables we can represent the polymorphic relationship as an intermediate object between the table containing the foreign key and the tables that it could possibly be referencing. Below is a complete example to show how this works in practice. @@ -220,7 +222,7 @@ poly_can_be(ownable, companies) ``` -#### Enums +### Enums To represent enums in your schema, you can define an `EnumType` element. Pass in the enum name and its datatype as the first and second arguments. It appears similar to a table in your diagram but will be styled a bit differently and will contain the values of your enum.