Packing Or Reference Checking A ZODB Storage: zodbpack

RelStorage also comes with a script named zodbpack that packs any ZODB storage that allows concurrent connections (including RelStorage and ZEO, but not including FileStorage). Use zodbpack in cron scripts. Pass the script the name of a configuration file that lists the storages to pack, in ZConfig format. An example configuration file:

  pack-gc true
    db zodb

When packing a RelStorage, please read Packing A Database May Increase Disk Usage.

Options for zodbpack

--days or -d

Specifies how many days of historical data to keep. Defaults to 1, meaning all objects newer than 1 day are considered reachable. This is meaningful even for history-free storages, since unreferenced objects are not removed from the database until the specified number of days have passed.

For RelStorage, specifying a negative number means to pack to the most recent committed transaction.


Instructs the storage to only run the pre-pack phase of the pack but not actually delete anything. This is equivalent to specifying pack-prepack-only true in the storage options.


Instructs the storage to only run the deletion (packing) phase, skipping the pre-pack analysis phase. This is equivalent to specifying pack-skip-prepack true in the storage options.


This RelStorage only option causes the storage to run an updated prepack with garbage collection and then report on any objects that would be kept but that reference other objects that no longer exist. This is limited to reporting exactly one level of broken references.

After completing this, you can run it again with --use-prepack-state and --days -1 to garbage collect anything that needs collecting.


This is new functionality as of RelStorage releases after October 6, 2020. Feedback is welcome!

usage: zodbpack [-h] [-d DAYS] [--prepack] [--use-prepack-state]

ZODB storage packing utility.

positional arguments:

optional arguments:
  -h, --help            show this help message and exit
  -d DAYS, --days DAYS  Days of history to keep (default: 1). If this is
                        negative, then packs to the current time (only on
  --prepack             Perform only the pre-pack preparation stage of a pack.
                        (Only works with some storage types, notably
  --use-prepack-state   Skip the preparation stage and go straight to packing.
                        Requires that a pre-pack has been run, or that packing
                        was aborted before it was completed.
  --check-refs-only     If given, performs an updated prepack with GC and
                        reports on any references from objects that would be
                        kept to objects that have already been removed. The
                        --days and --prepack arguments are ignored.