Add database_documentation and improve schema patch doc.

Co-authored-by: chr-schr <[email protected]>

Author: horenso

backend/Makefile

@@ -31,11 +31,11 @@ reset-database: ## Reset diesel database
 .PHONY: install
 install: ## Install dependencies within the source repo
 	rustup component add rustfmt clippy
-	cargo install diesel_cli@2.0.1 --no-default-features --features postgres && cargo install typeshare-cli
+	cargo install diesel_cli@2.1.1 --no-default-features --features postgres && cargo install typeshare-cli
 
 .PHONY: uninstall
 uninstall: ## Uninstall and clean everything in the backend
 	-cargo clean
 	-rustup component remove rustfmt clippy
-	-cargo uninstall diesel_cli@2.0.1 && cargo install typeshare-cli
+	-cargo uninstall diesel_cli@2.1.1 && cargo install typeshare-cli
 	-rm -rf target/*

backend/diesel.toml

@@ -1,6 +1,10 @@
 [print_schema]
 file = "src/schema.rs"
 patch_file = "src/schema.patch"
+with_docs = "only-database-comments"
 
 filter = { except_tables = ["spatial_ref_sys"] }
-import_types = ["postgis_diesel::sql_types::Geography", "diesel::sql_types::*"]
+import_types = [
+    "postgis_diesel::sql_types::Geography",
+    "postgis_diesel::sql_types::Geometry",
+]

backend/migrations/99999999999999_database_documentation/down.sql

@@ -0,0 +1,5 @@
+COMMENT ON DATABASE permaplant IS NULL;
+
+--
+-- Don't alter the database schema in this file.
+--

backend/migrations/99999999999999_database_documentation/up.sql

@@ -0,0 +1,19 @@
+--
+-- Only add database comments in this migration.
+--
+
+COMMENT ON TABLE layers IS 'The layers of a map';
+
+COMMENT ON COLUMN layers.name IS 'The name of the layer
+        Example: "Base Layer"';
+
+COMMENT ON COLUMN layers.type IS 'The type of the layer (ENUM layer_type)
+        Examples: base, plants, shade, ...';
+
+COMMENT ON COLUMN layers.type IS 'Whether the layer was created by the user as an alternative to a pre-existing layer';
+
+
+
+
+
+COMMENT ON COLUMN plantings.id IS 'This is generated by the frontend';

backend/src/schema.patch

@@ -1,37 +1,32 @@
-diff --git a/backend/src/schema.rs b/backend/src/schema.rs 2023-07-20
-index 54f26f46..68427977 100644
---- a/backend/src/schema.rs
-+++ b/backend/src/schema.rs
-@@ -10,20 +10,12 @@ pub mod sql_types {
-     pub struct ExternalSource;
+--- src/schema.rs	2024-02-19 18:13:43.582300382 +0000
++++ src/schema_tmp.rs	2024-02-19 18:12:36.849610756 +0000
+@@ -15,20 +15,12 @@
 
      #[derive(diesel::sql_types::SqlType)]
      #[diesel(postgres_type(name = "fertility"))]
      pub struct Fertility;
 
--    #[derive(diesel::sql_types::SqlType)]
+     #[derive(diesel::sql_types::SqlType)]
 -    #[diesel(postgres_type(name = "geography"))]
 -    pub struct Geography;
 -
 -    #[derive(diesel::sql_types::SqlType)]
 -    #[diesel(postgres_type(name = "geometry"))]
 -    pub struct Geometry;
 -
-     #[derive(diesel::sql_types::SqlType)]
+-    #[derive(diesel::sql_types::SqlType)]
      #[diesel(postgres_type(name = "growth_rate"))]
      pub struct GrowthRate;
 
      #[derive(diesel::sql_types::SqlType)]
      #[diesel(postgres_type(name = "herbaceous_or_woody"))]
-@@ -100,16 +92,15 @@ diesel::table! {
-         is_alternative -> Bool,
-     }
+     pub struct HerbaceousOrWoody;
+@@ -162,14 +154,12 @@
  }
 
  diesel::table! {
      use postgis_diesel::sql_types::Geography;
-+    use postgis_diesel::sql_types::Geometry;
-     use diesel::sql_types::*;
+     use postgis_diesel::sql_types::Geometry;
      use super::sql_types::PrivacyOption;
 -    use super::sql_types::Geography;
 -    use super::sql_types::Geometry;

doc/backend/06updating_schema_patch.md

@@ -1,8 +1,27 @@
-# Update the `schema.patch` file
+# Why do we need the `schema.patch` file
 
-This document explains how to update the `schema.patch` file used by diesel.
+When executing `diesel migration run` diesel connects to the database and
+expresses the current schema of the database in the `schema.rs` file. The
+config for this mechanism is in `diesel.toml`. You can use `diesel print-schema`
+to output the schema manually. Unfortunately Diesel generates type definitions
+for types we import from Postgis. This results in a double use:
 
-1. Remove the following line from `diesel.toml`:
+```
+diesel::table! {
+    use postgis_diesel::sql_types::Geography; // <-- even though we import using --import-types
+    use super::sql_types::Geography;          // <-- this gets generated by Diesel
+```
+
+After generating the `schema.rs` file Diesel applies the patch file to it.
+
+# When to update `schema.patch` file
+
+Whenever you get an error message similar to `error applying hunk #2` you have to update the `schema.patch` file.
+This happens when `schema.rs` changes in the diff context of the patch file (the lines before and after the change).
+
+# How to update the `schema.patch` file
+
+1. Comment out the following line from `diesel.toml`:
 
    ```toml
    patch_file = "src/schema.patch"
@@ -17,7 +36,13 @@ This document explains how to update the `schema.patch` file used by diesel.
    You should now have a generated `schema.rs` in the backend src folder.
 
 3. Copy the `schema.rs` file e.g. to `schema_tmp.rs`.
-4. Run `` diff src/schema.rs `src/schema_tmp.rs` -U6 `` in the backend folder and save the result to the `src/schema.patch` file.
-5. Add `patch_file = "src/schema.patch"` to the `diesel.toml` again.
 
-From now on the newly generated patch file should be used by diesel.
+4. Make the necessary changes to `schema_tmp.rs`.
+
+5. In the backend directory run `diff -U6 src/schema.rs src/schema_tmp.rs > src/schema.patch`.
+
+6. Add `patch_file = "src/schema.patch"` to the `diesel.toml` again.
+
+7. Delete `schema_tmp.rs`.
+
+From now on the newly generated patch file should be used by Diesel.

doc/changelog.md

@@ -10,13 +10,14 @@ Syntax: `- short text describing the change _(Your Name)_`
 
 - needs new migrations
 - needs new scraper data (integer for plant spread and height)
-- _()_
+- Add database documentation. _(Christoph @chr_schr, Jannis @horenso)_
 - Remove variety from table seeds _(Jannis Adamek)_
 - Refactor react query error handling _(Daniel Steinkogler)_
 - Add notes to plantings in backend #1156 _(Jannis Adamek)_
 - Fix seed routes and add naming convention guideline _(Daniel Steinkogler)_
 - Enable automatic image scaling in base layer _(Moritz)_
 - _()_
+
 - Add [guideline](guidelines/frontend-keyhandling.md) and [decisions](decisions/frontend_keyhandling.md) for key handling) _(Daniel Steinkogler)_
 - _()_
 - Fix ref warning in PlantLabel, center labels as intended _(Paul)_