How to Restore Koha from an S3 Backup

When would you need to restore from backup?

The KohaSupport automated backup system continuously writes encrypted snapshots of your Koha database and configuration to S3. You would need to restore from one of these backups in the following situations:

• Data corruption or accidental deletion — A patron record bulk-import went wrong, or items were deleted by mistake.
• Failed AMI upgrade that corrupted the database — An upgrade migration script left the database in an inconsistent state.
• Restoring to a known-good state after a bad configuration change — A system preference change or plugin installation had unintended consequences.
• Disaster recovery — The EC2 instance was terminated unexpectedly and cannot be recovered.

Note for AMI upgrades: For Standard and Enterprise tiers, the EBS data volume is preserved across AMI upgrades. You typically do not need an S3 restore after an upgrade unless the database itself is actually corrupted. Check the Koha staff interface first — if it loads normally, your data is intact.

Before you begin

Before starting a restore, confirm you have the following:

• SSH or SSM access to your Koha instance. If the original instance is gone, you’ll need a new instance first — see Restoring to a new instance below.
• Your S3 backup bucket name. Check CloudFormation Outputs for a key named BackupBucketName, or browse the S3 console and filter buckets by your stack name. The bucket follows the naming pattern: <stack-name>-koha-backup-<aws-account-id> (e.g., my-koha-stack-koha-backup-123456789012).
• AWS CLI access on the instance. The Koha instance IAM role already includes an AllowS3BackupOperations policy scoped to the backup bucket — no extra credentials needed when running from the instance.
• Backup logs at /var/log/koha/s3-backup.log if you need to identify which backup was the last clean one.

Tip: For any restore operation that takes more than a few seconds, run your commands inside a screen or tmux session. If your SSH connection drops mid-restore, the operation will continue running in the background.

# Start a named screen session
screen -S koha-restore

# If disconnected, reattach with:
screen -r koha-restore

⚠️ WARNING: Database restore is destructive

Restoring a database backup permanently overwrites all current Koha data — patrons, catalog records, circulation history, and system preferences — with the state from the backup point. There is no undo.

Before proceeding, take an EBS snapshot of the current instance volume from the EC2 console if there is any chance you need to recover the current state. Only continue once you are certain you want to replace the live database.

Step 1 — Find your backup bucket

In the AWS S3 console, look for a bucket named <stack-name>-koha-backup-<account-id>. If you have multiple stacks, filter by your stack name prefix.

From the command line on the Koha server (the instance IAM role has the required S3 permissions):

aws s3 ls | grep koha-backup

Note the full bucket name — you’ll use it in every subsequent step.

Step 2 — List available backups

S3 backup objects are listed chronologically. The most useful listing is sorted by date so you can identify the backup nearest to your target recovery point.

# List database backups (most recent last)
aws s3 ls s3://YOUR-BUCKET-NAME/library/databases/ --human-readable

# List config backups
aws s3 ls s3://YOUR-BUCKET-NAME/library/configs/ --human-readable

Database backups follow the naming pattern:

database_library_YYYY-MM-DDTHH:MM:SS.sql.gz

Config backups follow:

config_library_YYYY-MM-DDTHH:MM:SS.tar.gz

The library segment is the Koha instance name. If your instance was created with a custom name, replace library with that name throughout all commands in this guide.

Identify the timestamp of the backup you want to restore and note the exact filename.

Step 3 — Download the backup file

Create a working directory and download the backup and its checksum file. Always download both — the checksum is required in Step 4.

# Create a temp directory
mkdir -p /tmp/koha-restore

# Download the database backup
aws s3 cp s3://YOUR-BUCKET-NAME/library/databases/database_library_YYYY-MM-DDTHH:MM:SS.sql.gz \
    /tmp/koha-restore/

# Download the corresponding checksum file
aws s3 cp s3://YOUR-BUCKET-NAME/library/databases/database_library_YYYY-MM-DDTHH:MM:SS.sql.gz.sha256 \
    /tmp/koha-restore/

Step 4 — Verify backup integrity

Always verify the checksum before restoring. A corrupted backup that passes this check is extremely unlikely. One that fails must not be used.

cd /tmp/koha-restore
sha256sum -c database_library_YYYY-MM-DDTHH:MM:SS.sql.gz.sha256

Expected output:

database_library_YYYY-MM-DDTHH:MM:SS.sql.gz: OK

If verification fails, the downloaded file is corrupted. Try downloading again, or choose a different backup from the list. If multiple backups fail verification, contact KohaSupport.

Step 5 — Stop Koha services

Stop Koha and Apache before restoring. This prevents any new writes to the database while the restore is in progress and avoids partial-read errors from concurrent access.

sudo koha-stop-zebra library
sudo service apache2 stop

Step 6 — Restore the database

Reminder: This step overwrites the live koha_library database. Confirm you have taken a snapshot (Step “Before you begin”) if needed.

The fastest approach pipes the decompressed SQL directly into MySQL:

zcat /tmp/koha-restore/database_library_YYYY-MM-DDTHH:MM:SS.sql.gz | sudo mysql -u root koha_library

There is no progress output while this runs — that is normal. For large databases (hundreds of thousands of bibliographic records) this may take 10–20 minutes. Do not interrupt it.

Alternative: decompress first, then restore

If you want to inspect the SQL or restore in a separate step:

# Decompress without deleting the original
gunzip -k /tmp/koha-restore/database_library_YYYY-MM-DDTHH:MM:SS.sql.gz

# Restore from the decompressed file
sudo mysql -u root koha_library < /tmp/koha-restore/database_library_YYYY-MM-DDTHH:MM:SS.sql

Tip: For databases over 10 GB, run this inside your screen or tmux session. If you lose the SSH connection during a direct terminal restore, MySQL will receive EOF and the restore will be incomplete.

Step 7 — Restart services

Once the restore completes, bring services back up and rebuild the Zebra search index.

sudo service apache2 start
sudo koha-start-zebra library

# Rebuild the Zebra search index
sudo -u koha-library koha-shell -c "rebuild_zebra -b -a -v -r"

The -r flag resets the index before rebuilding, ensuring it is fully consistent with the restored database. For large catalogs this can take 10–30 minutes. Run it in your screen session.

Step 8 — Verify the restore

Confirm the restoration is successful before declaring the instance healthy:

1. Open the Koha OPAC in a browser — verify it loads without errors.
2. Log in to the staff interface — verify you can see patron and catalog data from the expected time period.
3. Run a catalog search — verify search results appear (confirms Zebra index is working).
4. Check the Koha staff home page for any system notices or warnings that may indicate a post-restore issue.

Restoring configuration files (optional)

A database restore is sufficient for most scenarios. Only restore the configuration backup if you also need to recover Koha config files, Apache virtual host settings, or SSL certificates — for example, after restoring to a brand-new instance.

# Download the config backup
aws s3 cp s3://YOUR-BUCKET-NAME/library/configs/config_library_YYYY-MM-DDTHH:MM:SS.tar.gz \
    /tmp/koha-restore/

# Download and verify the checksum
aws s3 cp s3://YOUR-BUCKET-NAME/library/configs/config_library_YYYY-MM-DDTHH:MM:SS.tar.gz.sha256 \
    /tmp/koha-restore/

cd /tmp/koha-restore
sha256sum -c config_library_YYYY-MM-DDTHH:MM:SS.tar.gz.sha256

# Inspect archive contents before extracting
tar -tzf config_library_YYYY-MM-DDTHH:MM:SS.tar.gz | head -30

# Extract files to their original paths (run as root)
sudo tar -xzf config_library_YYYY-MM-DDTHH:MM:SS.tar.gz -C /

Warning: Extracting a config backup with -C / restores files to their original absolute paths, overwriting current Apache and Koha configuration files in place. Only do this if you explicitly need those config files restored, not just the database.

After restoring config files, restart Apache and Koha:

sudo service apache2 restart
sudo koha-restart-zebra library

Clean up

After confirming the restore was successful, remove the temporary files:

rm -rf /tmp/koha-restore

If you’re restoring to a new instance

If the original instance is gone and you need to restore to a freshly deployed Koha instance:

1. Deploy a new CloudFormation stack using the same template and tier as the original. Wait for the stack to reach CREATE_COMPLETE and for Koha to be accessible.
2. SSH or SSM into the new instance.
3. Follow Steps 1–8 above on the new instance. The backup bucket persists independently of any stack — it is not deleted when a stack is torn down.
4. Restore both the database and config backup to recover your custom settings, SSL certificates, and Koha configuration.
5. If you use a custom domain, update your DNS record to point to the new instance’s public IP or load balancer endpoint.

Troubleshooting

“Access denied” when accessing the S3 bucket

The instance IAM role may not have the AllowS3BackupOperations policy attached, or the bucket name in the command is incorrect. Verify the instance profile in the EC2 console and confirm the bucket name with aws s3 ls | grep koha-backup.

“No such table” errors during restore

The .sql.gz backup file uses DROP TABLE IF EXISTS statements before each CREATE TABLE. The “no such table” messages you may see in logs are expected and harmless — they occur only when the table didn’t exist yet, and MySQL continues normally.

Zebra search shows no results after restore

The Zebra index needs to be rebuilt after any database restore. Run:

sudo -u koha-library koha-shell -c "rebuild_zebra -b -a -v"

Omit the -r flag if you’re retrying a rebuild that was interrupted (to avoid clearing the partial index again).

“Unknown database koha_library”

The koha_library MySQL database does not exist on this instance. This can happen on a freshly deployed instance where Koha hasn’t fully initialised yet, or if MySQL itself is not running. Check MySQL status with sudo service mysql status. If MySQL is up and the database is simply missing, run sudo koha-create --request-db library to create it, then re-run the restore command.

Restore is very slow

Large databases with hundreds of thousands of bibliographic records and items can take 10–20 minutes to restore. This is normal. Always run long restore operations inside a screen or tmux session:

screen -S koha-restore
# ... run restore commands ...
# Ctrl+A then D to detach; screen -r koha-restore to reattach