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