[Pulp-list] How to write migrations for an external Pulp package

[Randy Barlow]

We've recently made another change to our migration system. In a 
previous e-mail from me, I mentioned that you could write migrations in 
the pulp.server.db.migrations namespace. We decided to instead take 
advantage of the distribute pkg_resources module entry points feature. 
In order to write migrations as a third party package to Pulp, you 
simply need to follow these guidelines:

1) Somewhere in your own namespace, create a migrations package (you can 
name it what you like, but "migrations" is a good name.)

2) In this package, you can create Python migration scripts. Their 
filenames must start with a number, but you can name them anything you 
like following the number. For example, 0001_my_first_migration.py, 
0002_rename_rpm_descriptions.py, etc.

3) The first migration must be number 1, and every migration after must 
be the next whole number. No gaps are allowed in migration version 
numbers. Leading zeros are not required, but they may make it easier to 
sort the migrations using ls.

4) The migration modules must have a function in them named migrate with 
this method signature:

	def migrate(*args, **kwargs)

We don't currently pass any arguments, but we'd like to keep the option 
open for the future.

5) In order to advertise your migrations package to Pulp, your setup.py 
should have an entry like this in your setup method:

      entry_points = {
          'pulp.server.db.migrations': [
              '<a_label_of_your_choosing> = 
your_python_project.path.to.migrations_package',
          ]
      }

For example, the pulp_rpm project might use something like this:

     entry_points = {
         'pulp.server.db.migrations': [
             'pulp_rpm = pulp_rpm.migrations'
         ]
     }

The label 'pulp.server.db.migrations' is very important as that is what 
Pulp will be looking for. The label of your choosing can be anything you 
like, but it must be unique inside your own project. You can provide 
more than one migration package if you like.

This will be officially documented soon, but feel free to ask any 
questions you may have about this in the meantime.

-- 
Randy Barlow
Raleigh, NC, USA