Pony ORM Migrations

When we have started developing Pony ORM, we set a goal of creating the most pythonic, easy to use and powerful object-relational mapper for Python. Now, when we are getting feedback from our users, we are happy to see that we have managed to do this. We are grateful for your feedback, you are awesome! It helps us making Pony even better.

The most frequent request at the moment is database migrations. Pony ORM provides intuitive object-oriented interface to a database. We want our migrations to share the same paradigm – to be easy to use and powerful.

Pony ORM describes database model in terms of entities and its relationships. For human beings working with such a model is easier rather than with tables in a relational database. For example, it allows easily describe many-to-many relationships. In a relational database one need to add an intermediate table for this, which adds complexity. This way, Pony allows working with a database at a higher level of abstraction.

Previous attempts

By this moment, we have made a couple of attempts to implement the migrations. The result of those attempts were not officially released, although they are available at GitHub. The reason was that we’ve found some flaws in those approaches and for us it is important to provide an easy to use and powerful migrations interface. Based on that experience, we figured a better way and hope this approach is free from the drawbacks of previous versions.

Migrations workflow

The workflow of Pony ORM migrations looks as following:

The migration file describes the changes to be made in the database. In order to generate such a file, Pony compares the current models taken from the source code with the models generated by applying all previous migrations. The resulting file contains the descriptions both at the entity level and the database tables level.

Entity level

The modifications at the entity level are described using the list of operations such as AddEntity, RemoveEntity, AddAttrbute, AddRelation, RenameEntity, etc. After applying these operations, Pony gets a new state of entities.

Database level

The modifications at the database level are described using another list with the operations like AddTable, AddColumn, AddForeignKey, AddIndex, etc. These operations provide full control on database changes. At this level one can add the ExecSQL command, which is used for data migrations.

In most cases the database operations will be generated automatically, but when necessary, the developer can add any arbitrary operation to this list. It might be useful for complex updates or in early releases of the migration feature. Later we will be adding more and more well known use cases so that Pony can do those migrations automatically.


This approach perfectly matches with a typical software development workflow when adding new features happens in separate branches and then those branches are being merged into the main branch. Operations which describe the changes to be made makes the merging process very simple.

Once we have the new migrations, developers will be able to easily switch to the new version if currently they use an old approach.

We believe the new Pony ORM migrations will help developing applications even faster.