Reading another site's database

When you move content from an old Drupal site into a new one, Drupal's migration tools need to read the old site's database while running inside the new site. Both sites are already here, side by side, so the only thing missing is permission for one to read the other. That is what the Migration source task does.

You set it on the new site — the one you are building — and you point it at the old site. Nothing is copied and nothing on the old site changes. The new site simply gains the ability to read, and you take that ability away again when you are finished.

Setting it

Open the new site in your control panel, find Migration source among its tasks, and pick the old site from the list. Within a couple of minutes the new site can read the old site's database.

The list only offers sites you are allowed to pick, so there is nothing to get wrong. It shows your own sites, currently enabled, on the same database server as the site you are setting this on. It never offers the site itself, and it never offers your Ægir control panel. The one exception is the site you already picked: it stays in the list even after you disable it, shown with (disabled) beside its name, so opening this dialog and saving again never quietly drops the access you still rely on.

If the list is empty, you have no other site that qualifies.

Using it

The old site's database arrives as a second database connection named migrate. That is the name Drupal's migration tooling expects, so with the migration modules enabled you can run the upgrade from your own shell against the new site. Modern Drupal is driven with the site's own bundled Drush, so the ground rules from Drush basics apply: run Unlock Local Drush on the new site's platform, connect as your oN.ftp user, and cd into the platform root before these:

vdrush @your-site.example.com migrate:upgrade --legacy-db-key=migrate --legacy-root=/path/to/old/platform/root --configure-only
vdrush @your-site.example.com migrate:import --group=migrate_drupal_7 --continue-on-failure

--legacy-root is the old site's platform root — the directory holding its index.php, not its files directory. The full crossing, with the review step between those two commands and the gotchas either side of them, is what Migrating a Drupal 7 site to Drupal CMS walks through — treat this pair as proof the migrate key works, and that page as the way to run it.

Drupal CMS platforms built here already carry those migration modules, so there is nothing to fetch first — you only need to enable them on the site. On other platforms you add them to the codebase yourself the usual way, with Composer, before enabling them.

One thing to know before you start: this serves the command line path. Drupal's browser-based upgrade screen asks you to type database credentials into its own form and does not use a named connection, so setting this task does not fill that form in for you. The browser route still works, you just enter the details by hand there.

What access it actually gives

Worth being precise about, because it is your data on both ends.

The new site can read the whole of the old site's database. It cannot write to it, change it or drop anything — the permission granted is read-only, and the database server itself enforces that, so a mistake in a migration script cannot damage the source.

The access covers that entire source database, not a chosen part of it. It stays in place until you remove it. And it is only ever between two of your own sites in the same account; there is no way to point this at anyone else's site, or at your control panel.

Removing it

Set Migration source back to - None: remove access -. Within a couple of minutes the permission is withdrawn and the new site can no longer read the old database.

It is good practice to do this once the migration is finished. There is no harm in leaving it while you are still working.

Things that surprise people

Disabling the old site does not remove the access. Disabling takes a site off the web, but its database is still there and still readable by the new site. That is deliberate — you may well disable the old site at cutover while you are still finishing the migration. If you want the access gone, remove it here, or delete the old site.

Deleting the old site removes it for you. Once the source is gone there is nothing to read, and the permission is withdrawn automatically.

Cloning the new site does not carry it over. A clone gets its own fresh database account, so it starts with no access to anything. If you want the clone to read the old site too, set the task on the clone.

Renaming the new site, or moving it to another platform, keeps it. It is still the same site, so the wiring follows it. Moving it to a different database server does not — a grant cannot span servers, so the access is dropped, and you set it again on the new server if both sites end up there.

Restoring the new site from a backup keeps it. A restore gives the site a new database account behind the scenes, and the access is re-established for you shortly afterwards. Restoring the old site keeps it too, by a longer route — allow a few extra minutes before the migrate connection works again.

Disabling the new site hides this task but keeps the access. The task is only offered on enabled sites, so disabling the new site leaves the access in place while the control to remove it is not there. Re-enable the site to set it back to None, or ask your host.

If either site moves to a different account or database server, the access is removed — and it is not restored if the move is undone. Set the task again.

If you set it and nothing happens

Give it a couple of minutes, then check the simplest thing: connect to your oN.ftp shell and try the connection from the new site (same vdrush ground rules as above):

vdrush @your-site.example.com sql:query --database=migrate "SELECT 1"

If that fails, the access was not established. The usual reasons are that the source is no longer one of your sites (deleted, or moved to another account), that the two sites are not on the same database server, that the new site is no longer on a Drupal 8 or newer platform, or that the source cannot prove the database it claims is its own — the system checks that by opening the database with the credentials the source records for itself, so stale or hand-edited site credentials fail it.

The system retries for a while and then stops rather than trying forever, so an access that never worked will stay not working until you act. Set Migration source back to - None: remove access -, then set it again; if it still does not take, ask your host, who can see exactly which check refused it in the task log.

If it is not offered

The task appears only on sites running Drupal 8 or newer. On older sites it is hidden on purpose: adding a second database connection to a Drupal 7 site changes a value Drupal 7 derives from its database settings, which would invalidate every outstanding one-time login and password-reset link and any form a visitor had open — and change it back again when the wiring is removed. Since you migrate from Drupal 7 rather than into it, this costs you nothing in practice.

If the task is missing on a site you expected it on, check that the site is enabled and that it really is Drupal 8 or newer. If it still does not appear, ask your host — BOA switches the feature on automatically whenever an instance is installed or upgraded, so an instance that has not been upgraded in a while may not have it yet.