From c9cbd318fac297ffcddaeb5439e25c882222577d Mon Sep 17 00:00:00 2001 From: horenso Date: Mon, 19 Feb 2024 19:25:28 +0100 Subject: [PATCH] Add database_documentation and improve schema patch doc. Co-authored-by: chr-schr --- backend/Makefile | 4 +- backend/diesel.toml | 6 ++- .../down.sql | 5 +++ .../up.sql | 19 ++++++++++ backend/src/schema.patch | 21 ++++------- doc/backend/06updating_schema_patch.md | 37 ++++++++++++++++--- doc/changelog.md | 3 +- 7 files changed, 72 insertions(+), 23 deletions(-) create mode 100644 backend/migrations/99999999999999_database_documentation/down.sql create mode 100644 backend/migrations/99999999999999_database_documentation/up.sql diff --git a/backend/Makefile b/backend/Makefile index 9f36065c9..7bf5e33eb 100644 --- a/backend/Makefile +++ b/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/* diff --git a/backend/diesel.toml b/backend/diesel.toml index 323408016..91e7e1730 100644 --- a/backend/diesel.toml +++ b/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", +] diff --git a/backend/migrations/99999999999999_database_documentation/down.sql b/backend/migrations/99999999999999_database_documentation/down.sql new file mode 100644 index 000000000..bb03242b2 --- /dev/null +++ b/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. +-- diff --git a/backend/migrations/99999999999999_database_documentation/up.sql b/backend/migrations/99999999999999_database_documentation/up.sql new file mode 100644 index 000000000..c8204f2d9 --- /dev/null +++ b/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'; diff --git a/backend/src/schema.patch b/backend/src/schema.patch index 88f0f4345..869a7d9f2 100644 --- a/backend/src/schema.patch +++ b/backend/src/schema.patch @@ -1,15 +1,12 @@ -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; - @@ -17,21 +14,19 @@ index 54f26f46..68427977 100644 - #[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; diff --git a/doc/backend/06updating_schema_patch.md b/doc/backend/06updating_schema_patch.md index 8499c44ec..cd2a83871 100644 --- a/doc/backend/06updating_schema_patch.md +++ b/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. diff --git a/doc/changelog.md b/doc/changelog.md index ed11fbcd9..0c1fc2dec 100644 --- a/doc/changelog.md +++ b/doc/changelog.md @@ -8,13 +8,14 @@ Syntax: `- short text describing the change _(Your Name)_` ## 0.3.7 - UNRELEASED -- _()_ +- 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)_