CONTENTS OF THIS FILE --------------------- * Introduction * Requirements * Files * Setup * Performing the Migration * Miscellaneous * More Information INTRODUCTION ------------ Current Maintainer: Shaun Haber <shaun.haber@wmg.com> This directory contains necessary scripts to export content from a Drupal 5 database and import it into a Drupal 6 site. The migration phase is generally broken into 3 separate steps: initializing, importing, and processing. The initialization phase should only happen once, but the importing and processing phases may be run multiple times. It is advisable to do a preliminary run during site development to test for integration bugs, and to do a final migration in the moments before a site relaunch. REQUIREMENTS ------------ * This script requires Drush. Drush is installed on our development and production servers. Our development server is wbrlabs.com. Our production server is mgmt1.p.wbrdc.com. To learn more about Drush, visit http://drupal.org/project/drush * Before the preliminary migration, a snapshot of the production site database needs to be setup on the dev server with the same db access credentials as the dev site. * Before the site launch, the production site must be put in a frozen state or be taken offline. At this time, a snapshot of the production database should be setup on the dev server with the same db access credentials as the dev site. FILES ----- An overview of the files contained in this directory: * config.ini - The configuration file in ini format. * config.inc - Code to parse the configuration file. * import.drush.php - The main script, invoked using the drush php-script command * process-example.inc - A example script to give an idea of the process phase. * process.inc - The placeholder script where you capture the post-import actions. * README - This file. SETUP ----- 1. PROVISION THE NEW DEV SITE Setting up the new dev site should be the first thing that happens. Currently, this is done via a shell script on wbrlabs: /home/wbrlabs/drupal6x/sites/mknew.sh <site-moniker> This script will take care of most things including creating a project directory in Subversion, creating the dev database, and adding symbolic links to the dev environment. To finish the installation, visit: http://<site-moniker>.wbrdev.com/install.php. 2. COPY THE SCRIPT FILES TO A SPECIFIED LOCATION Place these files inside your site directory: E.g., /home/wbrlabs/drupal6x/sites/<newsite>/d6migration 3. SETUP SNAPSHOT OF PRODUCTION SITE DATABASE Perform a mysqldump of the production site database and import it into the dev server. If this is the final migration, be sure to put the production site in a frozen site or maintenance mode beforehand. Example below: # On production server mysqldump prod_database | gzip > prod_database.sql.gz scp prod_database.sql.gz wbrlabs@wbrlabs.com: # scp file to dev server rm prod_database.sql.gz # Clean up # On dev server mysqladmin create prod_database gunzip prod_database.sql.gz mysql prod_database < prod_database.sql rm prod_database.sql # Clean up The production db snapshot requires access using the dev site's db connection. 4. EDIT CONFIG FILE WITH AUTO-INCREMENT VALUES Examine the production database snapshot and determine the auto-increment values for each table listed in the config.ini file. Consider the current site's age, acceleration of produced content, and the estimated date of launch of the new site in order to gauge appropriate values. Don't be afraid to add plenty of padding. The whole purpose of this is to prevent from encountering conflicts on sequenced IDs (they are a huge huge pain). You only get one chance to get this right, so be conservative and bump the number as high as you see fit. Enter the auto-increment values and the production snapshot DB name in the config.ini file. This file already contains default values for the auto-increments, but these values will vary between sites. 5. INITIALIZE THE DEV SITE Initialize the dev site by running drush. drush -l <site-moniker>.wbrdev.com php-script import.drush.php init This should be done soon after provisioning the site and before any content is input into the site. This step should only be performed once. Make sure the config.ini is configured correctly before doing this. PERFORMING THE MIGRATION ------------------------ After following the steps in the setup phase, you will be ready to perform a migration. The basic procedure goes: 1. COPY THE PRODUCTION DATABASE TO THE DEV SERVER This is the same as STEP 3 in the setup phase. 2. RUN THE IMPORT COMMAND FROM THE DRUSH SCRIPT The import command inserts or replaces data for the most common Drupal tables. See the corresponding __import() function. drush -l <site-moniker>.wbrdev.com php-script import.drush.php import 3. RUN ALL PROCESS COMMANDS FROM THE DRUSH SCRIPT There will usually be additional actions to perform on the imported content. A typical example is to append underscores to all user email addresses has a clever way to prevent rogue emails being sent from the dev server. drush -l <site-moniker>.wbrdev.com php-script import.drush.php process drush -l <site-moniker>.wbrdev.com php-script import.drush.php process_1 ... drush -l <site-moniker>.wbrdev.com php-script import.drush.php process_N In the above example, there are multiple process commands. There is no naming convention for these, so it's up to you how to name them. All command names correspond to identical function names that have 2 prepended underscores. See the process-example.inc file. 4. WRITE CODE FOR ACTIONS ON IMPORTED DATA It is essential to capture any changes as code and encapsulate them in a function. The idea here to make everything repeatable so you can easily replay the changes when you perform another migration. Failure to do so means any changes will be lost when it comes time to do the final sync. You will gradually add code to the process.inc file as needed. You can choose to put all code in the single __process() function, or you may break it up into smaller meaningful functions. You'll need to run the drush php-script for each function you add. Function names should begin with 2 underscores. See the process-example.inc file. MISCELLANEOUS ------------- The physical files for the production site should be preserved and copied to the new site during launch. cd /NAS1/websites/drupal6x/sites/<newsite> cp -pR /NAS1/websites/drupal5x/sites/<oldsite>/files/* files/ MORE INFORMATION ---------------- Documentation is available at https://docs.01detail.com/node/2026