Add database migration guides for components

docs/3.0.0-beta.x/migration-guide/migration-guide-beta.17-to-beta.18.md

@@ -2,6 +2,8 @@
 
 Upgrading your Strapi application to `v3.0.0-beta.18`.
 
+**Make sure your server is not running until then end of the migration**
+
 ## Upgrading your dependencies
 
 Start by upgrading your dependencies. Make sure to use exact versions.
@@ -228,6 +230,220 @@ Now that you have moved your component into categories. You need to update your
 }
 ```
 
+### Database migration of groups
+
+::: warning
+Make sure to do a database backup before your migration.
+:::
+
+Those migration are only necessary if you have data in production. Otherwise you should simply recreate your db.
+To keep your preferences you can backup the `core_store` table data.
+
+#### Bookshelf
+
+Some database changes have occured:
+
+- Component join tables have been renamed from `{content_type}_groups` to `{content_type}_components`.
+- Component join tables column `group_type` is renamed to `component_type`.
+- Component join tables column `group_id` is renamed to `component_id`.
+
+**Migration queries**
+
+Make sure to run those queries for the tables that exist in your database.
+
+_`Queries for a Restaurant content type`_
+:::: tabs
+
+::: tab Sqlite
+
+```sql
+-- renaming the table
+ALTER TABLE restaurants_groups
+RENAME TO restaurants_components;
+
+-- renaming the columns
+ALTER TABLE restaurants_components
+RENAME COLUMN group_type to component_type;
+
+ALTER TABLE restaurants_components
+RENAME COLUMN group_id to component_id;
+```
+
+:::
+
+::: tab Postgres
+
+```sql
+-- renaming the table
+ALTER TABLE restaurants_groups
+RENAME TO restaurants_components;
+
+-- renaming the columns
+ALTER TABLE restaurants_components
+RENAME COLUMN group_type to component_type;
+
+ALTER TABLE restaurants_components
+RENAME COLUMN group_id to component_id;
+```
+
+:::
+
+::: tab Mysql
+
+```sql
+-- renaming the table
+RENAME TABLE restaurants_groups TO restaurants_components;
+
+
+-- renaming the columns
+ALTER TABLE restaurants_components
+RENAME COLUMN group_type to component_type;
+
+ALTER TABLE restaurants_components
+RENAME COLUMN group_id to component_id;
+```
+
+:::
+
+::::
+
+---
+
+You might notice that you still have some tables containg the `group` keyword. Those are the tables that contain the groups data.
+
+If you want to rename them you have 3 steps to follow:
+
+**1. Rename the table in your DB (you can use the table renaming query shown above).**
+
+:::: tabs
+::: tab Sqlite
+
+```sql
+ALTER TABLE groups_old_table_name
+RENAME TO components_new_table_name;
+```
+
+:::
+::: tab Postgres
+
+```sql
+ALTER TABLE groups_old_table_name
+RENAME TO components_new_table_name;
+```
+
+:::
+::: tab Mysql
+
+```sql
+-- renaming the table
+RENAME TABLE groups_old_table_name TO components_new_table_name;
+```
+
+:::
+::::
+
+**2. Change the `collectionName` of the component**
+
+**Before**
+`./api/components/category/component.json`
+
+```json
+{
+  "collectionName": "groups_old_table_name"
+  //...
+}
+```
+
+**After**
+`./api/components/category/component.json`
+
+```json
+{
+  "collectionName": "components_new_table_name"
+  //....
+}
+```
+
+**3. Update the `component_type` values in the join tables**
+
+_Repeat this query for every join table where you are using this component._
+
+```sql
+UPDATE restaurant_components
+SET component_type = 'groups_old_table_name'
+WHERE component_type = 'components_new_table_name';
+```
+
+#### Mongo
+
+In `mongo` the relation between a content type and its components is held in an array of references. To know which component type it referes to, the array also contains a `kind` attribute containing the component Schema name.
+
+**How to migrate**
+
+**1. Get your new global ids**
+
+The `kind` attribute references the Strapi `globalId` of a model. To get your component global ids run:
+
+```sh
+strapi console
+```
+
+```js
+Object.keys(strapi.components).map(key => strapi.components[key].globalId);
+//[
+// 'ComponentCategoryMyComponent',
+// 'ComponentCategoryMyOtherComponent',
+//]
+```
+
+**2. Rename the component collections**
+
+```js
+// renaming a collection groups_my_group
+db.collection.renameCollection('groups_my_group', 'components_my_component');
+```
+
+**3. Change the `collectionName` of the component**
+
+**Before**
+`./api/components/category/component.json`
+
+```json
+{
+  "collectionName": "groups_old_table_name"
+  //...
+}
+```
+
+**After**
+`./api/components/category/component.json`
+
+```json
+{
+  "collectionName": "components_new_table_name"
+  //....
+}
+```
+
+**4. Rename the `kind` attributes**
+
+To know the old `kind` name of a group here is the function that creates it:
+
+```js
+toGlobalId = name => upperFirst(camelCase(`group_${name}`));
+// my-group => GroupMyGroup
+```
+
+**Query to update the kind for on filed in one contentType**:
+
+```js
+db.getCollection('contentTypeCollection').update(
+  { 'componentField.kind': 'GroupsMyGroup' },
+  { $set: { 'componentField.$.kind': 'ComponentCategoryMyComponent' } },
+  { multi: true }
+);
+```
+
 ## Rebuilding your administration panel
 
 Now delete the `.cache` and `build` folders. Then run `yarn develop`.