2018-12-03 19:01:32 +02:00
Changing the database back-end
==============================
2023-03-26 14:21:00 +02:00
By default Mailu uses a SQLite database. It is possible to use an alternative database solutions such as PostgreSQL and MySQL/MariaDB.
The Mailu database contains static data. SQLite is sufficient for any deployment scenario of Mailu. There is no need to use a different database system.
The Mailu development team recommends to use SQLite.
2018-12-03 19:01:32 +02:00
2021-11-23 18:13:31 +02:00
Migrating to a different database back-end
------------------------------------------
2018-12-03 19:01:32 +02:00
2021-11-23 18:13:31 +02:00
From Mailu 1.9, Mailu has a :ref: `cli command (link) <config-export>` for exporting and importing the complete Mailu configuration.
Using this tool it is very easy to switch what database back-end is used for Mailu.
2021-11-25 22:50:17 +02:00
Unfortunately roundcube does not have a tool for exporting/importing its configuration.
2021-11-23 18:13:31 +02:00
This means it is not possible to switch the database back-end used by roundcube using out of box tools.
2018-12-03 19:01:32 +02:00
2021-11-23 18:13:31 +02:00
To switch to a different database back-end:
2018-12-03 19:01:32 +02:00
2023-05-06 19:05:37 +02:00
1. Run config-export to export the configuration. E.g. `docker compose exec admin flask mailu config-export --secrets --output /data/mail-config.yml`
2023-06-23 14:34:22 +02:00
2. Set up your new database server. Refer to the subsequent sections for tips for creating the database.
2023-03-26 14:21:00 +02:00
3. Modify the database settings (SQLAlchemy database URL) in mailu.env. Refer to the :ref: `configuration guide (link) <db_settings>` for the exact settings.
2021-11-23 18:13:31 +02:00
4. Start your Mailu deployment.
2023-05-06 19:05:37 +02:00
5. Run config-import to import the configuration...
1. Drop into a shell inside the admin container as you'll need to execute multiple commands. E.g. `docker exec -i $(docker compose ps -q admin) bash`
2023-10-20 09:20:30 +02:00
2. Initialize the new database back-end: `flask mailu db init`
2023-05-06 19:05:37 +02:00
2023-10-20 09:20:30 +02:00
3. Migrate the new database back-end to the current state: `flask mailu db upgrade`
2023-05-06 19:05:37 +02:00
4. Import the configuration export: `flask mailu config-import -v < /data/mail-config.yml`
2021-11-23 18:13:31 +02:00
Mailu has now been switched to the new database back-end. The Mailu configuration has also been migrated.
2018-12-03 19:01:32 +02:00
2021-11-23 18:13:31 +02:00
External MySQL/MariaDB
----------------------
It is also possible to use a MySQL/MariaDB database server, hosted elsewhere.
In this case you'll have to take to create an empty database for Mailu, corresponding user,
password and sufficient privileges on the database to `` CREATE TABLE `` , `` DROP `` etc.
Usually making the user owner of the database would be the easiest thing to do.
The following commands can serve as an example on how to set up MySQL/MariaDB for Mailu usage.
Adjust this to your own liking.
.. code-block :: sql
2018-12-03 19:01:32 +02:00
2021-11-23 18:13:31 +02:00
mysql> CREATE DATABASE mailu;
2021-11-25 22:50:17 +02:00
mysql> CREATE USER `mailu` @`%` IDENTIFIED WITH mysql_native_password BY `my-strong-password-here` ;
2021-11-23 18:13:31 +02:00
mysql> GRANT ALL PRIVILEGES ON mailu.* TO 'mailu'@'%';
mysql> FLUSH PRIVILEGES;
External PostgreSQL
2018-12-03 19:01:32 +02:00
-------------------
2021-11-23 18:13:31 +02:00
It is also possible to use a PostgreSQL database server, hosted elsewhere.
2018-12-03 19:01:32 +02:00
In this case you'll have to take to create an empty database for Mailu, corresponding user,
password and sufficient privileges on the database to `` CREATE TABLE `` , `` DROP `` etc.
Usually making the user owner of the database would be the easiest thing to do.
Don't forget to set `` pg_hba.conf `` accordingly.
2021-11-23 18:13:31 +02:00
The following commands can serve as an example on how to set up PostgreSQL for Mailu usage.
2018-12-03 19:01:32 +02:00
Adjust this to your own liking.
.. code-block :: bash
$ sudo su - postgres
$ psql
psql (10.6)
Type "help" for help.
postgres=# create user mailu;
CREATE ROLE
postgres=# alter user mailu password 'my_secure_pass';
ALTER ROLE
postgres=# create database mailu owner mailu;
CREATE DATABASE
postgres=# \c mailu
You are now connected to database "mailu" as user "postgres".
mailu=# create extension citext;
CREATE EXTENSION
mailu=# \q
In `` pg_hba.conf `` there should be a line like this:
.. code-block :: bash
host mailu mailu <mailu_host>/32 md5
2023-03-26 14:21:00 +02:00
Note that this example is the bare-minimum to get Mailu working. Additional work needs to be
2022-07-26 11:33:39 +02:00
done by the database admin to setup their own means of backups and TLS encrypted connections.
2019-01-10 17:58:33 +02:00
2021-11-23 18:13:31 +02:00
Nowadays it is recommended to use the official PostgreSQL image from the PostgreSQL community. The repository is located `here <https://hub.docker.com/_/postgres> `_ .
2019-01-10 17:58:33 +02:00
2021-11-23 18:13:31 +02:00
.. _migrate_mailu_postgresql:
2019-01-10 17:58:33 +02:00
2021-11-23 18:13:31 +02:00
Mailu PostgreSQL
----------------
2019-01-10 17:58:33 +02:00
2021-11-23 18:13:31 +02:00
Mailu optionally came with a pre-configured PostgreSQL image which was deprecated in Mailu 1.8.
2023-03-26 14:21:00 +02:00
Since Mailu 1.9 it is removed from Mailu. The following section describes how to move to a different
2022-07-26 11:33:39 +02:00
PostgreSQL image for novice administrators. The official PostgreSQL image (Postgres) will be used.
2019-01-10 17:58:33 +02:00
2023-03-26 14:21:00 +02:00
A Mailu deployment with the Mailu PostgreSQL image, will only use PostgreSQL for the Admin container
2022-07-26 11:33:39 +02:00
(Web administration interface). Roundcube uses SQLite as database back-end.
2021-11-23 18:13:31 +02:00
Mailu uses the following configuration for connecting to the database:
2019-01-10 17:58:33 +02:00
2021-11-23 18:13:31 +02:00
- Database host: 'database'
- Database name: 'mailu'
- Database user: 'mailu'
- Database password: See DB_PW in mailu.env.
2019-01-10 17:58:33 +02:00
2021-11-23 18:13:31 +02:00
.. note ::
The following instructions assume that
- project mailu is used. (-p mailu). If a different project (prefix) is used, then a different project can be specified.
- the data folder is /mailu. Change this to a different value in case Mailu makes use of a different data folder.
- All commands must be executed as root. On Debian/Ubuntu the sudo command is used to execute commands as root.
Prepare the environment. Mailu must not be in use. Only the database container.
1. Open a terminal.
2. `cd /mailu`
2023-02-15 11:00:03 +02:00
3. `docker compose -p mailu down`
4. `docker compose -p mailu up -d database`
2021-11-23 18:13:31 +02:00
Create the dump SQL file for recreating the database.
2023-02-15 11:00:03 +02:00
1. `docker compose -p mailu exec database /bin/bash`
2021-11-23 18:13:31 +02:00
2. `pg_dump -h database -p 5432 -U mailu > /backup/backup_db.sql`
3. Enter the password. See the value of DB_PW in mailu.env.
4. `exit`
5. The dump is saved to /mailu/data/psql_backup/backup_db.sql.
2023-02-15 11:00:03 +02:00
6. `docker compose -p mailu down`
2021-11-23 18:13:31 +02:00
Prepare the new PostgreSQL deployment.
1. `mkdir -p /mailu/data/external_psql/pgdata`
2023-02-15 11:00:03 +02:00
2. Create the file docker compose-postgresql.yml with the following contents:
2021-11-23 18:13:31 +02:00
.. code-block :: docker
version: '3.1'
services:
database:
image: postgres:13
restart: always
environment:
- POSTGRES_USER=mailu
- POSTGRES_PASSWORD=DB_PW from mailu.env file
- PGDATA=/var/lib/postgresql/data/pgdata
volumes:
- "/mailu/data/external_psql/pgdata:/var/lib/postgresql/data/pgdata"
- "/mailu/data/psql_backup:/dump"
2023-02-15 11:00:03 +02:00
3. `docker compose -f docker compose-postgresql.yml up -d`
4. `docker compose -f docker compose-postgresql.yml exec database /bin/bash`
2021-11-23 18:13:31 +02:00
5. `cat /dump/backup_db.sql | psql -h localhost -p 5432 -U mailu`
6. `exit`
2023-02-15 11:00:03 +02:00
7. `docker compose -f docker compose-postgresql.yml down`
8. Remove the file docker compose-postgresql.yml.
2021-11-23 18:13:31 +02:00
The new PostgreSQL deployment has the dump loaded now. Now it is time to modify Mailu to use the official PostgreSQL docker image.
1. Edit docker-compose.yml and change:
.. code-block :: docker
database:
image: ${DOCKER_ORG:-mailu}/${DOCKER_PREFIX:-}postgresql:${MAILU_VERSION:-master}
restart: always
env_file: mailu.env
volumes:
- "/mailu_db/data/psql_db:/data"
- "/mailu_db/data/psql_backup:/backup"
to
.. code-block :: docker
database:
image: postgres:13
restart: always
environment:
- PGDATA=/var/lib/postgresql/data/pgdata
volumes:
- "/mailu/data/external_psql/pgdata:/var/lib/postgresql/data/pgdata"
2. Edit mailu.env and append the following after the block
.. code-block :: docker
###################################
# Database settings
###################################
.. code-block :: docker
2023-03-26 14:21:00 +02:00
SQLALCHEMY_DATABASE_URI=postgresql://mailu:mailu@database/mailu
2021-11-23 18:13:31 +02:00
Mailu is now configured to use the official PostgreSQL docker image. Bring your new deployment online
2023-02-15 11:00:03 +02:00
1. `docker compose -p mailu up -d`
2021-11-23 18:13:31 +02:00
Optionally you can remove left-over files which were used by the old database:
- /mailu/data/psql_backup (old database backup files
- /mailu/data/psql_db (old database files)
.. note ::
Roundcube does not offer a migration tool for moving from SQLite to PostgreSQL.
2023-10-20 09:20:30 +02:00
In case roundcube is used, the Mailu setup utility can be used to specify SQLite for the roundcube database back-end.