[development] important reminder: do not use API functions in update code

[Gábor Hojtsy]

Hey,

As more and more schema API functionality is added to Drupal, and as
more and more database changes are made in each release, it is very
important for you to remenber this:

 **Avoid using API functions (ie. anything used in the Drupal runtime
too) in your update functions**

There were several instances of this before. Previous updates used
node content type listing API functions, some of which were simply
gone later, so no update-hopping (through multiple versions) was
possible without some update code hacking. But it is just as easy to
write bad code when in the same Drupal version. Take
system_update_6027 for example, which we try to fix at
http://drupal.org/node/197500 .

 - it calls _block_rehash() (note the underscore, not even a public
API function!)
 - _block_rehash() uses drupal_save_record(), which uses the most up
to date schema from system_schema()

Now what happens if the schema is changed in a later update in Drupal
6? (ie. > 6027 but < 7000). Well, system_update_6027() becomes broken,
because its _block_rehash() call tries to use the latest schema (as in
after all Drupal 6 updates are run), but all Drupal 6 updates are not
run yet.

Think about this when you are doing your Drupal 6 upgrade functions
for your modules.

Gabor