Database Maintenance

Server Migration

There are three methods available to migrate your Kanidm instance between servers.

Backup/Restore

1. Ensure the original server is stopped.
2. Backup on the original server.
3. Restore the data on the new server.
4. Start the new server.

Data Copy

1. Ensure the original server is stopped.
2. Copy the full content of your kanidmd volume to the new server.
3. Start the new server with the same docker arguments.

Replication

1. Create a new server.
2. Configure replication between the new and original server.
3. Ensure that that the initial refresh is complete.
4. Stop the original server.

Reindexing

In some (rare) cases you may need to reindex. Please note the server will sometimes reindex on startup as a result of the project changing its internal schema definitions. This is normal and expected - you may never need to start a reindex yourself as a result!

You only need to reindex if you add custom schema elements and you see a message in your logs such as:

Index EQUALITY name not found
Index {type} {attribute} not found

This indicates that an index of type equality has been added for name, but the indexing process has not been run. The server will continue to operate and the query execution code will correctly process the query - however it will not be the optimal method of delivering the results as we need to disregard this part of the query and act as though it’s un-indexed.

Reindexing will resolve this by forcing all indexes to be recreated based on their schema definitions.

docker stop <container name>
docker run --rm -i -t -v kanidmd:/data \
    kanidm/server:latest /sbin/kanidmd database reindex -c /data/server.toml
docker start <container name>

Vacuum

Vacuuming is the process of reclaiming un-used pages from the database freelists, as well as performing some data reordering tasks that may make some queries more efficient. It is recommended that you vacuum after a reindex is performed or when you wish to reclaim space in the database file.

Vacuum is also able to change the pagesize of the database. After changing db_fs_type (which affects pagesize) in server.toml, you must run a vacuum for this to take effect:

docker stop <container name>
docker run --rm -i -t -v kanidmd:/data \
    kanidm/server:latest /sbin/kanidmd database vacuum -c /data/server.toml
docker start <container name>

Verification

The server ships with a number of verification utilities to ensure that data is consistent such as referential integrity or memberof.

Note that verification really is a last resort - the server does a lot to prevent and self-heal from errors at run time, so you should rarely if ever require this utility. This utility was developed to guarantee consistency during development!

You can run a verification with:

docker stop <container name>
docker run --rm -i -t -v kanidmd:/data \
    kanidm/server:latest /sbin/kanidmd database verify -c /data/server.toml
docker start <container name>

If you have errors, please contact the project to help support you to resolve these.