openproject/help/installation-and-operations/manual/postgresql-migration.md

# Migrating your manual-installation OpenProject database to PostgreSQL

This guide will migrate your MySQL installation on a manual 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-manual-installation/) for Docker-based installations.



## Set up a PostgreSQL database

Please first set up a PostgreSQL database. These are generic apt-based installation steps, please adapt them appropriately for your distribution.

OpenProject requires at least PostgreSQL 9.5 installed. Please check <https://www.postgresql.org/download/> 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 -W 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.
```



## The MYSQL_DATABASE_URL

Note down or copy the current MySQL `DATABASE_URL`. The following command exports it to the curent shell as `MYSQL_DATABASE_URL`:

```bash
# Will look something something of the kind
# mysql2://user:password@localhost:3306/dbname

# Pass into the container but replace mysql2 with mysql!
export MYSQL_DATABASE_URL="mysql://user:password@localhost:3306/dbname"
```



**Please note:** Ensure that the URL starts with `mysql://` , not with ` mysql2://` !



## The PostgreSQL DATABASE_URL

Pass in `DATABASE_URL` pointing to your new PostgreSQL database. Fill the template below with the password you entered above.

```bash
export POSTGRES_DATABASE_URL="postgresql://openproject:<PASSWORD>@localhost/openproject"
```

## Running the migration via Docker

OpenProject provides a simple conversion script that you can run as a single command via Docker.

To run the migration script within the container, simply run the following command, replacing the content of the environment variables with your actual values.


### Adapting the hostname

**Note:** Depending on your docker installation and networking, you may need to replace the hostname `localhost` in the database URLs
with `host.docker.internal` to access the docker host. On Mac for example, localhost will refer to the docker client.


```bash
docker run -it \
  -e MYSQL_DATABASE_URL=$MYSQL_DATABASE_URL \
  -e DATABASE_URL=$POSTGRES_DATABASE_URL \
  openproject/community:latest
```


This will perform all necessary steps to perform the migration. Afterwards, simply remove the `MYSQL_DATABASE_URL`environment variable again and start your container as usual.



## Running the migration without Docker

### Installation of pgloader



#### Apt Systems

For systems with APT package managers (Debian, Ubuntu), you should already have `pgloader` available and can install as root with with:

```
[root@host] apt-get install pgloader
```



[For other installations, please see the project page itself for steps on installing with Docker or from source](https://github.com/dimitri/pgloader#install).



After installation, check that pgloader is in your path and accessible:



```
[root@host] pgloader --version

# Should output something of the kind
pgloader version "3.5.2"
compiled with SBCL 1.4.5.debian
```



### Performing the migration

You are now ready to use `pgloader`. You simply point it the old and new database URL while specifying the option
`--with "preserve index names"` which ensures that index names are kept identical.

```bash
pgloader --verbose --with "preserve index names" $MYSQL_DATABASE_URL $POSTGRES_DATABASE_URL
```

This might take a while depending on current installation size.

### Index attachments for fulltext search

One of the benefits of using PostgreSQL over MySql is the support for fulltext search on attachments. The fulltext search feature relies on the existence of two additional columns for attachments that need to be added now ff the migration to PostgreSql is done for an OpenProject >= **8.0**. If the OpenProject version is below **8.0** the next two commands can be skipped.

In order to add the necessary columns to the database, run

```bash
openproject run rails db:migrate:redo VERSION=20180122135443
```

After the columns have been added, the index has to be created for already uploaded attachments

```bash
openproject run rails attachments:extract_fulltext_where_missing
```

If a large set of attachments already exists, executing the command might take a while.



### Indexes on relations table

You will also need to rebuild the index on the relations table. Simply run the following command
to re-run the migration.

```bash
openproject run rails db:migrate:redo VERSION=20180105130053
```



## Optional: Uninstall MySQL

If you installed MySQL only for the installation of OpenProject, evaluate whether you want to remove MySQL server.

You can check the output of `dpkg - l | grep mysql` to check for packages removable. 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
```