X-Git-Url: http://www.aleph1.co.uk/gitweb/?a=blobdiff_plain;f=web%2Fmodules%2Fcontrib%2Fmigrate_upgrade%2FREADME.txt;fp=web%2Fmodules%2Fcontrib%2Fmigrate_upgrade%2FREADME.txt;h=70a94656be81775307395a247609e6b3f1dc5587;hb=a2bd1bf0c2c1f1a17d188f4dc0726a45494cefae;hp=0000000000000000000000000000000000000000;hpb=57c063afa3f66b07c4bbddc2d6129a96d90f0aad;p=yaffs-website diff --git a/web/modules/contrib/migrate_upgrade/README.txt b/web/modules/contrib/migrate_upgrade/README.txt new file mode 100644 index 000000000..70a94656b --- /dev/null +++ b/web/modules/contrib/migrate_upgrade/README.txt @@ -0,0 +1,87 @@ +The migrate_upgrade module provides drush support for performing upgrades from +previous versions of Drupal to Drupal 8. It implements two drush commands: + +* migrate-upgrade - performs a complete import of the source site's congiuration +and content into the target Drupal 8 site. Optionally, with the --configure-only +flag, it may create migration configurations for such an import without actually +running them, to permit customization of the import process. + +* migrate-upgrade-rollback - removes content and certain configuration +previously imported either by the migrate-upgrade command or by the core +upgrade UI. + +migrate-upgrade +=============== +The upgrade command requires a Drupal 6-style database URL of the source site's +database, and the location of the source site's public files. + +drush migrate-upgrade --legacy-db-url=mysql://user:pw@127.0.0.1/d6db --legacy-root=http://example.com + +The --legacy-root option may be either the domain of your existing Drupal site +(with the public files pulled by HTTP), or a local file directory into which you +have copied the files directory from your source site. + +If your source site used a database prefix for all tables, you may specify the +prefix with --legacy-db-prefix. Migration from sites with partial or mixed +prefixing is not supported. Note that if the source site is stored in a Postgres +schema, you must set the prefix to the schema with a period appended (e.g., +--legacy-db-prefix=drupal.). + +The migrate-upgrade command, like the core upgrade UI, is designed to be run on +a freshly installed and empty Drupal 8 site (where the only site configuration +that has been done is enabling any modules for which you wish to migrate data). + +migrate-upgrade-rollback +======================== + +The rollback command has no arguments or options: + +drush migrate-upgrade-rollback + +If it detects that an upgrade has been performed, either by migrate-upgrade or +by the core UI, it removes all content imported via the migration process (it +identifies the upgrade by the presence of the migrate_drupal_ui.performed state +key). In addition, any configuration entites created by the migration process +(such as content type and field definitions) are also removed. Because simple +configuration settings (such as the site title) are generally modified rather +than created by the upgrade process, and the original values are not preserved, +those changes are not rolled back. To completely return to the previous state, +you need to restore the site from backup, or reinstall a fresh empty site. + +migrate-upgrade --configure-only +================================ +At the time of this release, tools have not yet been developed (along the lines +of the migrate_d2d_ui module under Drupal 7) for customizing Drupal-to-Drupal +migrations in Drupal 8. For now, the best option short of doing custom +development is to use the --configure-only option on migrate-upgrade to replace +the actual execution of the migrations with export of their configuration to +configuration entities, which can then be modified as needed for a particular +migration scenario. A suggested workflow: + +1. Install a fresh empty D8 site, enabling all modules for which you wish to + migrate data. +2. Run the drush migrate-upgrade command with the --configure-only option. This + generates migration configuration entities in the D8 database (config table). +3. Create a custom module containing only a .info.yml file (with dependencies on + migrate_plus and migrate_drupal) and a config/install directory. +4. Export your site configuration, e.g. drush cex --destination=/tmp/export +5. Copy the migration configuration that was generated by migrate-upgrade into + the custom module - be sure *not* to copy the default group configuration, + which is defined by migrate_plus: + cp /tmp/export/migrate_plus.migration.* /tmp/export/migrate_plus.migration_group.migrate_*.yml migrate_custom/config/install/ +6. Look at that migrate_plus.migration_group.* file - you'll see your database + configuration captured there. In most cases, what you'll want to do is define + your database connection in settings.php with those credentials under the key + that is configured there - you won't want to commit the credentials to your + git repo. +7. Edit the generated .yml files to reflect your custom migration path. +8. Reinstall D8, enable your custom module and migrate_tools, and proceed to + work with your Drupal migrations as you would with any custom migration. + Hint: you'll probably want config_devel so you can edit .yml files in + config/install and immediately test your changes. + +Note that the configuration entities generated above need to be prefixed to +avoid conflict with the core migration plugins they originated from. For +example, by default the core d6_user plugin generates the upgrade_d6_user +configuration entity. You may modify the 'upgrade_' prefix by providing a +--migration-prefix option.