From db0caf8d2fcc6cbe75b605ee087c792ccd0664ca Mon Sep 17 00:00:00 2001 From: Marc-Roig Date: Mon, 4 Sep 2023 15:37:33 +0200 Subject: [PATCH 1/8] feat/v5-database --- rfcs/xxxx-v5-database.md | 155 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 rfcs/xxxx-v5-database.md diff --git a/rfcs/xxxx-v5-database.md b/rfcs/xxxx-v5-database.md new file mode 100644 index 0000000..01b4454 --- /dev/null +++ b/rfcs/xxxx-v5-database.md @@ -0,0 +1,155 @@ +- Start Date: (fill in today's date, 2023-09-04) +- RFC PR: (leave this empty) + +# Summary + +We need to support development of new features. Most of them are going towards a more CMS like model. to support this approach we will introduce the notion of `documents` & `links`. + +# Motivation + +Bringing new features that were not possible in v4. The most important ones: + +## Draft and Publish + +Introducing a new version of draft & publish. One which allows having one draft and one published entry at the same time. + +This version should support having different relations between a draft and a published version. + +Consider a scenario where a writer wants to work on an article (draft) while the previously published version remains unaffected. This requires a system that supports simultaneous draft and published entries, leading to the idea of `Documents`. + +## Synchronized relations across locales + +In Strapi V4, users requested the ability to share the same relation across multiple locales. This led to the concept of `Links`, allowing relations to be shared across different document locales. And also unblocks other use cases mentioned in this RFC. + +Instead of breaking v4 relations `Links` will be a different type, and v4 relations will be kept as legacy relations. + +# Detailed design + +Documents are introduced in v5 as a way to group multiple entries. That is implemented by adding a new `document_id` column in entries: + +![Untitled]() + +Also, all the variations of that document will have its own column in every entry: + +- `locale` for i18n +- `publicationState` for draft and publish + +## Document id and entry id + +Additionally, in V5, all identifiers (entry ids and document ids) will now be universally unique identifiers (UUIDs). This transition offers significant benefits: + +- `Data Transfer`: Previously, transferring data between databases while retaining the same entry IDs was not possible, due to the use of incremental ids. + +The switch to UUIDs, which will keep entry and document ids unique, makes this feasible. + +- `More secure`: The use of UUIDs also enhances security. With incremental IDs, one could predict the existence of other IDs based on a known ID. For instance, if ID `10` is known, it is reasonable to infer that IDs `9`, `8`, etc., exist in the database. UUIDs, being non-sequential and randomly generated, prevent such easy discovery. + +While the probability of two UUIDs colliding is not zero, it is practically negligible, making them an excellent choice for unique identifiers. + +## Links + +`Links` introduce the following key functionalities: + +### Relate entry to document + +In V4, you might have encountered this situation: + +![Untitled]() + +When relating an article to a specific author in V4, only articles and authors of the same locale could be linked, because localizations were not really grouped in a single document. + +Thus, if an author did not have a locale that matched the article's, creating a relationship was impossible. + +`Links` will solve this by referencing a document as a whole, not a specific locale: + +![Untitled]() + +--- + +### Synchronize links across locales + +In V4, if you want to keep the same relation across the same locales, one would have to manually create them, with the risk of missing one. + +![Untitled]() + +In V5, `links` will offer the possibility to be synchronized across locales. + +![Untitled]() + +As an additional comment, the synched relation will only affect the locales inside the same publication state. Meaning, relations will not be shared between the `draft` and `published` versions of the document. + +![Untitled]() + +--- + +### Polymorphic links + +V5 will eventually support polymorphic links. + +Those will allow use cases like Website Menus , linked to many other content types + +![Untitled]() + +This was just not possible in V4. + +## Link content schema + +Links will be represented as so in the content type schema: + +```jsx +{ + attributes: { + “myLink”: { + “type”: "link", + // Target one (or multiple) content types. + // Target all by not defining target + “target”: "uid-a" | ["uid-a", "uid-b"] | undefined, + “multiple”: true|false + } + } +} +``` + +## Links Database Schema + +The database schema of `links` join tables : + +![Untitled]() + +The join table will now contain: + +- `Owner side doc id`: Reference to do the document id of the owner side (Article in the example) +- `Inverse side doc id`: Reference ot the document id of the inverse side (Author in the example) +- `pivot columns`: Reference the owner side variations (locale & publication state). +- `order`: Only in `manyWays` and `morphMany` relations. + +## Query engine + +The query engine will expose the same methods as before. + +This layer will be used to interact with the database rows directly, and as so, methods such as `findOne` and `update` will reference entry ids and not document ids. + +Interactions with documents will be done in the application layer `DocumentService` , which will be documented in another RFC. + +# Tradeoffs + +Benefits of this approach: + +- Links schema reduces the number of queries needed to read and create relations. +- It is conceptually easy, and similar to our approach. +- It's easy to share the same relation between different document locales. + +Downsides: + +- Links will not allow for bidirectionality. A relation that references an entry to a document introduces many complexities that prevents bidirectionality, or makes it rather difficult. The first versions of links will not have bidirectionality in mind. + +# Unresolved questions + +- How do we manage life cycles? + - A database lifecycle would trigger at an entry level, not a document level. As everything will be document oriented, database life cycles might have less sense from a user perspective in V5. + - Document life cycles could be managed in a upper layer than the database. +- How are we going to support v4 relation types with the new document ids. + - Could we connect a v4 relation with a document Id, or do we only support connecting with entry ids? +- Do we prefix internal strapi columns in db? + - We need to avoid collisions +- Which universal ID to be used. UUID, CUID, NANOID, ULID. From fdc882d527334a3ef39bd8c3a6eb8a77cb198052 Mon Sep 17 00:00:00 2001 From: Marc Roig Date: Mon, 4 Sep 2023 15:51:25 +0200 Subject: [PATCH 2/8] chore: add database diagrams --- rfcs/xxxx-v5-database.md | 35 +++++++++++++++++++++++++---------- 1 file changed, 25 insertions(+), 10 deletions(-) diff --git a/rfcs/xxxx-v5-database.md b/rfcs/xxxx-v5-database.md index 01b4454..8d54f35 100644 --- a/rfcs/xxxx-v5-database.md +++ b/rfcs/xxxx-v5-database.md @@ -27,7 +27,9 @@ Instead of breaking v4 relations `Links` will be a different type, and v4 relati Documents are introduced in v5 as a way to group multiple entries. That is implemented by adding a new `document_id` column in entries: -![Untitled]() +

+ +

Also, all the variations of that document will have its own column in every entry: @@ -54,7 +56,10 @@ While the probability of two UUIDs colliding is not zero, it is practically negl In V4, you might have encountered this situation: -![Untitled]() +

+ +

+ When relating an article to a specific author in V4, only articles and authors of the same locale could be linked, because localizations were not really grouped in a single document. @@ -62,25 +67,31 @@ Thus, if an author did not have a locale that matched the article's, creating a `Links` will solve this by referencing a document as a whole, not a specific locale: -![Untitled]() +

+ +

---- ### Synchronize links across locales In V4, if you want to keep the same relation across the same locales, one would have to manually create them, with the risk of missing one. -![Untitled]() +

+ +

In V5, `links` will offer the possibility to be synchronized across locales. -![Untitled]() +

+ +

As an additional comment, the synched relation will only affect the locales inside the same publication state. Meaning, relations will not be shared between the `draft` and `published` versions of the document. -![Untitled]() +

+ +

---- ### Polymorphic links @@ -88,7 +99,9 @@ V5 will eventually support polymorphic links. Those will allow use cases like Website Menus , linked to many other content types -![Untitled]() +

+ +

This was just not possible in V4. @@ -114,7 +127,9 @@ Links will be represented as so in the content type schema: The database schema of `links` join tables : -![Untitled]() +

+ +

The join table will now contain: From 38158b784128adae8a1a3dceef5459c78a44bf38 Mon Sep 17 00:00:00 2001 From: Marc Roig Date: Mon, 4 Sep 2023 15:55:27 +0200 Subject: [PATCH 3/8] chore: v5 database reference PR --- rfcs/xxxx-v5-database.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/rfcs/xxxx-v5-database.md b/rfcs/xxxx-v5-database.md index 8d54f35..bbe4bbc 100644 --- a/rfcs/xxxx-v5-database.md +++ b/rfcs/xxxx-v5-database.md @@ -1,6 +1,5 @@ - Start Date: (fill in today's date, 2023-09-04) -- RFC PR: (leave this empty) - +- RFC PR: https://github.com/strapi/rfcs/pull/52 # Summary We need to support development of new features. Most of them are going towards a more CMS like model. to support this approach we will introduce the notion of `documents` & `links`. From 368618772d8ac61663dce7037d6aae02206dc4ed Mon Sep 17 00:00:00 2001 From: Marc Roig Date: Mon, 4 Sep 2023 15:59:44 +0200 Subject: [PATCH 4/8] chore: update v5 database rfc date --- rfcs/xxxx-v5-database.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/xxxx-v5-database.md b/rfcs/xxxx-v5-database.md index bbe4bbc..1a17009 100644 --- a/rfcs/xxxx-v5-database.md +++ b/rfcs/xxxx-v5-database.md @@ -1,4 +1,4 @@ -- Start Date: (fill in today's date, 2023-09-04) +- Start Date: 2023-09-04 - RFC PR: https://github.com/strapi/rfcs/pull/52 # Summary From d457521f39563371ef80d499051b62d2c221a0df Mon Sep 17 00:00:00 2001 From: DMehaffy Date: Wed, 6 Sep 2023 10:59:11 -0700 Subject: [PATCH 5/8] fix: bad codeblock formatting --- rfcs/xxxx-v5-database.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/rfcs/xxxx-v5-database.md b/rfcs/xxxx-v5-database.md index 1a17009..5ff1473 100644 --- a/rfcs/xxxx-v5-database.md +++ b/rfcs/xxxx-v5-database.md @@ -111,14 +111,14 @@ Links will be represented as so in the content type schema: ```jsx { attributes: { - “myLink”: { - “type”: "link", - // Target one (or multiple) content types. - // Target all by not defining target - “target”: "uid-a" | ["uid-a", "uid-b"] | undefined, - “multiple”: true|false - } - } + myLink: { + type: "link", + // Target one (or multiple) content types. + // Target all by not defining target + target: "uid-a" | ["uid-a", "uid-b"] | undefined, + multiple: true|false + } + } } ``` From a7563dcd98786d049a3b58359d01307dd2b65216 Mon Sep 17 00:00:00 2001 From: Marc Roig Date: Fri, 8 Sep 2023 10:02:13 +0200 Subject: [PATCH 6/8] chore: snake case publication state --- rfcs/xxxx-v5-database.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/xxxx-v5-database.md b/rfcs/xxxx-v5-database.md index 5ff1473..5d16133 100644 --- a/rfcs/xxxx-v5-database.md +++ b/rfcs/xxxx-v5-database.md @@ -33,7 +33,7 @@ Documents are introduced in v5 as a way to group multiple entries. That is imple Also, all the variations of that document will have its own column in every entry: - `locale` for i18n -- `publicationState` for draft and publish +- `publication_state` for draft and publish ## Document id and entry id From f3f0d85335aa81df3c922b8934581c07c37d9e1f Mon Sep 17 00:00:00 2001 From: Marc Roig Date: Fri, 8 Sep 2023 10:04:35 +0200 Subject: [PATCH 7/8] chore: snake case pivot publications tate --- rfcs/xxxx-v5-database.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/rfcs/xxxx-v5-database.md b/rfcs/xxxx-v5-database.md index 5d16133..84405d8 100644 --- a/rfcs/xxxx-v5-database.md +++ b/rfcs/xxxx-v5-database.md @@ -127,9 +127,10 @@ Links will be represented as so in the content type schema: The database schema of `links` join tables :

- +

+ The join table will now contain: - `Owner side doc id`: Reference to do the document id of the owner side (Article in the example) From 89b3db6f43e07d7245be6717d1d82e78715bc8d1 Mon Sep 17 00:00:00 2001 From: Marc Roig Date: Mon, 2 Oct 2023 10:12:37 +0200 Subject: [PATCH 8/8] fix: link join table references document ids --- rfcs/xxxx-v5-database.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/xxxx-v5-database.md b/rfcs/xxxx-v5-database.md index 84405d8..a2a91f4 100644 --- a/rfcs/xxxx-v5-database.md +++ b/rfcs/xxxx-v5-database.md @@ -127,7 +127,7 @@ Links will be represented as so in the content type schema: The database schema of `links` join tables :

- +