The Joomla! Community Portal ™





Migration Updates
Written by Sam Moffatt   
Tuesday, 29 January 2008 02:16

Update: This is an old blog, for the latest information about migrating check out the guide on the documentation wiki at:

No doubt if you've already got a Joomla! 1.0.x site you're wondering what it'll take to get your site to 1.5, you might also be wondering if you can get their third party extensions migrated as well and you may even wonder if its safe to sit on 1.0 for a little while longer until things pan out a bit for this funny 1.5 thing and people start writing new extensions and updating old extensions. So I thought I'd write up some thoughts about migrating to 1.5 and spread some news to help people out.

Migrator Updates
To get started in the land of Migration there has been an update: the migrator tool is now at RC6. Some tutorials on the net have been mistakenly saying you need the same version of Migrator as you do Joomla! release, which is just plain wrong. Earlier migrators will work with later Joomla! releases and vice versa, though really you're going to want the latest and greatest to get things to behave properly. So the migrator should also work fine regardless of your Joomla! release, but it has been heavily tested from versions 1.0.10 to 1.0.14RC1, so being on at least those releases is the most advisable. Additionally I've tested the migrator on Mambo 4.5.2, 4.5.5 and 4.6.3 and have had the import run successfully again the sample data for those sites (note: Mambo isn't officially supported or fully tested and not all data may be transferred properly). Whilst not all data will be transferred, the core of Mambo hasn't changed that much so we're able to use the exact same mgirator with those Mambo releases as Joomla! 1.0, cool!

So whats new with RC6? Well now there is the ability to select which plugins you wish to run (so you can selective export tables) and for the developers there was an addition to the API to make it even easier to alter the SQL automatically generated by the ETLPlugin framework and add SQL before and after a plugin runs. The core_log_* tables have also been removed which for older sites could be quite large tables so this should speed up the creation of dump files.

And the stable migrator? Well if RC6 is holding up pretty well and no issues come up in the next week or so, RC6 is probably going to turn into the Migrator's stable release. This means from the Migrator side of things I feel I've gotten most of the bugs out and its easy to use. The stable will probably have a few more updates with regards to documentation shipped but this should be the only change.

Update PHP version
Where possible upgrade to PHP4.4.x or higher to get the best compatibility. There are known issues with PHP 4.3.x releases (especially with 4.3.9) so upgrading to the latest release will give you less troubles both in migration and with 1.5 in general.

iconv errors
I've seen a few iconv errors floating around the place about invalid characters. For the most part things seem to be fine by ignoring them, however they may cause other issues. For the most part if iconv is flagging an issue with something then it would appear that the data has information in it that isn't quite right. Check your data for any strange characters or use a slightly different encoding and see if you have any issues still.

I've also seen some issues with migration that can be solved by going through David Gal's old guide for UTF-8 in 1.0 on the forum: so checking that you've applied all of the tips, namely the "SET NAMES 'UTF8'" tip.

Don't forget the prefix!
The migrator changes the prefix to jos_ regardless of the original site prefix. This was done to normalise the prefix. This doesn't mean you can't use a different prefix in your 1.5 database but when it comes to migration the "old prefix" is "jos_". Additionally it doesn't mean that you can't export a site if you don't have a 'jos_' prefix, it just means that the migrator dump file will always use the 'jos_' prefix.

Memory and time
If you have the ability to, give your PHP process more memory and execution time during migration. This will allow the system to create and load dumps faster if you can increases these limtis and will reduce the number of page reloads to avoid exceeding time or memory limits. Whilst the migration systems attempt to do their best, giving it some breathing room also helps. This is especially relevant for larger Joomla! instances!

Misbehaving 1.0 extensions
Before migrating, create a small 1.5 test installation and install your 1.0 extensions on to it and test with using legacy mode or not. Some extensions that do not work properly with 1.5 at the moment are mod_pda and Joombackup, both of which from reports on the forum cause Joomla! not to load properly. Not all extensions will be supported in 1.5, so its handy to test it on a vanilla (non migrated) 1.5 site to see how they behave before attempting to migrate your 1.0 site.

The tortoise or the hare?
Joomla! 1.0 support isn't going to disappear the moment 1.5 is released, which means you don't have to race to get to 1.5 and get everything updated. You can wait a while on 1.0 until updates to your extensions are 1.5 compatible. What you might gain from waiting is better third party support for your extensions and an easier migration pathway. If you are just using the Core of Joomla! then it is easy to upgrade to 1.5, but if you heavily rely on third party extensions then you might want to get in touch with their developers about writing migration plugins and 1.5 versions of their extensions.

In Joomla! 1.5 we've updated the SEF to behave a lot better, but that makes it different to 1.0's style. For those who haven't installed a third party SEF solution in 1.0, then you can merely enable the Legacy Plugin (with legacy routing) and the Backlink Migration plugin in 1.5 to have approximately 90% of 1.0 SEF URL's routed appropriately. If you have a third party SEF extension, the backlink migration system will build a list of SEF links from your menus. This means that any link that is in your menu should be transferred properly, even if you have third party SEF, but not all links will be transferred.

File permissions
If you're doing a migration make sure you give Apache write access to installation/sql/migration/ and ensure you've got a temporary directory set up and writeable (e.g. /tmp) for the migrator to use. The migrator alters the dump file before it imports it into 1.5 to handle things such as different prefixes and transliteration. It is important that you make these directories writeable.

Manual insertion
Whilst this is certainly the hardest way of doing things, you can also manually insert most tables from the dump file into Joomla!. You will have to take care of manually renaming any key values to ensure that there aren't any clashes. I'm not quite sure what the best and easiest way to do this is, but it would be possible if you have an existing 1.5 site and want to insert content from your old site into it. The only table that this won't work for is the menu table, this has to be handled specifically via the 1.5 migration process.

Core hacks and modifications
The migrator doesn't support core hacks or modifications to the core database tables. If you have installed anything like a bridge to the system that modifies the core tables then these will not migrate properly. The migrator is designed to handle the core tables as they are, not in their modified form. Contact the creator of the bridge to acquire migrator plugins approriate to your tables (you can override the core plugins by putting your own over the top) if you want to migrate a modified site.

Migration Errors
If you encounter an error half way through migration, the system won't let you attempt to migrate again because your database might be in an inconsistent state (hey, it had an error!). This means that if you get an error during migration you will need to start the entire 1.5 install again to get a clean database and the system will then allow you to try to migrate again.