www.aleph1.co.uk Git - yaffs-website/blob - web/modules/contrib/migrate_upgrade/README.txt

   1 The migrate_upgrade module provides drush support for performing upgrades from
   2 previous versions of Drupal to Drupal 8. It implements two drush commands:
   3
   4 * migrate-upgrade - performs a complete import of the source site's congiuration
   5 and content into the target Drupal 8 site. Optionally, with the --configure-only
   6 flag, it may create migration configurations for such an import without actually
   7 running them, to permit customization of the import process.
   8
   9 * migrate-upgrade-rollback - removes content and certain configuration
  10 previously imported either by the migrate-upgrade command or by the core
  11 upgrade UI.
  12
  13 migrate-upgrade
  14 ===============
  15 The upgrade command requires a Drupal 6-style database URL of the source site's
  16 database, and the location of the source site's public files.
  17
  18 drush migrate-upgrade --legacy-db-url=mysql://user:pw@127.0.0.1/d6db --legacy-root=http://example.com
  19
  20 The --legacy-root option may be either the domain of your existing Drupal site
  21 (with the public files pulled by HTTP), or a local file directory into which you
  22 have copied the files directory from your source site.
  23
  24 If your source site used a database prefix for all tables, you may specify the
  25 prefix with --legacy-db-prefix. Migration from sites with partial or mixed
  26 prefixing is not supported. Note that if the source site is stored in a Postgres
  27 schema, you must set the prefix to the schema with a period appended (e.g.,
  28 --legacy-db-prefix=drupal.).
  29
  30 The migrate-upgrade command, like the core upgrade UI, is designed to be run on
  31 a freshly installed and empty Drupal 8 site (where the only site configuration
  32 that has been done is enabling any modules for which you wish to migrate data).
  33
  34 migrate-upgrade-rollback
  35 ========================
  36
  37 The rollback command has no arguments or options:
  38
  39 drush migrate-upgrade-rollback
  40
  41 If it detects that an upgrade has been performed, either by migrate-upgrade or
  42 by the core UI, it removes all content imported via the migration process (it
  43 identifies the upgrade by the presence of the migrate_drupal_ui.performed state
  44 key). In addition, any configuration entites created by the migration process
  45 (such as content type and field definitions) are also removed. Because simple
  46 configuration settings (such as the site title) are generally modified rather
  47 than created by the upgrade process, and the original values are not preserved,
  48 those changes are not rolled back. To completely return to the previous state,
  49 you need to restore the site from backup, or reinstall a fresh empty site.
  50
  51 migrate-upgrade --configure-only
  52 ================================
  53 At the time of this release, tools have not yet been developed (along the lines
  54 of the migrate_d2d_ui module under Drupal 7) for customizing Drupal-to-Drupal
  55 migrations in Drupal 8. For now, the best option short of doing custom
  56 development is to use the --configure-only option on migrate-upgrade to replace
  57 the actual execution of the migrations with export of their configuration to
  58 configuration entities, which can then be modified as needed for a particular
  59 migration scenario. A suggested workflow:
  60
  61 1. Install a fresh empty D8 site, enabling all modules for which you wish to
  62    migrate data.
  63 2. Run the drush migrate-upgrade command with the --configure-only option. This
  64    generates migration configuration entities in the D8 database (config table).
  65 3. Create a custom module containing only a .info.yml file (with dependencies on
  66    migrate_plus and migrate_drupal) and a config/install directory.
  67 4. Export your site configuration, e.g. drush cex --destination=/tmp/export
  68 5. Copy the migration configuration that was generated by migrate-upgrade into
  69    the custom module - be sure *not* to copy the default group configuration,
  70    which is defined by migrate_plus:
  71     cp /tmp/export/migrate_plus.migration.* /tmp/export/migrate_plus.migration_group.migrate_*.yml migrate_custom/config/install/
  72 6. Look at that migrate_plus.migration_group.* file - you'll see your database
  73    configuration captured there. In most cases, what you'll want to do is define
  74    your database connection in settings.php with those credentials under the key
  75    that is configured there - you won't want to commit the credentials to your
  76    git repo.
  77 7. Edit the generated .yml files to reflect your custom migration path.
  78 8. Reinstall D8, enable your custom module and migrate_tools, and proceed to
  79    work with your Drupal migrations as you would with any custom migration.
  80    Hint: you'll probably want config_devel so you can edit .yml files in
  81    config/install and immediately test your changes.
  82
  83 Note that the configuration entities generated above need to be prefixed to
  84 avoid conflict with the core migration plugins they originated from. For
  85 example, by default the core d6_user plugin generates the upgrade_d6_user
  86 configuration entity. You may modify the 'upgrade_' prefix by providing a
  87 --migration-prefix option.