From 487aed02a5550c2ea73e026c78ff2de3ff6c7ac2 Mon Sep 17 00:00:00 2001 From: Chris Date: Sat, 5 Aug 2023 15:46:33 +0200 Subject: [PATCH 1/4] update database documentation --- doc/database/schemata/01er_diagram.md | 225 ----------- .../01er_tables_implemented_diagram.md | 351 ++++++++++++++++++ .../schemata/02er_enum_types_diagram.md | 214 +++++++++++ doc/database/schemata/02table_descriptions.md | 55 ++- doc/database/schemata/03example_queries.md | 47 --- doc/database/schemata/README.md | 3 +- 6 files changed, 605 insertions(+), 290 deletions(-) delete mode 100644 doc/database/schemata/01er_diagram.md create mode 100644 doc/database/schemata/01er_tables_implemented_diagram.md create mode 100644 doc/database/schemata/02er_enum_types_diagram.md delete mode 100644 doc/database/schemata/03example_queries.md diff --git a/doc/database/schemata/01er_diagram.md b/doc/database/schemata/01er_diagram.md deleted file mode 100644 index f0251828a..000000000 --- a/doc/database/schemata/01er_diagram.md +++ /dev/null @@ -1,225 +0,0 @@ -# ER diagram - -```mermaid -erDiagram - -enum_tag { - VARCHAR Leaf_crops - VARCHAR Fruit_crops - VARCHAR Root_crops - VARCHAR Flowering_crops - VARCHAR Herbs - VARCHAR Other -} - -enum_quantity { - VARCHAR Nothing - VARCHAR Not_enough - VARCHAR Enough - VARCHAR More_than_enough -} - -enum_quality { - VARCHAR Organic - VARCHAR Not_organic - VARCHAR Unknown -} - -seeds { - INT id PK - tags tag "NOT NULL" - INT plant_id "NOT NULL" - SMALLINT harvest_year "NOT NULL" - DATE use_by - VARCHAR origin - VARCHAR flavor - INT yield - INT quantity - quality quality - MONEY price - INT generation - VARCHAR notes -} - -plants { - INT id PK - tags tag "NOT NULL" - VARCHAR type "NOT NULL" - VARCHAR synonym - SMALLINT sowing_from - SMALLINT sowing_to - INT sowing_depth - INT germination_temperature - BOOLEAN prick_out - DATE transplant - INT row_spacing - INT plant_density - INT germination_time - INT harvest_time - VARCHAR location - VARCHAR care - INT height -} - -plant_detail{} - -plants }o--|| plant_detail: "type" - -plants ||--o{ seeds : "" - -relations { - INT plant1 PK - INT plant2 PK - RELATION_TYPE relation "NOT NULL" - VARCHAR note -} -relations }o--|| plants : "plant1" -relations }o--|| plants : "plant2" - -species{} -genus{} -subfamily{} -family{} - -relation{} - -plant_detail }|--|| species : "" -plant_detail }|--|| genus : "" -plant_detail }|--|| subfamily : "" -plant_detail }|--|| family : "" - -maps { - INT id PK - VARCHAR name "NOT NULL" - BOOLEAN is_inactive "NOT NULL" - DATE last_visit - INT honors - INT visits - INT harvested - DATE creation_date - DATE deletion_date - DATE inactivity_date - INT zoom_factor - GEOGRAPHY geo_data -} - -layers { - INT id PK - LAYER_TYPES type "NOT NULL" - VARCHAR name "NOT NULL" - BOOLEAN is_alternative "NOT NULL" -} -layers }|--|| maps : "" - -plantings { - INT id PK - INT layer_id - INT plant_id - INT x - INT y - INT width - INT height - REAL rotation - REAL scale_x - REAL scale_y -} -plantings }o--|| layers : "" -plantings }o--|| plants : "" - -users { - UUID id PK - SALUTATION salutation "NOT NULL" - VARCHAR title - VARCHAR country "NOT NULL" - VARCHAR phone - VARCHAR website - VARCHAR organization - EXPERIENCE experience - MEMBERSHIP membership - INT[] member_years - DATE member_since - INT[] permacoins -} - -guided_tours { - UUID user_id PK - BOOLEAN editor_tour "NOT NULL" -} - -blossoms { - VARCHAR title PK - VARCHAR description - TRACKS track - VARCHAR icon - BOOLEAN is_seasonal "NOT NULL" -} - -enum_tracks { - VARCHAR beginners_track - VARCHAR seasonal_track - VARCHAR completionist_track - VARCHAR expert_track -} - -enum_salutation { - VARCHAR ms - VARCHAR mrs - VARCHAR mr -} - -enum_experience { - VARCHAR beginner - VARCHAR advanced - VARCHAR expert -} - -enum_membership { - VARCHAR supporting_membership - VARCHAR regular_membership - VARCHAR contributing_membership -} - -blossoms_gained { - UUID user_id PK - INT times_gained - DATE[] gained_date -} - -maps }o--|| users : "owned by" -blossoms ||--o{ blossoms_gained : "" - -ingredientLists { - INT id PK - VARCHAR name "NOT NULL" - VARCHAR description - BYTEA image - BOOLEAN is_recurring "NOT NULL" - DATE end_date "NOT NULL" - INT accomplished -} - -ingredients { - BOOLEAN is_fulfilled "NOT NULL" -} - -ingredientLists }o--|| users : "" -ingredientLists }o--|| maps : "" -ingredients }|--|| ingredientLists : "" -ingredients }|--|| plant_detail : "" - -events { - INT id PK - BOOLEAN system_event "NOT NULL" - VARCHAR name "NOT NULL" - VARCHAR description - DATE event_date "NOT NULL" -} - -events }o--|| maps : "" - -favorites {} - -favorites }o--|| maps : "" -favorites }o--|| plant_detail : "" - -``` diff --git a/doc/database/schemata/01er_tables_implemented_diagram.md b/doc/database/schemata/01er_tables_implemented_diagram.md new file mode 100644 index 000000000..c4d4dfaab --- /dev/null +++ b/doc/database/schemata/01er_tables_implemented_diagram.md @@ -0,0 +1,351 @@ +# ER diagram + +```mermaid +erDiagram + +seeds { + INT id PK + INT plant_id "NOT NULL" + TEXT name "NOT NULL" + SMALLINT harvest_year "NOT NULL" + DATE use_by + TEXT origin + TEXT taste + TEXT yield + TEXT variety + QUANTITY quantity + QUALITY quality + INT price + INT generation + TEXT notes + INT owner_id "NOT NULL" +} + +plants { + INT id PK + TEXT unique_name "NOT NULL" + TEXT[] common_name_en + TEXT[] common_name_de + TEXT family + TEXT edible_uses_en + TEXT functions + SMALLINT heat_zone + SHADE shade + SOIL_PH[] soil_ph + SOIL_TEXTURE[] soil_texture + TEXT ecosystem_niche + DECIDUOUS_OR_EVERGREEN deciduous_or_evergreen + HERBACEOUS_OR_WOODY herbaceous_or_woody + LIFE_CYCLE[] life_cycle + GROWTH_RATE[] growth_rate + PLANT_HEIGHT plant_height + FERTILITY[] fertility + TIMESTAMP created_at + TIMESTAMP updated_at + BOOLEAN has_drought_tolerance + BOOLEAN tolerates_wind + SMALLINT preferable_permaculture_zone + TEXT hardiness_zone + LIGHT_REQUIREMENT[] light_requirement + WATER_REQUIREMENT[] water_requirement + PROPAGATION_METHOD[] propagation_method + TEXT alternate_name + BOOLEAN edible + TEXT[] edible_parts + PLANT_SPREAD spread + TEXT warning + SMALLINT version + EXTERNAL_SOURCE external_source + SMALLINT[] sowing_outdoors + SMALLINT[] harvest_time + DOUBLE seed_weight_1000 +} + + +relations { + INT plant1 PK + INT plant2 PK + RELATION_TYPE relation "NOT NULL" + TEXT note +} + + + + +maps { + INT id PK + TEXT name "NOT NULL" + DATE creation_date "NOT NULL" + DATE deletion_date + DATE last_visit + BOOLEAN is_inactive "NOT NULL" + INT zoom_factor "NOT NULL" + INT honors "NOT NULL" + INT visits "NOT NULL" + INT harvested "NOT NULL" + PRIVACY_OPTION privacy "NOT NULL" + TEXT description + GEOGRAPHY location + INT owner_id "NOT NULL" + GEOMETRY geometry "NOT NULL" + +} + +layers { + INT id PK + INT map_id "NOT NULL" + LAYER_TYPES type "NOT NULL" + TEXT name "NOT NULL" + BOOLEAN is_alternative "NOT NULL" +} + + +plantings { + INT id PK + INT layer_id "NOT NULL" + INT plant_id "NOT NULL" + INT x "NOT NULL" + INT y "NOT NULL" + INT width "NOT NULL" + INT height "NOT NULL" + REAL rotation "NOT NULL" + REAL scale_x "NOT NULL" + REAL scale_y "NOT NULL" + DATE add_date + DATE remove_date +} + + +users { + UUID id PK + SALUTATION salutation "NOT NULL" + TEXT title + TEXT country "NOT NULL" + TEXT phone + TEXT website + TEXT organization + EXPERIENCE experience + MEMBERSHIP membership + INT[] member_years + DATE member_since + INT[] permacoins +} + +guided_tours { + UUID user_id PK + BOOLEAN editor_tour "NOT NULL" +} + +blossoms { + TEXT title PK + TEXT description + TRACKS track + TEXT icon + BOOLEAN is_seasonal "NOT NULL" +} + + +blossoms_gained { + UUID user_id PK + TEXT blossom "NOT NULL" + INT times_gained "NOT NULL" + DATE gained_date "NOT NULL" +} + +base_layer_images { + UUID id PK + INT layer_id "NOT NULL" + TEXT path "NOT NULL" + REAL rotation "NOT NULL" + REAL scale "NOT NULL" +} + + +plants ||--o{ seeds : "" +relations }o--|| plants : "plant1" +relations }o--|| plants : "plant2" +layers }|--|| maps : "" +plantings }o--|| layers : "" +plantings }o--|| plants : "" +maps }o--|| users : "owned by" +blossoms ||--o{ blossoms_gained : "" + + + + + + + + + + + + +``` + +## Plants Table + +For performance reasons, we decided to disable certain columns for the plants table for now. + +For more information, see: [PR #644](https://github.com/ElektraInitiative/PermaplanT/pull/644) + +The following columns are commented out for now: + +- genus: text +- medicinal_uses: text +- material_uses_and_functions: text +- botanic: text +- material_uses: text +- soil_water_retention: soil_water_retention[] +- environmental_tolerances: text[] +- native_geographical_range: text +- native_environment: text +- flower_colour: text +- flower_type: flower_type +- plant_references: text[] +- is_tree: boolean +- nutrition_demand: nutrition_demand +- article_last_modified_at: timestamp without time zone +- diseases: text +- germination_temperature: text +- introduced_into: text +- habitus: text +- medicinal_parts: text +- native_to: text +- plants_for_a_future: text +- plants_of_the_world_online_link: text +- plants_of_the_world_online_link_synonym: text +- pollination: text +- propagation_transplanting_en: text +- resistance: text +- root_type: text +- seed_planting_depth_en: text +- seed_viability: text +- slug: text +- utility: text +- when_to_plant_cuttings_en: text +- when_to_plant_division_en: text +- when_to_plant_transplant_en: text +- when_to_sow_indoors_en: text +- sowing_outdoors_en: text +- when_to_start_indoors_weeks: text +- when_to_start_outdoors_weeks: text +- cold_stratification_temperature: text +- cold_stratification_time: text +- days_to_harvest: text +- habitat: text +- spacing_en: text +- wikipedia_url: text +- days_to_maturity: text +- pests: text +- germination_time: text +- description: text +- parent_id: text +- external_id: text +- external_url: text +- root_depth: text +- external_article_number: text +- external_portion_content: text +- sowing_outdoors_de: text +- spacing_de: text +- required_quantity_of_seeds_de: text +- required_quantity_of_seeds_en: text +- seed_planting_depth_de: text +- seed_weight_1000_de: text +- seed_weight_1000_en: text +- machine_cultivation_possible: boolean +- edible_uses_de: text + + + + + + + + + + diff --git a/doc/database/schemata/02er_enum_types_diagram.md b/doc/database/schemata/02er_enum_types_diagram.md new file mode 100644 index 000000000..8ba5ec1b0 --- /dev/null +++ b/doc/database/schemata/02er_enum_types_diagram.md @@ -0,0 +1,214 @@ +# Enum Types + +### These are all the enum types we currently have implemented: + +```mermaid +erDiagram + +enum_deciduous_or_evergreen{ + ENUM deciduous + ENUM evergreen +} +enum_experience{ + ENUM beginner + ENUM advanced + ENUM expert +} +enum_external_source{ + ENUM practicalplants + ENUM permapeople + ENUM reinsaat +} + +``` + +```mermaid +erDiagram + +enum_fertility{ + ENUM self_fertile + ENUM self_sterile +} +enum_growth_rate{ + ENUM slow + ENUM moderate + ENUM vigorous +} +enum_herbaceous_or_woody{ + ENUM herbaceous + ENUM woody +} + +``` + +```mermaid +erDiagram + +enum_layer_type{ + ENUM base + ENUM soil + ENUM todo + ENUM label + ENUM paths + ENUM photo + ENUM shade + ENUM trees + ENUM winds + ENUM zones + ENUM plants + ENUM drawing + ENUM terrain + ENUM habitats + ENUM warnings + ENUM watering + ENUM landscape + ENUM hydrology + ENUM fertilization + ENUM infrastructure +} +enum_life_cycle{ + ENUM annual + ENUM biennial + ENUM perennial +} +enum_light_requirement{ + ENUM full_sun + ENUM partial_sun_or_shade + ENUM full_shade +} + +``` + +```mermaid +erDiagram + +enum_membership{ + ENUM supporting + ENUM regular + ENUM contributing +} +enum_nutrition_demand{ + ENUM light_feeder + ENUM moderate_feeder + ENUM heavy_feeder +} +enum_plant_height{ + ENUM low + ENUM medium + ENUM high +} + +``` + +```mermaid +erDiagram + +enum_plant_spread{ + ENUM narrow + ENUM medium + ENUM wide +} +enum_privacy_option{ + ENUM private + ENUM protected + +} +enum_propagation_method{ + ENUM seed_direct_sow + ENUM seed_transplant + ENUM division + ENUM cuttings + ENUM layering + ENUM spores + ENUM seed +} + +``` + +```mermaid +erDiagram + +enum_quality{ + ENUM organic + ENUM not_organic + ENUM unknown +} +enum_quantity{ + ENUM nothing + ENUM not_enough + ENUM enough + ENUM more_than_enough +} +enum_relation_type{ + ENUM companion + ENUM neutral + ENUM antagonist +} + +``` + +```mermaid +erDiagram + +enum_salutation{ + ENUM ms + ENUM mrs + ENUM mr + ENUM mx +} +enum_shade{ + ENUM no_shade + ENUM light_shade + ENUM partial_shade + ENUM permanent_shade + ENUM permanent_deep_shade +} +enum_soil_ph{ + ENUM very_acid + ENUM acid + ENUM neutral + ENUM alkaline + ENUM very_alkaline +} + +``` + +```mermaid +erDiagram + +enum_soil_texture{ + ENUM sandy + ENUM loamy + ENUM clay + ENUM heavy_clay +} +enum_track{ + ENUM beginner + ENUM seasonal + ENUM completionist + ENUM expert +} +enum_water_requirement{ + ENUM dry + ENUM moist + ENUM wet + ENUM water +} + +``` + +### These are all the enum types we currently have NOT implemented: + +```mermaid +erDiagram + +enum_tag{ + ENUM Leaf_crops + ENUM Fruit_crops + ENUM Root_crops + ENUM Flowering_crops + ENUM Herbs + ENUM Other +} + +``` diff --git a/doc/database/schemata/02table_descriptions.md b/doc/database/schemata/02table_descriptions.md index 61e640490..8d397f2f9 100644 --- a/doc/database/schemata/02table_descriptions.md +++ b/doc/database/schemata/02table_descriptions.md @@ -2,6 +2,8 @@ ## `Plant_detail` + + | **_Column name_** | **_Example_** | **_Initial rule_** | **_Description_** | | :------------------------------- | :------------------------------- | :------------------------------------------------------------------------------------------------ | :--------------------------------- | | **id** | 1 | @@ -69,22 +71,26 @@ Store relations between plants. ## `Maps` -| **_Column name_** | **_Example_** | **_Description_** | -| :------------------ | :------------ | :--------------------------------------------------------------------------------------------- | -| **id** | 1 | -| **owner_id** | 1 | -| **name** | My Map | only alphanumerical values | -| **is_inactive** | false | -| **last_visit** | 2023-04-04 | -| **honors** | 0 | 0 to infinity | -| **visits** | 0 | 0 to infinity | -| **harvested** | 0 | 0 to infinity, amount of plants harvested on this map | -| **version_date** | 2023-04-04 | the date the snapshot for this version was taken | -| **creation_date** | 2023-04-04 | -| **deletion_date** | 2023-04-04 | -| **inactivity_date** | 2023-04-04 | -| **zoom_factor** | 100 | value used in formula "X by X cm", e.g. 100 would mean "100 x 100 cm", range from 10 to 100000 | -| **geo_data** | NULL | PostGis Geodata, location of the map | +| **_Column name_** | **_Example_** | **_Description_** | +| :---------------- | :------------ | :--------------------------------------------------------------------------------------------- | +| **id** | 1 | +| **owner_id** | 1 | +| **name** | My Map | only alphanumerical values | +| **is_inactive** | false | +| **last_visit** | 2023-04-04 | +| **honors** | 0 | 0 to infinity | +| **visits** | 0 | 0 to infinity | +| **harvested** | 0 | 0 to infinity, amount of plants harvested on this map | +| **privacy** | protected | privacy_option enum type | +| **description** | Our first map | | +| **creation_date** | 2023-04-04 | +| **deletion_date** | 2023-04-04 | +| **zoom_factor** | 100 | value used in formula "X by X cm", e.g. 100 would mean "100 x 100 cm", range from 10 to 100000 | +| **location** | NULL | PostGis Geodata, location of the map | +| **geometry** | FILLME | Layout of the map. | + + + ## `Layers` @@ -110,6 +116,8 @@ Store relations between plants. | **rotation** | 0 | the rotation of the plant on the map. | | **scale_x** | 1 | the x scale of the plant on the map. | | **scale_y** | 1 | the y scale of the plant on the map. | +| **add_date** | 2023-04-04 | Date when the plant was planted | +| **remove_date** | 2023-04-04 | Date when the plant was removed | ## `Users` @@ -155,6 +163,18 @@ Store relations between plants. | **times_gained** | 1 | 0 to infinity | | **gained_date** | {2023-04-10} | one entry for every time gained | +## `Base Layer Images` + +| **_Column name_** | **_Example_** | **_Description_** | +| :---------------- | :----------------------------------- | :---------------- | +| **id** | 00000000-0000-0000-0000-000000000000 | | +| **layer_id** | 1 | +| **path** | background.jpg | +| **rotation** | 0 | | +| **scale** | 1 | | + + diff --git a/doc/database/schemata/03example_queries.md b/doc/database/schemata/03example_queries.md deleted file mode 100644 index 7ea34ee25..000000000 --- a/doc/database/schemata/03example_queries.md +++ /dev/null @@ -1,47 +0,0 @@ -# Example queries - -## Get all plants with their hierarchy information - -```sql -SELECT * - FROM plant_detail - LEFT JOIN genus - ON plant_detail.genus = genus.name - LEFT JOIN subfamily - ON plant_detail.subfamily = subfamily.name - LEFT JOIN family - ON plant_detail.family = family.name; -``` - -## Insert a relation between a plant with a specific genus and a specific family - -```sql -INSERT INTO relations (from_id, from_type, to_id, to_type, relation_type, relation_strength) -VALUES (1, 'genus', 156, 'family', 'companion', 3); -``` - -## Get all plants that are companions to a specific family - -```sql -SELECT p.id, - p.binomial_name, - p.genus, - p.family, - p.subfamily, - r.* - FROM plant_detail p - LEFT JOIN genus - ON p.genus = genus.name - LEFT JOIN subfamily - ON p.subfamily = subfamily.name - LEFT JOIN family - ON p.family = family.name - JOIN relations r - ON r.relation_type = 'companion' AND r.to_type = 'family' AND r.to_id = 156 AND - CASE - WHEN r.from_type = 'plant' THEN r.id = p.id - WHEN r.from_type = 'genus' THEN r.id = genus.id - WHEN r.from_type = 'subfamily' THEN r.id = subfamily.id - WHEN r.from_type = 'family' THEN r.id = family.id - END; -``` diff --git a/doc/database/schemata/README.md b/doc/database/schemata/README.md index b50267fc7..7c6a4a797 100644 --- a/doc/database/schemata/README.md +++ b/doc/database/schemata/README.md @@ -1,5 +1,4 @@ # Schemata -Tag and Quality in this case are enum. Postgres supports [enums](https://www.postgresql.org/docs/current/datatype-enum.html) so it is easy to define a static set of values. -Right now, Mermaid doesn't support enum types so a `_` character denotes white spaces in enums. +Right now, Mermaid doesn't support white spaces in names, so a `_` character denotes white spaces in enums. From 77292f793595d91edd8a1c0f1327a3c9463b3f77 Mon Sep 17 00:00:00 2001 From: Chris Date: Sat, 5 Aug 2023 15:47:26 +0200 Subject: [PATCH 2/4] updated changelog - closes #654 --- doc/CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/CHANGELOG.md b/doc/CHANGELOG.md index d288a6f18..0b05f9053 100644 --- a/doc/CHANGELOG.md +++ b/doc/CHANGELOG.md @@ -26,7 +26,7 @@ Syntax: `- short text describing the change _(Your Name)_` - _()_ - Fix a bug where an 'empty' but visible selection box would be left behind _(Paul)_ - Fix a bug where seemingly random date change actions would be fired _(Paul)_ -- _()_ +- update database documentation _(temmey)_ - _()_ - _()_ - _()_ From 313a9054a4fc3267dc92921ea565bddf30401726 Mon Sep 17 00:00:00 2001 From: Chris Date: Sat, 12 Aug 2023 03:03:14 +0200 Subject: [PATCH 3/4] fixed filename and spellingissue --- .../{02table_descriptions.md => 03er_table_descriptions.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename doc/database/schemata/{02table_descriptions.md => 03er_table_descriptions.md} (99%) diff --git a/doc/database/schemata/02table_descriptions.md b/doc/database/schemata/03er_table_descriptions.md similarity index 99% rename from doc/database/schemata/02table_descriptions.md rename to doc/database/schemata/03er_table_descriptions.md index 8d397f2f9..6fb420a4e 100644 --- a/doc/database/schemata/02table_descriptions.md +++ b/doc/database/schemata/03er_table_descriptions.md @@ -2,7 +2,7 @@ ## `Plant_detail` - + | **_Column name_** | **_Example_** | **_Initial rule_** | **_Description_** | | :------------------------------- | :------------------------------- | :------------------------------------------------------------------------------------------------ | :--------------------------------- | From 7722e25493ddda3d485fd76203c0a8cf48cd5fd9 Mon Sep 17 00:00:00 2001 From: Chris Date: Sat, 12 Aug 2023 03:04:08 +0200 Subject: [PATCH 4/4] implemented requested changes --- .../01er_tables_implemented_diagram.md | 29 +++++-------------- 1 file changed, 7 insertions(+), 22 deletions(-) diff --git a/doc/database/schemata/01er_tables_implemented_diagram.md b/doc/database/schemata/01er_tables_implemented_diagram.md index c4d4dfaab..06ff8c01d 100644 --- a/doc/database/schemata/01er_tables_implemented_diagram.md +++ b/doc/database/schemata/01er_tables_implemented_diagram.md @@ -185,7 +185,7 @@ blossoms ||--o{ blossoms_gained : "" ## Plants Table -For performance reasons, we decided to disable certain columns for the plants table for now. +For performance reasons, we decided to disable some unused columns in the plants table for now. For more information, see: [PR #644](https://github.com/ElektraInitiative/PermaplanT/pull/644) @@ -258,8 +258,9 @@ The following columns are commented out for now: