WIP, document how to use pgloader2799-mysql-to-postgresql-docs

1 files changed, 55 insertions, 17 deletions

diff --git a/doc/update/mysql_to_postgresql.md b/doc/update/mysql_to_postgresql.md
index a7de5648c0e..843c66cdaba 100644
--- a/doc/update/mysql_to_postgresql.md
+++ b/doc/update/mysql_to_postgresql.md
@@ -1,36 +1,74 @@
-# Migrating GitLab from MySQL to Postgres
+# Migrating GitLab from MySQL to PostgreSQL
 *Make sure you view this [guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/update/mysql_to_postgresql.md#migrating-gitlab-from-mysql-to-postgres) for the most up to date instructions.*
 
-If you are replacing MySQL with Postgres while keeping GitLab on the same server all you need to do is to export from MySQL, convert the resulting SQL file, and import it into Postgres. If you are also moving GitLab to another server, or if you are switching to omnibus-gitlab, you may want to use a GitLab backup file. The second part of this documents explains the procedure to do this.
+If you are replacing MySQL with PostgreSQL while keeping GitLab on the same
+server, all you need to do is to prepare a fresh PostgreSQL database with
+up-to-date schema, and use [pgloader][] to migrate the data from MySQL to
+PostgreSQL. If you are also moving GitLab to another server, or if you are
+switching to omnibus-gitlab, you may want to use a GitLab backup file.
+The second part of this documents explains the procedure to do this.
 
-## Export from MySQL and import into Postgres
+[pgloader]: http://pgloader.io/
 
-Use this if you are keeping GitLab on the same server.
+## Keeping GitLab on the same server
 
-```
-sudo service gitlab stop
+### Prepare a fresh PostgreSQL database
 
-# Update /home/git/gitlab/config/database.yml
+Before we start, we should stop the service:
 
-git clone https://github.com/gitlabhq/mysql-postgresql-converter.git -b gitlab
-cd mysql-postgresql-converter
-mysqldump --compatible=postgresql --default-character-set=utf8 -r gitlabhq_production.mysql -u root gitlabhq_production -p
-python db_converter.py gitlabhq_production.mysql gitlabhq_production.psql
-ed -s gitlabhq_production.psql < move_drop_indexes.ed
+``` bash
+sudo service gitlab stop
+```
 
-# Import the database dump as the application database user
-sudo -u git psql -f gitlabhq_production.psql -d gitlabhq_production
+Update `/home/git/gitlab/config/database.yml` and point it to the PostgreSQL
+database you're going to use. Run the following commands to prepare schema:
 
-# Install gems for PostgreSQL (note: the line below states '--without ... mysql')
+``` bash
+# Install gems for PostgreSQL
+# Note: the line below states '--without ... mysql'
 sudo -u git -H bundle install --without development test mysql --deployment
 
+# Prepare the schema
+sudo gitlab-rake db:create db:migrate
+```
+
+### Migrate data from MySQL to PostgreSQL
+
+Now we could start using [pgloader][] to migrate the data from MySQL to
+PostgreSQL. **Please install pgloader X.Y.Z** and use the following pgloader
+command to migrate the data:
+
+```
+LOAD DATABASE
+  FROM ...
+  INTO ...
+
+WITH ...
+
+CAST ...
+
+ALTER SCHEMA '...' RENAME TO 'public'
+
+;
+```
+
+Save the above command (in `commands.load` for example) and edit with your
+database host and credentials. Then you could start migrating by running:
+
+``` bash
+pgloader commands.load # Or whatever file you saved the commands
+```
+
+After it's done, you could start the service again and verify the result:
+
+``` bash
 sudo service gitlab start
 ```
 
-## Converting a GitLab backup file from MySQL to Postgres
+## Converting a GitLab backup file from MySQL to PostgreSQL
 **Note:** Please make sure to have Python 2.7.x (or higher) installed.
 
-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.
+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 PostgreSQL database dump. This can be useful if you are moving to another server.
 
 ```
 # Stop GitLab