The queryset-refactor branch

This branch contains a major refactoring of the django.db.models.query.QuerySet class to fix a group of SQL problems and make SQL generation easier for database backends requiring customization.

How to get the branch

svn co http://code.djangoproject.com/svn/django/branches/queryset-refactor

See our ​branch policy for full information on how to use a branch.

Status

Branch was created on 13 September, 2007.

At the moment, the branch is fairly unusable. All the tests pass, but there are a lot of other places in the code that attempt to construct SQL fragments and pass them around and they will tend to break.

The focus right now is on correctness, but some significant performance profiling and tuning will need to be done. Current performance is quite a bit slower than the existing code. The good news here is that there are some obvious places to speed things up and, no doubt, some unobvious as well once we get to that point. An optimisation pass is still some way off at the moment; getting all the relevant bugs fixed is the current focus.

Tickets of interest for this branch are marked with qs-rf (and qs-rf-fixed when fixed) in the keywords field in Trac. ​This report shows all the tickets being worked on (unfortunately, there's no easy way to view qs-rf without the qs-rf-fixed ones appearing, since they have a common prefix).

Changes introduced on the branch

A few backwards incompatible changes are created by the changes in this branch. Most people won't be affected by many of these, and porting code is reasonably straightforward.

1. When deleting an object via my_object.delete(), the primary key attribute in the model is now set to None before the post_delete signal is dispatched. Previously, this attribute still had a value inside any post_delete handler.
2. The Options.get_order_sql() method is now gone in django.db.models.options. There appears to be no use for this method any longer.
3. Ordering querysets across related models has a new syntax that is the same as the way you specify relations in a filter: field1__field2__field3, etc. Previously, you had to specify the database table name and the model field name, separated by a period. This led to some problems with multiple joins, as well as requiring you to remember the database table name, which depended on things like the application name. The new syntax is more natural and consistent, as well as helping solve a few bugs. See the order_by() documentation in db-api.txt for more information and some examples.
4. Q objects have changed internally. This is only relevant if you have created custom Q-like objects. You would have created a get_sql() method that returned a data structure that was inserted into the query. In the new code, you create a add_to_query() method that accepts one argument -- the django.db.models.sql.query.Query instance for the current query. Your Q-like object can then add to the various attributes of this class (select, where, etc) to have whatever effect it likes on the result. Note that the add_to_query() method is called when the object is added to the Query object and more changes may be made before it is turned into SQL and executed against the database.