Dump and Load utilities

Introduction

Citadel now includes two new utilities, ctdldump and ctdlload, which as their names suggest are intended to "dump" your Citadel Server database to a plain-text delimited format, and then "load" that text file into the database of a new server. If you have worked with databases before then the purposes of these utilities will be familiar.

• You can make a backup of your database in an architecture-independent format.
• You can change CPU architectures (for example, from AMD64 to ARM) or bit length (for example, 32-bit to 64-bit) by dumping on the source system and then loading on the target system.
• Examining and/or performing "surgery" on the dumped data is also possible. This is neither encouraged nor supported.

Warnings!

ctdldump and ctdlload are intended to be used while Citadel Server is not running. You MUST stop the Citadel Server before attempting to use either utility.

ctdlload will erase any existing database in the specified target directory. Once this happens, it is not possible to recover any data that was previously there. Take backups of everything!

The source and target systems must be running the same version of Citadel Server.

Usage

Both utilities use the same calling convention:

./ctdldump -y [-h citadel_dir]
./ctdlload -y [-h citadel_dir]

The -y flag tells the program that you've read these instructions, and yes, you understand the calling syntax. The -h flag specifies the location of your Citadel installation. On most systems this will be /usr/local/citadel

ctdldump sends its dump data to standard output. ctdlload reads from standard input.

Examples

Example 1: dump your database to a file in the /tmp directory

cd /usr/local/citadel
./ctdldump -y >/tmp/dump.dat

Example 2: load your database from that file in the /tmp directory (perhaps on another system)

cd /usr/local/citadel
./ctdlload -y </tmp/dump.dat

Example 3: migrate your database to another host over an SSH connection (run on the source system)

cd /usr/local/citadel
./ctdldump -y | ssh root@other.system "cd /usr/local/citadel ; ./ctdlload -y"

Notes

These utilities replace the ctdlmigrate utility found in previous versions of Citadel. The new utilities run much faster and more reliably.