# Migrating your packaged OpenProject database to PostgreSQL **Note:** this guide only applies if you've installed OpenProject using our DEB/RPM packages. This guide will migrate your packaged MySQL installation to a PostgreSQL installation using [pgloader](https://github.com/dimitri/pgloader). ## Backing up Before beginning the migration, please ensure you have created a backup of your current installation. Please follow our [backup and restore documentation](https://www.openproject.org/operations/backup/backup-guide-packaged-installation/) for our packaged installation. This guide should leave you with a set of archives that you can use to restore, should the migration end up in an unstable state: - **Database**: mysql-dump-<timestamp>.sql.gz - **Attachments**: attachments-<timestamp>.tar.gz - **Custom env configuration**: conf-<timestamp>.tar.gz - **Repositories**: svn- and git-<timestamp>.tar.gz ## Installation of pgloader We ship a custom version of pgloader (named `pgloader-ccl`), which embeds some memory optimizations useful when you are migrating from a large MySQL database. This also allows us to provide a unified migration experience for all installation types. This package is available for all the currently supported distributions at https://packager.io/gh/opf/pgloader-ccl. There are some reports that the contained pgloader-ccl might fail with an internal error. We are not yet quite sure what is causing this, but you can alternative compile or provide your own pgloader (see https://pgloader.io for more information). To do that, set the environment variable `PGLOADER_PATH` to the absolute path of your provided pgloader. ### Ubuntu 18.04 ``` wget -qO- https://dl.packager.io/srv/opf/pgloader-ccl/key | sudo apt-key add - sudo wget -O /etc/apt/sources.list.d/pgloader-ccl.list \ https://dl.packager.io/srv/opf/pgloader-ccl/master/installer/ubuntu/18.04.repo sudo apt-get update sudo apt-get install pgloader-ccl ``` ### Ubuntu 16.04 ``` wget -qO- https://dl.packager.io/srv/opf/pgloader-ccl/key | sudo apt-key add - sudo wget -O /etc/apt/sources.list.d/pgloader-ccl.list \ https://dl.packager.io/srv/opf/pgloader-ccl/master/installer/ubuntu/16.04.repo sudo apt-get update sudo apt-get install pgloader-ccl ``` ### Debian 9 ``` wget -qO- https://dl.packager.io/srv/opf/pgloader-ccl/key | sudo apt-key add - sudo wget -O /etc/apt/sources.list.d/pgloader-ccl.list \ https://dl.packager.io/srv/opf/pgloader-ccl/master/installer/debian/9.repo sudo apt-get update sudo apt-get install pgloader-ccl ``` ### CentOS / RHEL 7 ``` sudo wget -O /etc/yum.repos.d/pgloader-ccl.repo \ https://dl.packager.io/srv/opf/pgloader-ccl/master/installer/el/7.repo sudo yum install pgloader-ccl ``` ### SuSE Enterprise Linux 12 ``` sudo wget -O /etc/zypp/repos.d/pgloader-ccl.repo \ https://dl.packager.io/srv/opf/pgloader-ccl/master/installer/sles/12.repo sudo zypper install pgloader-ccl ``` ## Optional: Install and create PostgreSQL database If you have not yet installed and set up a PostgreSQL installation database, please set up a PostgreSQL database now. OpenProject requires at least PostgreSQL 9.5 installed. Please check if your distributed package is too old. ```bash [root@host] apt-get install postgresql postgresql-contrib libpq-dev ``` Once installed, switch to the PostgreSQL system user. ```bash [root@host] su - postgres ``` Then, as the PostgreSQL user, create the system user for OpenProject. This will prompt you for a password. We are going to assume in the following guide that password were 'openproject'. Of course, please choose a strong password and replace the values in the following guide with it! ```bash [postgres@host] createuser -P -d openproject ``` Next, create the database owned by the new user ```bash [postgres@host] createdb -O openproject openproject ``` Lastly, exit the system user ```bash [postgres@host] exit # You will be root again now. ``` ## Set the MYSQL_DATABASE_URL to migrate from The following command saves the current MySQL `DATABASE_URL` as `MYSQL_DATABASE_URL` in the OpenProject configuration: ```bash openproject config:set MYSQL_DATABASE_URL="$(openproject config:get DATABASE_URL)" openproject config:get MYSQL_DATABASE_URL # Will output something of the kind # mysql2://user:password@localhost:3306/dbname ``` This will be used later by the migration script. ## Configuring OpenProject to use the PostgreSQL database Form the `DATABASE_URL` string to match your selected password and add it to the openproject configuration: ```bash openproject config:set DATABASE_URL="postgresql://openproject:@localhost/openproject" ``` **Please note:** Replace `` with the password you provided above. If you used any special characters, [check whether they need to be percent-encoded](https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding) for the database URL. You can use this command to escape any characters in the password: ```bash openproject run ruby -r cgi -e "puts CGI.escape('your-password-here');" ``` ## Migrating the database You are now ready to migrate from MySQL to PostgreSQL. The OpenProject packages embed a migration script that can be launched as follows: ``` sudo openproject run ./docker/mysql-to-postgres/bin/migrate-mysql-to-postgres ``` Make sure you stopped openproject service, otherwise you will get the following error: ``` ERROR: database "openproject" is being accessed by other users DETAIL: There is 1 other session using the database. ``` This might take a while depending on current installation size. ## Optional: Uninstall MySQL If the packaged installation auto-installed MySQL before and you no longer need it (i.e. only OpenProject used a MySQL database on your server), you can remove the MySQL packages. You can check the output of `dpkg -l | grep mysql` to check for packages to be removed. Only keep `libmysqlclient-dev` for Ruby dependencies on the mysql adapter. The following is an exemplary removal of an installed version MySQL 5.7. ``` [root@host] apt-get remove mysql-server [root@host] openproject config:unset MYSQL_DATABASE_URL ``` **Note:** OpenProject still depends on `mysql-common` and other dev libraries of MySQL to build the `mysql2` gem for talking to MySQL databases. Depending on what packages you try to uninstall, `openproject` will be listed as a dependent package to be uninstalled if trying to uninstall `mysql-common`. Be careful here with the confirmation of removal, because it might just remove openproject itself due to the apt dependency management. ## Running openproject reconfigure After you migrated your data, all you need to do is run through the configuration process of the packaged installation to remove the MySQL configuration ```bash openproject reconfigure ``` In the database installation screen, make sure to select `skip`. Keep all other values the same by simply confirming them by pressing `enter` . After the configuration process has run through, your OpenProject installation will be running on PostgreSQL!