[development] Incremental upgrades
drupal at dwwright.net
Mon Jul 30 03:57:40 UTC 2007
Here's the heart of the matter...
1) DB updates are written using the core API of the version they are
updating you to. E.g. the 60** updates are all for the 6.x core API.
2) Drupal core's API has been known to change.
3) It's possible that an update to a particular version of core is
using a core API function that changed or no longer exists in a
future version of core.
So, hypothetically, the updates from 4.6.x to 4.7.x might have used
some function in 4.7.x core that no longer exists or works the same
way in 6.x. If that was true, you couldn't just upgrade directly
from 4.6.x to 6.x, since when you hit the update function that only
worked in 4.7.x core, it would fail and then the rest of the upgrade
path could be busted. Therefore, first upgrading from 4.6.x to
4.7.x, then from 4.7.x to 5.x, and finally from 5.x to 6.x, is the
safest, since you're always running update functions against the
version of core they were written for and tested with.
Upgrading from 4.7.0 to 4.7.1 to ... to 4.7.7 is silly and wasteful.
To the extent the docs and release announcements give that
impression, we should fix them.
Of course, 99% of all update functions only use a tiny fraction of
the core API, namely the DB abstraction layer. The DB layer doesn't
tend to change much, so usually "skipping" some core versions when
upgrading isn't much of a problem.
However, look at schema API new in 6.x -- for now, it's a non-
destructive change, meaning that update_sql() or db_query() still
work as usual. But, it's certainly possible that, e.g. in 7.x,
schema API changes in such a way that update_sql() no longer works as
it once did, or no longer exists. If that happens, it'll be
important for sites to first upgrade all the way to the latest 6.x
release of core, run update.php, upgrade core to 7.x, and run
Also, note that update_sql() has been causing bugs and driving me and
other developers nuts for ages, since it doesn't provide the same
placeholder escaping/substitution functionality that db_query() does,
even though lots of people assume it does. :( I never got around to
mounting a crusade around that for 6.x, but maybe I'll find time/
energy to do so for 7.x (if schema API doesn't totally change
update_sql() by then, anyway). So, it's in fact quite likely that
*something* about the API we use for update.php will change in 7.x,
and that means upgrading directly from 4.7.x or 5.x to 7.x might not
If that happens, we should definitely document it clearly in numerous
spots, but otherwise, I think the boiler-plate text we've been
cutting and pasting in release announcements is probably misleading
and should be either removed or clarified based on this info.
More information about the development