How to Migrate Your Koha Database to a New AMI Instance

When a security update requires you to move to a new server image (AMI), you need to copy your Koha database from the old server to the new one. This guide walks through the full process: backing up your data, launching a new server, restoring everything, and switching over.

Downtime: Your library system will be unavailable during the final switchover — typically 15–60 minutes depending on the size of your database.

What You Are Doing

Think of this like moving your library’s filing system to a new building. You will:

1. Pack everything up (create a database backup on the old server)
2. Put the backup somewhere safe (copy it to S3 cloud storage)
3. Set up the new location (launch a new server with the updated software)
4. Move the files over (restore the backup on the new server)
5. Check everything arrived (verify Koha is working)
6. Update the address (point your domain or IP to the new server)
7. Close the old location (terminate the old server)

Before You Begin

Make sure you have:

• Access to the AWS Console for your account
• Ability to connect to your server via EC2 Instance Connect (the browser-based terminal)
• Your library’s web address (OPAC URL) or Elastic IP written down
• About 30–90 minutes of uninterrupted time

Marketplace billing during migration: AWS Marketplace software charges are applied per running instance. This migration has an overlap window — from launching the new server (Step 3) to shutting down the old one (Step 8) — where two instances run simultaneously. On hourly pricing that means software charges apply to both for the overlap period (typically 30–90 minutes). If you are on an annual subscription, your subscription covers one instance; AWS does not explicitly document how a temporary second instance of the same type is billed — contact AWS Support if you need a firm answer before proceeding. Either way, work through Steps 3–8 without unnecessary delays to keep the overlap window short.

Step 1 — Back Up Your Database on the Old Server

Connect to your old server:

1. Open the AWS EC2 console.
2. Click Instances in the left sidebar.
3. Find and select your Koha server.
4. Click Connect → EC2 Instance Connect → Connect.

A browser-based terminal opens. Run this command to create a full backup:

sudo koha-dump library

This creates two files in /var/spool/koha/library/:

• A .sql.gz file — your Koha database (catalogue, patrons, circulation records)
• A .tar.gz file — Koha configuration and uploaded files

Check that the files were created:

sudo ls -lh /var/spool/koha/library/

You should see two files with today’s date in their names, each at least a few megabytes in size. If the files are very small (under 100 KB) or missing, something went wrong — contact KohaSupport before continuing.

Standard and Enterprise tip: If your automated S3 backup ran successfully within the past 24 hours, you can use that as your backup and skip the manual upload in Step 2. Check the S3 console for a recent file in library/databases/.

Step 2 — Copy the Backup to S3

You need to get the backup off the old server before it is shut down. S3 (Amazon’s cloud storage) is the safest place for it.

Find or create your S3 bucket:

• Standard and Enterprise: You already have a backup bucket. Its name looks like your-stack-name-koha-backup-123456789. Find it in the S3 console.
• Free tier: You may need to create a bucket. Go to the S3 console, click Create bucket, give it a unique name (e.g. koha-backup-yourlibrary), and leave all other settings as defaults.

Upload the backup (run this in the EC2 Instance Connect terminal):

aws s3 cp /var/spool/koha/library/koha-library-*.sql.gz \
  s3://your-bucket-name/koha-migration/koha_library_backup.sql.gz

Replace your-bucket-name with your actual bucket name.

Confirm the upload worked:

aws s3 ls s3://your-bucket-name/koha-migration/

You should see the backup file listed with a size of at least a few megabytes.

Step 3 — Launch a New Server

1. Go to AWS Marketplace and find the KohaSupport Koha listing for your tier.
2. Subscribe (if not already) and proceed to Launch.
3. Launch a new EC2 instance using the same settings as your current server:
   • Same instance type (e.g. t3.medium)
   • Same subnet and security group
   • Same IAM instance profile (this gives the server permission to access S3)
4. Wait until the new server shows Running and 2/2 status checks passed (takes 3–5 minutes).

Keep your old server running until you have confirmed your data is on the new one.

Step 4 — Restore Your Database on the New Server

Connect to the new server via EC2 Instance Connect (same steps as Step 1, but select the new instance).

Download the backup from S3:

aws s3 cp s3://your-bucket-name/koha-migration/koha_library_backup.sql.gz \
  /home/ubuntu/koha_library_backup.sql.gz

Stop Koha before touching the database:

sudo koha-plack --stop library

Restore the database:

sudo mysql -e "DROP DATABASE IF EXISTS koha_library; CREATE DATABASE koha_library;"
sudo zcat /home/ubuntu/koha_library_backup.sql.gz | sudo mysql koha_library

The restore may take a few minutes depending on the size of your catalogue.

Apply database updates for the new Koha version:

sudo koha-upgrade-schema library

This brings the database up to date with the newer Koha version. It is safe to run — it only adds what is missing.

Start Koha again:

sudo koha-plack --start library

Step 5 — Update Your Library’s Web Addresses

The new server does not know your library’s URL yet. Update these settings to match your old server:

sudo koha-mysql library -e "
  UPDATE systempreferences SET value='https://YOUR-OPAC-URL'
    WHERE variable='OPACBaseURL';
  UPDATE systempreferences SET value='https://YOUR-STAFF-URL'
    WHERE variable='staffClientBaseURL';
  UPDATE systempreferences SET value='[email protected]'
    WHERE variable='KohaAdminEmailAddress';
"

Replace the placeholder values with your actual URLs and email address.

Restart Koha to apply the changes:

sudo koha-plack --stop library && sleep 3 && sudo koha-plack --start library

Step 6 — Verify the New Server

Before switching over, confirm everything is working.

Check Koha is running:

sudo koha-plack --status library

Check the error log:

sudo tail -30 /var/log/koha/library/plack-error.log

Test in your browser using the temporary IP address:

Find your new instance’s public IP in the EC2 console and open http://<new-instance-ip> in your browser. Check:

• The OPAC loads and search works
• You can log into the staff interface
• A sample record is accessible
• Patron records are visible

Step 7 — Switch Over to the New Server

If you use an Elastic IP address:

1. Open the EC2 console.
2. Click Elastic IPs in the left sidebar.
3. Find your library’s IP address.
4. Click Actions → Associate Elastic IP address.
5. Select the new instance and click Associate.

The switch is immediate — your library’s web address now points to the new server.

If you use a custom domain with a DNS record:

Log into your DNS provider and update the A record to your new server’s public IP. Changes may take a few minutes to a few hours to take effect depending on your DNS settings.

Step 8 — Shut Down the Old Server

Once you have confirmed the new server is fully working:

1. EC2 console → select the old Koha instance.
2. Click Instance State → Terminate instance → confirm.

Clean up the temporary backup from S3:

aws s3 rm s3://your-bucket-name/koha-migration/koha_library_backup.sql.gz

Need Help?

If your library data is not appearing, or Koha shows an error or the web installer screen instead of your catalogue, do not terminate the old server — your data is still there.

Contact KohaSupport with the output of:

sudo tail -50 /var/log/koha/library/plack-error.log

and we will assist you remotely.