From 40f53fdeb0e702b93d4dce204792c6e66145eaa5 Mon Sep 17 00:00:00 2001
From: rijkvanzanten <rijkvanzanten@me.com>
Date: Mon, 15 Mar 2021 17:18:02 -0400
Subject: [PATCH] Add (basic) migration guide

Fixes #3560
---
 docs/.vuepress/config.js         |  8 ++++
 docs/guides/migrating-from-v8.md | 66 ++++++++++++++++++++++++++++++++
 2 files changed, 74 insertions(+)
 create mode 100644 docs/guides/migrating-from-v8.md

diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
index b133be96ff..73e6c22b93 100755
--- a/docs/.vuepress/config.js
+++ b/docs/.vuepress/config.js
@@ -200,6 +200,14 @@ module.exports = {
 			{
 				title: 'Guides',
 				children: [
+					{
+						type: 'page',
+						path: '/guides/migrating-from-v8',
+						title: 'Migrating from v8',
+					},
+					{
+						type: 'divider',
+					},
 					{
 						type: 'page',
 						path: '/guides/api-config',
diff --git a/docs/guides/migrating-from-v8.md b/docs/guides/migrating-from-v8.md
new file mode 100644
index 0000000000..c456355f88
--- /dev/null
+++ b/docs/guides/migrating-from-v8.md
@@ -0,0 +1,66 @@
+# Migrating from v8
+
+There's two ways to migrate from an existing v8 instance:
+
+- [Automated Script](#automated-script) (recommended)
+- [Manual Database Export/Import](#manual-database-export-import)
+
+## Automated Script
+
+We created a (community maintained) script, that will automatically copy over the schema, content, files, users, and
+roles from an existing v8 instance to a new v9 instance. This is the most hands-off approach to moving from a v8 to a v9
+instance, and is the recommended way of migrating your v8 instance.
+
+::: tip
+
+The script, and instructions on how to run it, can be found on the\
+[`directus-community/migration-tool`](https://github.com/directus-community/migration-tool) repo.
+
+:::
+
+This tool will copy over:
+
+- Schema (collections / fields)
+- Files (including file contents)
+- User data (eg all items in all collections)
+- Roles
+- Users
+
+This tool will NOT copy over:
+
+- Interface/display configurations
+- Permissions
+- Activity / revisions
+
+## Manual Database Export/Import
+
+::: warning Automated
+
+We highly recommend using the automated migration tool mentioned above. If that's not possible, you can perform the
+following steps to migrate your v8 instance.
+
+:::
+
+Directus v9 is a breaking change coming from v8 (hence the major version bump), so you won't be able to just use your
+existing v8 database and run v9 on top of it. However, due to the database-mirroring approach of Directus, it's fairly
+straightforward to migrate your content from v8 to v9.
+
+#### 1) Setup a Fresh v9 Instance
+
+By installing Directus "fresh", you're ensured your system tables are up-to-date and ready to go.
+
+#### 2) Migrate your Data
+
+Using a tool like [Sequel Pro](http://sequelpro.com) or [TablePlus](https://tableplus.com), export your v8 user-tables
+and import them into your v9 database.
+
+Directus v9 will automatically recognize your tables, and you'll be ready to get started in v9.
+
+**Note:** If you have references to users and files, make sure to update them to the new UUID format.
+
+#### 3) Configure Directus
+
+Once the tables are in, you can start configuring the details of the schema. This includes choosing the correct
+interfaces, displays, and their options for your fields.
+
+This would also be a good time to reconfigure your permissions, to ensure they are what you need them to be.