Running update.php
If you have previously determined that you do not need to update your database, you may skip the following step. However, it does not hurt to run the update.php script just to verify whether or not a database update is necessary. Just make sure that you have made a backup of your database first.
If you set up a test site, you are going to be running update.php on it instead of your existing, live site.
Depending on your site, you may need to log in using the following URL: http://example.com/?q=user
I. Did you login as USER 1?
Previously, you were asked to login as USER 1, the root user, the first user created on your Drupal site. If you are logged in as user 1, skip to part II. If you were not able to do so, you will need to edit the update script in a text editor. Otherwise, you will not be permitted to update the database. Change TRUE to FALSE for the $access_check statement like so:
When upgrading to Drupal 5.x, alter in /update.php:
$access_check = FALSE;When upgrading to Drupal 6.x, alter in /sites/default/settings.php:
$update_free_access = TRUE;After you complete the upgrade, be sure to CHANGE the update.php file BACK TO ITS ORIGINAL STATE if you have made this change. Otherwise, anyone would be able to run the update.php file on your site.
II. Run update.php
In your web browser navigate to the directory where Drupal is installed:
http://www.example.com/update.php
or
http://www.example.com/test_site/update.php (if you are upgrading a test site)The update script should only be run once. It will complete all the updates at once. If prompted for which version, choose the closest starting version that makes sense for you.
This will update the default Drupal and contributed module database tables automatically (versions prior to 4.7 will require manual upgrade of the contributed modules). Once the script has stopped loading, be sure to scroll to the bottom to look for errors.
PostgreSQL and upgrading from Drupal 4.6 to 4.7
Since MySQL is still pretty much the preferred database platform for Drupal (though PostgreSQL support is getting much better!), you may be faced with some additional steps in upgrading. I don't know if this is the case in Drupal 5, but the PostgreSQL database schema includes a number of functions, presumably to add a basic level of MySQL compatibility. Your site may be able to run okay without them, but some modules (like forum) won't be able to work without them. These functions don't seem to be upgraded with the update.php script, so when you upgrade, you may have to grab them from the database schema file (under the database directory of the installation). They're near the end of the file, starting with a section named "Functions". Copy these to a separate file and then you can load them with the command
psql [database_name] < [name of file you created]For reference, here is the contents of the file that I created, based on the 4.7 distribution. You'll want to use whatever's in your Drupal distribution, though.
---
--- Functions
---
--- Always installed in 'public' as prefix isn't appended to function names
SET search_path TO public;
CREATE OR REPLACE FUNCTION "greatest"(numeric, numeric) RETURNS numeric AS '
SELECT CASE WHEN (($1 > $2) OR ($2 IS NULL)) THEN $1 ELSE $2 END;
' LANGUAGE 'sql';
CREATE OR REPLACE FUNCTION "greatest"(numeric, numeric, numeric) RETURNS numeric AS '
SELECT greatest($1, greatest($2, $3));
' LANGUAGE 'sql';
CREATE OR REPLACE FUNCTION "rand"() RETURNS float AS '
SELECT random();
' LANGUAGE 'sql';
CREATE OR REPLACE FUNCTION "concat"(text, text) RETURNS text AS '
SELECT $1 || $2;
' LANGUAGE 'sql';
CREATE OR REPLACE FUNCTION "if"(boolean, text, text) RETURNS text AS '
SELECT CASE WHEN $1 THEN $2 ELSE $3 END;
' LANGUAGE 'sql';
CREATE OR REPLACE FUNCTION "if"(boolean, integer, integer) RETURNS integer AS '
SELECT CASE WHEN $1 THEN $2 ELSE $3 END;
' LANGUAGE 'sql';
Question re: Update Versions and Troubleshooting
Perhaps this is all explained somewhere other than a book.....
Lets say I inherit a database which has not been cared for, and there are many update versions for contrib modules to choose from, starting with 2, 3 and then jumping, say, to 4005, 4006, 4007.
Would the prudent course be to choose the first available (2), and then continue running update, moving up through those? That goes against the dictum "run update.php only once".
On the other hand, say I've leaped ahead (I chose 4005 instead of 3) and run an update that fails, because it is editing a table that looks different than it should, because previous updates had not been run. I assume my only recourse is to go and manually edit the table design based on what the update was trying to accomplish, given its error message. (I can't "un-do" the status of the update, can I?)
So...say I do that. Should I expect my next update.php to indicate that it is time to run update 4006?