diff --git a/CHANGELOG b/CHANGELOG index d3561d2efc94ab3baca0962ccd93e3ae1b899a51..cc271f5e2cd17109dac21eb46ab94faf44cca18d 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 9a324545eb0ae373fe26a04e329206f033a55813..5b9209d7df4f87794a2a24e70f30b5206cc7f1e7 100644 --- a/doc/update/mysql_to_postgresql.md +++ b/doc/update/mysql_to_postgresql.md @@ -1,9 +1,68 @@ -# Use the shell commands below to convert a MySQL GitLab database to a PostgreSQL one. +# Migrating GitLab from MySQL to Postgres + +If you are replacing MySQL with Postgres while keeping GitLab on the same +server all you need to do is to export from MySQL and import into Postgres as +described below. 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 + +Use this if you are keeping GitLab on the same server. ``` +sudo service gitlab stop + +# Update /home/git/gitlab/config/database.yml + git clone https://github.com/lanyrd/mysql-postgresql-converter.git cd mysql-postgresql-converter mysqldump --compatible=postgresql --default-character-set=utf8 -r databasename.mysql -u root gitlabhq_production python db_converter.py databasename.mysql databasename.psql psql -f databasename.psql -d gitlabhq_production + +sudo service gitlab start +``` + +## 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. ```