How to Back Up and Restore a Koha Database Safely

A reliable backup strategy is one of the most important responsibilities of a Koha administrator. Hardware failures, accidental deletions, failed upgrades, database corruption, or poorly executed configuration changes can turn an ordinary working day into a very unpleasant one.

The good news is that backing up a Koha database is relatively straightforward. The important part is doing it correctly and, more importantly, testing that the backup can actually be restored.

In this guide, I will explain how to back up and restore a Koha database on an Ubuntu/Linux server using MySQL/MariaDB tools.

Always test backup and restore procedures on a test server before using them on a production library system.

Why Should You Back Up Koha?

A Koha installation contains much more than bibliographic records. Depending on your configuration, the database contains:

• Bibliographic records
• Holdings and item information
• Patron records
• Circulation transactions
• Fines and payments
• Acquisition information
• Serials information
• System preferences
• User accounts and permissions
• Saved reports
• Notices and templates
• Various administrative settings

Losing the database can therefore mean losing years of library operations and transaction history. A proper backup strategy should protect both the database and the Koha configuration/files.

Identify Your Koha Database

Before creating a backup, identify the database used by your Koha instance.

Koha stores instance configuration files under:

/etc/koha/sites/

For example, if your Koha instance is called library, you may have:

/etc/koha/sites/library/

The database configuration can be checked with:

sudo nano /etc/koha/sites/library/koha-conf.xml

Look for the database configuration, particularly the database name.

You can also use:

sudo grep -i "database" /etc/koha/sites/library/koha-conf.xml

The exact configuration depends on your Koha installation.

Check the Database Server

Koha installations commonly use MariaDB or MySQL.

Check the service with:

sudo systemctl status mariadb

If your system uses MySQL instead:

sudo systemctl status mysql

You should see that the database server is running.

You can also check the installed version:

mysql --version

For example:

mysql  Ver 15.1 Distrib 10.x.x-MariaDB

Create a Manual Koha Database Backup

The most straightforward method is using mysqldump.

The general syntax is:

mysqldump -u root -p DATABASE_NAME > backup.sql

For example:

mysqldump -u root -p library > library_backup.sql

You will be asked for the database password.

The resulting file:

library_backup.sql

contains the SQL statements required to recreate the database.

I recommend adding the date to the filename:

mysqldump -u root -p library > library_2026-08-15.sql

This makes it much easier to identify older backups.

Create a Compressed Backup

Koha databases can become quite large, especially in libraries with many bibliographic records and long circulation histories.

You can compress the backup using gzip:

mysqldump -u root -p library | gzip > library_2026-08-15.sql.gz

To check the backup:

ls -lh library_2026-08-15.sql.gz

You can also inspect the compressed file without extracting it:

zcat library_2026-08-15.sql.gz | head

You should see SQL statements such as:

-- MySQL dump
-- Host: localhost
-- Database: library

Where Should You Store the Backup?

This is where many backup strategies become slightly fictional.

A backup stored on the same server as the production database is not a complete backup strategy.

If the server’s disk fails, both the database and the backup may disappear together.

Keep at least one additional copy somewhere else.

For example:

Koha Server
     |
     +-- Local backup
     |
     +-- Backup server
     |
     +-- External storage

A practical approach is to maintain:

• Daily local backups
• A separate copy on another server or storage device
• Periodic off-site backups
• Regularly tested restoration

Back Up the Koha Configuration

The database is critical, but it is not the only thing you should protect.

Koha configuration files are generally located under:

/etc/koha/

You can create an archive:

sudo tar -czf koha_config_2026-08-15.tar.gz /etc/koha/

You may also want to preserve important customizations and local files depending on your installation.

For example:

sudo tar -czf koha_files_2026-08-15.tar.gz /etc/koha /var/lib/koha

Be careful with large directories and verify what you are including before copying the archive.

Create an Automated Daily Backup

Manually typing backup commands every day is not a particularly sustainable IT strategy.

Linux provides cron, which can automate the process.

Create a backup directory:

sudo mkdir -p /var/backups/koha

Create a backup script:

sudo nano /usr/local/bin/koha-backup.sh

Add:

#!/bin/bash

INSTANCE="library"
BACKUP_DIR="/var/backups/koha"
DATE=$(date +"%Y-%m-%d_%H-%M-%S")

mkdir -p "$BACKUP_DIR"

mysqldump -u root -pYOUR_DATABASE_PASSWORD "$INSTANCE" | gzip > "$BACKUP_DIR/${INSTANCE}_${DATE}.sql.gz"

find "$BACKUP_DIR" -type f -name "*.sql.gz" -mtime +30 -delete

Make the script executable:

sudo chmod 700 /usr/local/bin/koha-backup.sh

Important security note

Do not casually leave a database password inside a script with permissions that allow other users to read it.

For a production server, use an appropriate MySQL/MariaDB credentials file or another secure authentication mechanism rather than exposing the password in the command line.

The example above is intended to demonstrate the backup process, not to be treated as a complete production security configuration.

Schedule the Backup with Cron

Edit the root crontab:

sudo crontab -e

To run the backup every day at 2:00 AM:

0 2 * * * /usr/local/bin/koha-backup.sh

This will create a new backup every night.

The retention command in the script removes backups older than 30 days.

You can modify the retention period according to your requirements.

For example:

-mtime +90

would retain approximately three months of backups.

Verify That the Backup Exists

A backup process should never be considered successful simply because the script ran.

Check the backup directory:

ls -lh /var/backups/koha/

You should see files such as:

library_2026-08-13_02-00-01.sql.gz
library_2026-08-14_02-00-01.sql.gz
library_2026-08-15_02-00-01.sql.gz

Check the integrity of a gzip archive:

gzip -t library_2026-08-15_02-00-01.sql.gz

If there is no error, the gzip archive itself is valid.

Restoring a Koha Database

Before restoring a production database, stop Koha services so that users and background processes are not modifying the database during restoration.

For an instance called library:

sudo koha-plack --stop library
sudo koha-common stop

The exact service commands can vary depending on your Koha version and installation method.

If you are performing a major recovery operation, make sure you understand which services are running before stopping them.

Create a Backup Before Restoring

This step is extremely important.

Even if the current database appears damaged, create one final copy before overwriting it.

For example:

mysqldump -u root -p library | gzip > library_before_restore.sql.gz

This gives you a recovery point if something goes wrong during the restoration.

Drop and Recreate the Database

First log into MariaDB/MySQL:

mysql -u root -p

Then:

DROP DATABASE library;
CREATE DATABASE library;
EXIT;

Be extremely careful with DROP DATABASE.

Make absolutely certain that:

1. You have selected the correct database.
2. You have a valid backup.
3. You actually intend to replace the existing database.

This is one of those commands where Linux offers no comforting pop-up asking whether you really mean it.

Restore an SQL Backup

If your backup is an uncompressed SQL file:

mysql -u root -p library < library_backup.sql

For a compressed backup:

gunzip -c library_backup.sql.gz | mysql -u root -p library

Depending on the size of the Koha database, restoration may take some time.

Do not interrupt the process unless you have a specific reason to do so.

Check the Database After Restoration

Once restoration is complete, verify that the database contains the expected tables.

Run:

mysql -u root -p library

Then:

SHOW TABLES;

You should see many Koha tables.

You can also check the number of bibliographic records:

SELECT COUNT(*) FROM biblio;

And items:

SELECT COUNT(*) FROM items;

Patrons can be checked with:

SELECT COUNT(*) FROM borrowers;

The exact table structure can differ between Koha versions, so use these commands as basic validation rather than as a complete integrity test.

Start Koha Again

After confirming that the database has been restored:

sudo koha-common start

If you use Plack:

sudo koha-plack --start library

Check the services:

sudo systemctl status apache2
sudo systemctl status mariadb

Then test both:

• Koha Staff Interface
• OPAC

Test the Actual Library Functions

Do not stop after confirming that the login page opens.

Test important functionality such as:

Staff interface

• Staff login
• Searching the catalogue
• Opening bibliographic records
• Editing records
• Adding items
• Patron search
• Patron details

Circulation

• Check out
• Check in
• Renew
• Holds
• Fines
• Payments

OPAC

• Catalogue search
• Record display
• Availability
• Patron login
• Holds and renewals, if enabled

A database restoration is successful only when the library system actually works.

Database Backup Is Not the Same as Full Server Backup

This distinction is important.

A database backup protects your Koha database.

It does not necessarily protect:

• Operating system configuration
• Apache configuration
• SSL certificates
• Custom scripts
• Custom Koha modifications
• Uploaded files
• Local configuration
• Other application data

For a complete disaster-recovery strategy, consider backing up:

Koha Database
        +
Koha Configuration
        +
Custom Files
        +
Server Configuration
        +
SSL Certificates
        +
Backup Credentials/Keys

The exact files and directories depend on your server configuration.

Follow the 3-2-1 Backup Principle

For a production library system, a useful rule is the 3-2-1 backup strategy:

3 copies of your data

2 different storage locations/media

1 copy stored off-site

For example:

Production Koha Server
        |
        +---- Local backup
        |
        +---- Backup server
        |
        +---- Off-site/cloud backup

This protects you against more than just database corruption.

It also helps with:

• Server failure
• Disk failure
• Accidental deletion
• Malware/ransomware
• Hardware replacement
• Failed upgrades
• Disaster recovery

Always Test Your Backups

This is perhaps the most important rule in the entire article:

A backup that has never been restored is only a theory.

At regular intervals, restore a backup to a test server or virtual machine.

Verify:

Database restored
        ↓
Koha starts
        ↓
OPAC works
        ↓
Staff interface works
        ↓
Bibliographic records present
        ↓
Patrons present
        ↓
Circulation works
        ↓
Configuration is correct

If the restoration fails, you want to discover that before the production server fails.

Recommended Backup Schedule

For a typical academic or research library, a practical starting point could be:

Backup	Frequency	Retention
Database	Daily	30 days
Configuration	Daily/Weekly	30–90 days
Full server backup	Weekly	1–3 months
Off-site backup	Daily/Weekly	According to policy
Restore test	Monthly/Quarterly	N/A

The exact schedule should depend on the size and operational importance of your library.

Conclusion

Koha database backup is technically simple, but a reliable backup strategy requires more than running mysqldump once and forgetting about it.

A good Koha backup system should:

• Create regular automated backups
• Compress and timestamp backup files
• Store copies outside the production server
• Protect database credentials
• Back up important configuration files
• Retain multiple historical versions
• Monitor whether backups are actually being created
• Regularly test restoration

For a production library, the goal is not merely to have a backup.

The goal is to be able to say:

“If this server dies today, I know exactly how to bring the library system back.”