docs: Add DB migration docs

docs/database_migration.md

@@ -0,0 +1,57 @@
+# 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](https://github.com/dimitri/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 a dump of existing data.
+2. Change all `CREATE TABLE ...` lines to `DELETE FROM tablename;`. We will later have LLDAP create the schema for us, so we want to clear out existing data to replace it with the original data.
+3. Do any syntax fixes for the target db syntax
+4. Change your LLDAP config database_url to point to the new target and restart.
+5. After LLDAP has started, stop it.
+6. Execute the manicured dump file against the new database.
+
+The steps below assume you already have PostgreSQL or MySQL set up with an empty database for LLDAP to use.
+
+## Create a dump
+
+First, we must dump the existing data to a file. The dump must be tweaked slightly according to your target db. See below for commands
+
+### PostgreSQL
+
+PostgreSQL uses a different hex string format and doesn't support `PRAGMA`.
+
+```
+sqlite3 /path/to/lldap/config/users.db .dump | \
+sed -r -e "s/X'([[:xdigit:]]+'[^'])/'\\\x\\1/g" \
+-e 's/^CREATE TABLE IF NOT EXISTS "([^"]*)".*/DELETE FROM \1;/' \
+-e '/^PRAGMA.*/d' > /path/to/dump.sql
+```
+
+### MySQL
+
+MySQL doesn't support `PRAGMA`.
+
+```
+sqlite3 /path/to/lldap/config/users.db .dump | \
+-e 's/^CREATE TABLE IF NOT EXISTS "([^"]*)".*/DELETE FROM \1;/' \
+-e '/^PRAGMA.*/d' > /path/to/dump.sql
+```
+
+## Generate New Schema
+
+Modify your `database_url` in `lldap_config.toml` (or `LLDAP_DATABASE_URL` in the env) to point to your new database. Restart LLDAP and check the logs to ensure there were no errors connecting and creating the tables. After that, stop LLDAP. Now we can import our original data!
+
+### PostgreSQL
+
+`psql -d <database> -U <username> -W < /path/to/dump.sql`
+
+### MySQL
+
+`mysql -u < -p <database> < /path/to/dump.sql`
+
+## Finish
+
+If all succeeds, you're all set to start LLDAP with your new database!

lldap_config.docker_template.toml

@@ -75,16 +75,16 @@
 #ldap_user_pass = "REPLACE_WITH_PASSWORD"
 
 ## Database URL.
-## This encodes the type of database (SQlite, Mysql and so
+## This encodes the type of database (SQlite, MySQL, or PostgreSQL)
-## on), the path, the user, password, and sometimes the mode (when
+## , the path, the user, password, and sometimes the mode (when
 ## relevant).
-## Note: Currently, only SQlite is supported. SQlite should come with
+## Note: SQlite should come with "?mode=rwc" to create the DB
-## "?mode=rwc" to create the DB if not present.
+## if not present.
 ## Example URLs:
 ##  - "postgres://postgres-user:password@postgres-server/my-database"
 ##  - "mysql://mysql-user:password@mysql-server/my-database"
 ##
-## This can be overridden with the DATABASE_URL env variable.
+## This can be overridden with the LLDAP_DATABASE_URL env variable.
 database_url = "sqlite:///data/users.db?mode=rwc"
 
 ## Private key file.