Drall: A Tool to Run Drush on Multi-site Drupal Installations

In mid 2021, I started working in a cool Montréal-based agency named Symetris where my first project happened to be a multi-site Drupal 8 installation with over 200 websites. Later, I was assigned many other multi-site projects and I noticed that they all faced a common problem:

How to execute Drush commands on all sites in a multi-site Drupal installation?

Since I love writing CLI tools, I answered this question by writing Drall – a tool built with Symfony Console that helps with running Drush commands on multi-site Drupal installations.

2 minute version

• Drall helps run Drush on multi-site Drupal installations.
  • One command to Drush them all.
• Install Drall with composer require jigarius/drall.
• Run drall list and drall help to get started.
• Run Drush commands on all sites like:
  • drall exec:drush core:status.
  • drall exec:drush @@site.dev core:status.
• Run non-drush commands like:
  • drall exec:shell ls web/sites/@@uri/files.
• Run commands on site groups with --drall-group=GROUP.
  • Site groups must first be defined.
• For more documentation, read the rest of the article.
• You can support/sponsor Drall on GitHub.

Video tutorial

Installation

Drall can be installed with composer, either globally or in a specific project.

# System-wide (global) installation.
composer global require jigarius/drall
# Project-specific installation.
composer require jigarius/drall

Note: To run drall from anywhere in the terminal, you need to add composer’s vendor/bin directory to your system’s PATH variable.

Usage

Drall offers a number of commands to simplify working with multi-site Drupal installations. Here’s a list of drall commands that you might find useful.

exec:drush

This command allows you to execute a Drush command on:

• All sites.
• A pre-defined site group.
• A custom list of sites (coming soon).

There are a number of ways in which you can to use this command.

With @@uri

In this method, the --uri option is sent to Drush.

$ drall exec:drush --uri=@@uri core:status
# Equivalent to running the following Drush commands.
drush --uri=site-1 core:status
drush --uri=site-2 core:status
...
drush --uri=site-n core:status

Or simply omit the --uri=@@uri and Drall adds it automatically, unless you’ve included @@site in the command, which is discussed next.

With @@site

In this method, the @@site part represents the various site aliases you have configured for Drush.

$ drall exec:drush @@site.prod core:status
# Equivalent to running the following Drush commands.
drush @site-1.prod core:status
drush @site-2.prod core:status
...
drush @site-n.prod core:status

site:directories

The site directories command lists all directories referred to in Drupal’s sites.php. Say, your sites.php looks as follows.

$sites[
  'site-1.com' => 'site-1',
  'site-2.com' => 'site-2',
  // ...
  'site-n.com' => 'site-n',
];

With drall site:directories, you can get a list of the site directory names.

$ drall site:directories
site-1
site-2
...
site-n

You can then use in scripts to do fancy stuff.

for site in $(drall site:directories)
do
  echo "Working on $site";
  // Do something with $site.
done;

exec:shell

More often than not, we need to run multiple commands on each site in a multi-site Drupal installation. For example,

• Put a site in maintenance mode.
• Execute the drush deploy command on the site.
• Put the site out of maintenance mode.

Or maybe simply execute a non-drush command on each site. The exec:shell added in v2.x command attempts to solve this problem.

$ drall exec:shell "mkdir -p web/sites/@@uri/private && drush --uri=@@uri core:rebuild"

site:aliases

The site aliases command lists all site aliases defined in your Drupal project. Say, you have the following site aliases defined:

# In your Drupal project root. Usually one level above index.php.
drush
└── sites
    ├── site1.site.yml
    ├── site2.site.yml
    ├── ...
    └── siten.site.yml

Say, each of these files defines 2 aliases each for 2 environments: dev, prod. With drall site:aliases, you can get a list of all aliases.

$ drall site:aliases
@site1.dev
@site1.prod
@site2.dev
@site2.prod
...
@siten.dev
@siten.prod

This behavior is also provided by the drush site:alias command.

Site groups

This is one Drall feature that I really find useful, especially when dealing with a huge number of Drupal sites in a single multi-site installation. Drall allows you to define site groups and then use the --drall-group=GROUP option to run commands on specific site groups. Here’s how you can define site groups for Drall.

With site aliases

If you’re using site aliases in your project, you can assign site aliases to one or more groups by adding a drall.groups key.

# File: tnmt.site.yml
local:
  root: /opt/drupal/web
  # ...
  drall:
    groups:
      - group1
      - group2

With this in place, you can run Drush commands on all group1 sites like this:

$ drall exec:drush --drall-group=group1 deploy

With sites.*.php files

If you’re not using Drush site aliases, you can still assign your sites to groups by creating sites.*.php files in Drupal’s sites directory. For example,

web/sites/
|-- sites.group1.php
|-- sites.group2.php
|-- ...
|-- sites.php

Each of these files define a $sites variable just like the sites.php file. You can then run Drush commands on all group1 sites like this:

$ drall exec:drush --drall-group=group1 cron

Conclusion

By allowing us to run Drush on all or multiple sites, Drall does help a lot in multi-site Drupal installations. It can easily be installed with composer and it is fairly easy to use.

Next steps

• Use Drall on your next multi-site Drupal project.
• Visit and star the Drall repository on GitHub.
• Visit symetris.ca – the company that sponsored Drall’s initial development.