zodbconvert¶
RelStorage comes with a script named zodbconvert
that converts
databases between formats. Use it to convert a FileStorage instance to
RelStorage and back, or to convert between different kinds of
RelStorage instances, or to convert other kinds of storages that
support the storage iterator protocol.
When converting between two history-preserving databases (note that
FileStorage uses a history-preserving format), zodbconvert
preserves all objects and transactions, meaning you can still use the
ZODB undo feature after the conversion, and you can convert back using
the same process in reverse. When converting from a history-free
database to either a history-free database or a history-preserving
database, zodbconvert
retains all data, but the converted
transactions will not be undoable. When converting from a
history-preserving storage to a history-free storage, zodbconvert
drops all historical information during the conversion.
How to use zodbconvert
¶
Create a ZConfig style configuration file that specifies two storages,
one named “source”, the other “destination”. The configuration file
format is very much like zope.conf. Then run zodbconvert
, providing
the name of the configuration file as a parameter.
The utility does not modify the source storage. Before copying the
data, the utility verifies the destination storage is completely empty.
If the destination storage is not empty, the utility aborts without
making any changes to the destination, unless the --incremental
option is used (in which case the destination must be a previously
copied version of the source).
Here is a sample zodbconvert
configuration file:
<filestorage source>
path /zope/var/Data.fs
</filestorage>
<relstorage destination>
<mysql>
db zodb
</mysql>
</relstorage>
This configuration file specifies that the utility should copy all of the transactions from Data.fs to a MySQL database called “zodb”. If you want to reverse the conversion, exchange the names “source” and “destination”. All storage types and storage options available in zope.conf are also available in this configuration file.
Options for zodbconvert
¶
usage: zodbconvert [-h] [--dry-run] [--clear] [--incremental] config_file ZODB storage conversion utility. positional arguments: config_file optional arguments: -h, --help show this help message and exit --dry-run Attempt to open both storages, then explain what would be done. --clear Clear the contents of the destination storage before copying. Only works if the destination is a RelStorage. WARNING: use this only if you are certain the destination has no useful data. --incremental Assume the destination contains a partial copy of the source and resume copying from the last transaction. WARNING: no effort is made to verify that the destination holds the same transaction data before this point! Use at your own risk.