collective.recipe.backup 0.5

Example usage

The simplest way to use it to add a part in buildout.cfg like this:

>>> write('buildout.cfg',
... """
... [buildout]
... parts = backup
...
... [backup]
... recipe = collective.recipe.backup
... """)

Running the buildout adds a backup, snapshotbackup and restore scripts to the bin/ directory and, by default, it creates the var/backups and var/snapshotbackups dirs:

>>> print system(buildout) # doctest:+ELLIPSIS
Upgraded...
Installing backup.
backup: Created /sample-buildout/var/backups
backup: Created /sample-buildout/var/snapshotbackups
Generated script '/sample-buildout/bin/backup'.
Generated script '/sample-buildout/bin/snapshotbackup'.
Generated script '/sample-buildout/bin/restore'.
<BLANKLINE>
>>> ls('var')
d  backups
d  snapshotbackups
>>> ls('bin')
-  backup
-  buildout
-  restore
-  snapshotbackup

>>> print system('bin/backup')
--backup -f /sample-buildout/var/filestorage/Data.fs -r /sample-buildout/var/backups
INFO: Backing up database file: ...

>>> print system('bin/backup --quiet')
--backup -f /sample-buildout/var/filestorage/Data.fs -r /sample-buildout/var/backups

>>> print system('bin/restore')
--recover -o /sample-buildout/var/filestorage/Data.fs -r /sample-buildout/var/backups
INFO: Restoring...

Supported options

The recipe supports the following options, none of which are needed by default. The most common one to change is location, as that allows you to place your backups in some system-wide directory like /var/zopebackups/instancename/.

location

Location where backups are stored. Defaults to var/backups inside the buildout directory.

keep

Number of full backups to keep. Defaults to 2, which means that the current and the previous full backup are kept. Older backups are removed, including their incremental backups. Set it to 0 to keep all backups.

datafs

In case the Data.fs isn’t in the default var/filestorage/Data.fs location, this option can overwrite it.

full

By default, incremental backups are made. If this option is set to ‘true’, bin/backup will always make a full backup.

debug

In rare cases when you want to know exactly what’s going on, set debug to ‘true’ to get debug level logging of the recipe itself. Repozo is also run with --verbose if this option is enabled.

snapshotlocation

Location where snapshot defaults are stored. Defaults to var/snapshotbackups inside the buildout directory.

gzip

Use repozo’s zipping functionality. ‘false’ by default. Set it to ‘true’ and repozo will gzip its files. Note that *.fs becomes *.fsz, not *.fs.gz.

additional_filestorages

Advanced option, only needed when you have split for instance a catalog.fs out of the regular Data.fs. Use it to specify the extra filestorages. (See explanation further on).

We’ll use all options:

>>> write('buildout.cfg',
... """
... [buildout]
... parts = backup
...
... [backup]
... recipe = collective.recipe.backup
... location = /backups/myproject
... keep = 3
... datafs = subfolder/myproject.fs
... full = true
... debug = true
... snapshotlocation = snap/my
... gzip = true
... """)
>>> print system(buildout) # doctest:+ELLIPSIS
Uninstalling backup.
Installing backup.
backup: Created /sample-buildout/snap/my
Generated script '/sample-buildout/bin/backup'.
Generated script '/sample-buildout/bin/snapshotbackup'.
Generated script '/sample-buildout/bin/restore'.
<BLANKLINE>

Backups are now stored in /backups/myproject and the Data.fs location is handled correctly despite being a relative link:

>>> print system('bin/backup')
--backup -f /sample-buildout/subfolder/myproject.fs -r /backups/myproject -F --verbose --gzip
INFO: Backing up database file: ...

The same is true for the snapshot backup.

>>> print system('bin/snapshotbackup')
--backup -f /sample-buildout/subfolder/myproject.fs -r /sample-buildout/snap/my -F --verbose --gzip
INFO: Making snapshot backup:...

Advanced usage: multiple Data.fs files

Sometimes, a Data.fs is split into several files. Most common reason is to have a regular Data.fs and a catalog.fs which contains the portal_catalog. This is supported with the additional_filestorages option:

>>> write('buildout.cfg',
... """
... [buildout]
... parts = backup
...
... [backup]
... recipe = collective.recipe.backup
... additional_filestorages =
...     catalog
...     another
... """)

The additional backups have to be stored separate from the Data.fs backup. That’s done by appending the file’s name and creating extra backup directories named that way:

>>> print system(buildout) # doctest:+ELLIPSIS
Uninstalling backup.
Installing backup.
backup: Created /sample-buildout/var/backups_catalog
backup: Created /sample-buildout/var/snapshotbackups_catalog
backup: Created /sample-buildout/var/backups_another
backup: Created /sample-buildout/var/snapshotbackups_another
Generated script '/sample-buildout/bin/backup'.
Generated script '/sample-buildout/bin/snapshotbackup'.
Generated script '/sample-buildout/bin/restore'.
<BLANKLINE>
>>> ls('var')
d  backups
d  backups_another
d  backups_catalog
d  snapshotbackups
d  snapshotbackups_another
d  snapshotbackups_catalog

The various backups are done one after the other. They cannot be done at the same time with repozo:

>>> print system('bin/backup')
--backup -f /sample-buildout/var/filestorage/Data.fs -r /sample-buildout/var/backups
--backup -f /sample-buildout/var/filestorage/catalog.fs -r /sample-buildout/var/backups_catalog
--backup -f /sample-buildout/var/filestorage/another.fs -r /sample-buildout/var/backups_another
INFO: Backing up database file: ...
INFO: Backing up database file: ...
INFO: Backing up database file: ...

Same with snapshot backups:

>>> print system('bin/snapshotbackup')
--backup -f /sample-buildout/var/filestorage/Data.fs -r /sample-buildout/var/snapshotbackups -F
--backup -f /sample-buildout/var/filestorage/catalog.fs -r /sample-buildout/var/snapshotbackups_catalog -F
--backup -f /sample-buildout/var/filestorage/another.fs -r /sample-buildout/var/snapshotbackups_another -F
INFO: Making snapshot backup: ...
INFO: Making snapshot backup: ...
INFO: Making snapshot backup: ...

And a restore restores all three backups:

>>> print system('bin/restore')
--recover -o /sample-buildout/var/filestorage/Data.fs -r /sample-buildout/var/backups
--recover -o /sample-buildout/var/filestorage/catalog.fs -r /sample-buildout/var/backups_catalog
--recover -o /sample-buildout/var/filestorage/another.fs -r /sample-buildout/var/backups_another
INFO: Restoring...
INFO: Restoring...
INFO: Restoring...

0.5 (unreleased)

• Added support for additional_filestorages option, needed for for instance a split-out catalog.fs. [reinout]

• Test setup fixes. [reinout+maurits]

0.4 (2008-08-19)

• Allowed the user to make the script more quiet (say in a cronjob) by using ‘bin/backup -q’ (or –quiet). [maurits]

• Refactored initialization template so it is easier to change. [maurits]

0.3.1 (2008-07-04)

• Added ‘gzip’ option, including changes to the cleanup functionality that treats .fsz also as a full backup like .fs. [reinout]

• Fixed typo: repoze is now repozo everywhere… [reinout]

0.2 (2008-07-03)

• Extra tests and documentation change for ‘keep’: the default is to keep 2 backups instead of all backups. [reinout]

• If debug=true, then repozo is also run in –verbose mode. [reinout]

0.1 (2008-07-03)

• Added bin/restore. [reinout]

• Added snapshot backups. [reinout]

• Enabled cleaning up of older backups. [reinout]

• First working version that runs repozo and that creates a backup dir if needed. [reinout]

• Started project based on zopeskel template. [reinout]