NOTE: As of December 2012, the official pgbackups:auto-month addon is free again, making this script redundant. I’ll leave it here for general interest, and in case Heroku decide to start charging for the addon again in the future.

heroku-pgpy

Lightweight Heroku pgbackups implementation for Python.

Until mid-2012 Heroku’s free pgbackups offering included an auto-month service, which provided automated daily backups with a daily, weekly and monthly archive. This is no longer included on the free database tier, so pgpy provides a script that can be called server-side from Heroku Scheduler (their cron package) to automate your backups.

Various Ruby gems exist that perform similar functions, but most seem to upload the backups to S3 whereas I wanted to use the native pgbackups storage mechanism. Also, how about that Python, you guys?

By examining the official Toolbelt client I was able to write a small Python library that uses the native platform functions to create, store and inventory backups.

Installation

You probably want to include pgpy in your project as a submodule, as it will need to be pushed to Heroku along with the rest of your project. See the docs on submodules if you need help.

$ cd myproject
$ git submodule add git://github.com/BigglesZX/heroku-pgpy.git heroku-pgpy

pgpy requires the Requests library so that will need to be present in your project environment. If you use pip, you’re in luck.

$ pip install requests

Configuration

None, as pgpy picks up all the info it needs by inspecting your Heroku environment variables.

Usage

Run pgpy from Heroku Scheduler, or manually via heroku run python heroku-pgpy/pg.py or via the shell using heroku bash. Note: pgpy cannot be run locally. It is designed to be run on the server side where the Heroku features are accessible.

With the --show option pgpy will show your recent backups; with the --capture option it will create one, expiring an old backup if necessary.

$ heroku run python heroku-pgpy/pg.py --show
$ heroku run python heroku-pgpy/pg.py --capture

It is strongly recommended that you schedule your backups to run no frequently than once a day, as per the original schedule of the pgbackups addon at the auto-month level.

Troubleshooting

pgpy identifies itself as the Heroku client gem in order to access server-side resources. If your backups fail with errors like “your Heroku client version is out of date”, ensure you have the latest copy of pgpy. The latest version should increment the HEROKU_GEM_VERSION var at the top of the file so that it matches a recent version of the official gem. See here for the latest if you feel like changing it yourself.

Resources

Based on an inspection of the Heroku client code here and here. Thanks to Will at Heroku for his assistance and approval .

Obligatory Disclaimer

This is beta software still under development, and while all functionality within pgpy is taken from the official Heroku client, it is used at your own risk. pgpy uses API calls that are subject to change, so it may be necessary to update the library from time to time to keep up with changes to the Heroku platform.

This is not an official Heroku product; it is not developed by Heroku or supported or endorsed by them beyond the approval of its use linked above.