lldap/docs/database_migration.md

Migration

Existing servers can migrate from one database backend to another. This page includes guidance for migrating from SQLite - similar concepts apply when migrating from databases of other types.

NOTE: pgloader is a tool that can easily migrate to PostgreSQL from other databases. Consider it if your target database is PostgreSQL

The process is as follows:

1. Create empty schema on target database
2. Dump existing values
3. Sanitize for target DB (not always required)
4. Insert data into target
5. Change LLDAP config to new target

The steps below assume you already have PostgreSQL or MySQL set up with an empty database for LLDAP to use.

Create schema on target

LLDAP has a command that will connect to a target database and initialize the schema. If running with docker, run the following command to use your active instance (this has the benefit of ensuring your container has access):

docker exec -it <LLDAP container name> /app/lldap create_schema -d <Target database url>

If it succeeds, you can proceed to the next step.

Create a dump of existing data

We want to dump all existing values to some file. The dump should consist just INSERT statements. There are various ways to do this, but a simple enough way is filtering a whole database dump. For example:

sqlite3 /path/to/lldap/config/users.db .dump | grep "^INSERT" > /path/to/dump.sql

Sanitize data (if needed)

Some databases might use different formats for some data - for example, PostgreSQL uses a different syntax for hex strings than SQLite.

To PostgreSQL

PostgreSQL uses a different hex string format. The command below should switch SQLite format to PostgreSQL format.

sed -i -r "s/X'([[:xdigit:]]+'[^'])/'\\\x\\1/g" /path/to/dump.sql

Insert data

Insert the data generated from the previous step into the target database.

PostgreSQL

psql -d <database> -U <username> -W < /path/to/dump.sql

MySQL

mysql -u < -p <database> < /path/to/dump.sql

Switch to new database

Modify your database_url in lldap_config.toml (or LLDAP_DATABASE_URL in the env) to point to your new database (the same value used when generating schema). Restart LLDAP and check the logs to ensure there were no errors.