Document how to convert a backup to PostgreSQL

2 files changed, 48 insertions, 0 deletions

diff --git a/CHANGELOG b/CHANGELOG
index d3561d2efc9..cc271f5e2cd 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -9,6 +9,7 @@ v 6.9.0
   - Improve comments loading logic
   - Stop refreshing comments when the tab is hidden
   - Improve issue and merge request mobile UI (Drew Blessing)
+  - Document how to convert a backup to PostgreSQL
 
 v 6.8.0
   - Ability to at mention users that are participating in issue and merge req. discussion
diff --git a/doc/update/mysql_to_postgresql.md b/doc/update/mysql_to_postgresql.md
index 9a324545eb0..cdef7d71e33 100644
--- a/doc/update/mysql_to_postgresql.md
+++ b/doc/update/mysql_to_postgresql.md
@@ -1,5 +1,9 @@
 # Use the shell commands below to convert a MySQL GitLab database to a PostgreSQL one.
 
+## Export from MySQL and import into Postgres
+
+Use this if you are keeping GitLab on the same server.
+
 ```
 git clone https://github.com/lanyrd/mysql-postgresql-converter.git
 cd mysql-postgresql-converter
@@ -7,3 +11,46 @@ mysqldump --compatible=postgresql --default-character-set=utf8 -r databasename.m
 python db_converter.py databasename.mysql databasename.psql
 psql -f databasename.psql -d gitlabhq_production
 ```
+
+## Converting a GitLab backup file from MySQL to Postgres
+
+GitLab backup files (<timestamp>_gitlab_backup.tar) contain a SQL dump.  Using
+the lanyrd database converter we can replace a MySQL database dump inside the
+tar file with a Postgres database dump. This can be useful if you are moving to
+another server.
+
+```
+# Stop GitLab
+sudo service gitlab stop
+
+# Create the backup
+cd /home/git/gitlab
+sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production
+
+# Note the filename of the backup that was created. We will call it
+# TIMESTAMP_gitlab_backup.tar below.
+
+# Move the backup file we will convert to its own directory
+sudo -u git -H mkdir -p tmp/backups/postgresql
+sudo -u git -H mv tmp/backups/TIMESTAMP_gitlab_backup.tar tmp/backups/postgresql/
+
+# Create a separate database dump with PostgreSQL compatibility
+cd tmp/backups/postgresql
+sudo -u git -H mysqldump --compatible=postgresql --default-character-set=utf8 -r gitlabhq_production.mysql -u root gitlabhq_production
+
+# Clone the database converter
+sudo -u git -H git clone https://github.com/lanyrd/mysql-postgresql-converter.git
+
+# Convert gitlabhq_production.mysql
+sudo -u git -H mkdir db
+sudo -u git -H python mysql-postgresql-converter/db_converter.py gitlabhq_production.mysql db/database.sql
+
+# Replace the MySQL dump in TIMESTAMP_gitlab_backup.tar.
+
+# Warning: if you forget to replace TIMESTAMP below, tar will create a new file
+# 'TIMESTAMP_gitlab_backup.tar' without giving an error.
+
+sudo -u git -H tar rf TIMESTAMP_gitlab_backup.tar db/database.sql
+
+# Done! TIMESTAMP_gitlab_backup.tar can now be restored into a Postgres GitLab installation.
+```