Introduction

A while back I introduced tco db-backup which eases creating and restoring backups. Here I’ll introduce some additions to make it even easier to retrieve and restore backups. I’ll also introduce some changes to how DevOps will deliver requested DB backups from now on.

Some changes described here may require you to update tco. Debian / Ubuntu users will receive the update automatically via OS updates. Others look at tco’s README file.

New download and restore-local

tco db-backup download and tco-backup restore-local allow downloading a backup as file and restoring the backup on localhost, respectively.

The commands for doing either is printed when you list backups:

$ tco db-backup list toccotest
tco db-backup download db2.stage.tocco.cust.vshn.net:file:nice_toccotest.dump nice_toccotest-2026-04-10T00:01.dump
tco db-backup restore db1.stage.tocco.cust.vshn.net db2.stage.tocco.cust.vshn.net:file:nice_toccotest.dump
tco db-backup restore-local db2.stage.tocco.cust.vshn.net:file:nice_toccotest.dump
    db_name: nice_toccotest
    time:    2026-04-10 00:01:26 (  0 d 14 h  6 min ago)
    size:    1.4 GiB


download      -> download dump
restore       -> restore on db1.stage.tocco.cust.vshn.net
restore-local -> restore on localhost

Pick the download, restore or restore-local command you need. Use tco db-backup <SUBCOMMAND> --help to find out more.

Reminder: tco db-backup list will always give you access to the latest backup (usually from yeterday night), without talking to DevOps.

Delivering Archived Backups

We archive our backups using Borg. I hope to integrate Borg fully with tco db-backup at some point but for now I simply added a helper script for extracting backups from this archive easily and in a way that allows tco db-backup to discover and identify the extracted backups.

When you request a backup, DevOps will run this script and sent you the output which contains all the information you need to do the restore / download yourself:

$ sudo -i borg-extract-db db-2026-04-04T04:12:01 toccotest
Retrieving file from Borg:
    size:  1.4 GiB
    dated: 2026-04-03 23:59:19

File ready, use the following commands to retrive / restorebackup.

Restore on db1.stage.tocco.cust.vshn.net:

    $ tco db-backup restore db1.stage.tocco.cust.vshn.net "db2.stage.tocco.cust.vshn.net:file:borg-extract/nice_toccotest-2026-04-03T23:59:19.dump"

Restore on localhost:

    $ tco db-backup restore-local "db2.stage.tocco.cust.vshn.net:file:borg-extract/nice_toccotest-2026-04-03T23:59:19.dump" nice_toccotest

Download:

    $ tco db-backup download "db2.stage.tocco.cust.vshn.net:file:borg-extract/nice_toccotest-2026-04-03T23:59:19.dump" nice_toccotest-2026-04-03T23:59:19.dump

The details don’t matter much for those outside the DevOps team but this is the output you’ll receive.

The backups provided this way will remain available for three days (subject to change) and can also be seen via the list command:

$ tco db-backup list toccotest
tco db-backup download db2.stage.tocco.cust.vshn.net:file:borg-extract/nice_toccotest-2026-04-03T23:59:19.dump nice_toccotest-2026-04-03T23:59.dump
tco db-backup restore db1.stage.tocco.cust.vshn.net db2.stage.tocco.cust.vshn.net:file:borg-extract/nice_toccotest-2026-04-03T23:59:19.dump
tco db-backup restore-local db2.stage.tocco.cust.vshn.net:file:borg-extract/nice_toccotest-2026-04-03T23:59:19.dump
    db_name: nice_toccotest
    time:    2026-04-03 23:59:19 (  6 d 16 h  7 min ago)
    size:    1.4 GiB


tco db-backup download db2.stage.tocco.cust.vshn.net:file:nice_toccotest.dump nice_toccotest-2026-04-10T00:01.dump
tco db-backup restore db1.stage.tocco.cust.vshn.net db2.stage.tocco.cust.vshn.net:file:nice_toccotest.dump
tco db-backup restore-local db2.stage.tocco.cust.vshn.net:file:nice_toccotest.dump
    db_name: nice_toccotest
    time:    2026-04-10 00:01:26 (  0 d 16 h  5 min ago)
    size:    1.4 GiB


download      -> download dump
restore       -> restore on db1.stage.tocco.cust.vshn.net
restore-local -> restore on localhost

Why The Change?

I’ve ended up restoring a number of DB backups recently and couldn’t but notice that various DBs have grown to a size which is hard to handle.

For our largest backup the transfer alone takes about 7 minutes at 100 MiB/s, 1 hour 10 minutes at 10 MiB/s or 12 hours at 1 MiB/s. I decided make some small changes to have tco db-backup handle the heavy lifting. It has already been optimized heavily to allow creating and, if needed, restoring backups during deployment. We’ll need this when we start rolling out automated deployments for production.

Specifically, advantages of using tco db-backup are:

• Dumps are compressed in transit, reducing transferred bytes by 70% to 95% compared to using scp and transferring the raw, uncompressed dump.
• restore (but not restore-local) happens directly, server-to-server. Speed is independent of your internet connection.
• Target DB is created automatically, with the right owner.
• DevOps extracts the backup from the archive once and you can then use it freely for the next days, downloading and restoring it as needed.

Note that restoring on a different server (e.g. restoring a production backup on test) is not currently supported.