From fe17ce215087eca25204719efbd922c5dd0423de Mon Sep 17 00:00:00 2001
From: Hypolite Petovan <mrpetovan@gmail.com>
Date: Wed, 5 Oct 2016 16:39:37 -0400
Subject: [PATCH] Add upgrade documentation

---
 doc/upgrade.md | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)
 create mode 100644 doc/upgrade.md

diff --git a/doc/upgrade.md b/doc/upgrade.md
new file mode 100644
index 0000000000..778f9355e6
--- /dev/null
+++ b/doc/upgrade.md
@@ -0,0 +1,34 @@
+# Considerations before upgrading Friendica
+
+* [Home](help)
+
+## MySQL >= 5.7.4
+
+Starting from MySQL version 5.7.4, the IGNORE keyword in ALTER TABLE statements is ignored.
+This prevents automatic table deduplication if a UNIQUE index is added to a Friendica table's structure.
+If a DB update fails for you while creating a UNIQUE index, make sure to manually deduplicate the table before trying the update again.
+
+### Manual deduplication
+
+There are two main ways of doing it, either by manually removing the duplicates or by recreating the table.
+Manually removing the duplicates is usually faster if they're not too numerous.
+To manually remove the duplicates, you need to know the UNIQUE index columns available in `database.sql`.
+
+```SQL
+SELECT GROUP_CONCAT(id), <index columns>, count(*) as count FROM users
+GROUP BY <index columns> HAVING count >= 2;
+
+/* delete or merge duplicate from above query */;
+```
+
+If there are too many rows to handle manually, you can create a new table with the same structure as the table with duplicates and insert the existing content with INSERT IGNORE.
+To recreate the table you need to know the table structure available in `database.sql`.
+
+```SQL
+CREATE TABLE <table_name>_new <rest of the CREATE TABLE>;
+INSERT IGNORE INTO <table_name>_new SELECT * FROM <table_name>;
+DROP TABLE <table_name>;
+RENAME TABLE <table_name>_new TO <table_name>;
+```
+
+This method is slower overall, but it is better suited for large numbers of duplicates.
\ No newline at end of file