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 ls web/sites/@@uri/files.
• For more documentation, read the rest of the article.
• If you find Drall useful, consider making a small donation on GitHub.

Installation

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

# In the Drupal project directory.
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

This command allows you to execute a Drush or a shell command command on:

• All sites in the Drupal installation.
• A pre-defined site group.
• A list of sites matching a certain filter.

There are a number of ways in which you can to use this command. In general, drall exec works by replacing one of the pre-defined placeholders (discussed below) to generate and execute commands targeting each site in the Drupal installation.

With @@dir

In this method, @@dir is replaced with the values of the $sites array.

$ drall exec drush --uri=@@dir 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=@@dir and Drall adds it automatically for drush commands, unless you’ve included @@site in the command, which is discussed next.

With @@key

In this method, @@key is replaced with the keys of the $sites array. These keys usually represent the domain at which the site can be accessed and is useful for use with commands like drush uli.

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

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

For a Drush alias like @foo.ENV, @@site will only take the @foo part of the alias.

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;

site:keys

The site keys command lists all keys (usually hostnames) 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:keys, you can get a list of the site URIs.

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

You can then use in scripts to do fancy stuff.

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

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

Site filters

If you want to run a command only on sites that match a certain criteria, you can use --drall-filter to filter placeholder values with an expression.

# Run only on the "leo" site.
drall exec --drall-filter=leo drush core:status
# Run only on "leo" and "ralph" sites.
drall exec --drall-filter="leo||ralph" drush core:status

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.
• Read detailed documentation on the Drall repository on GitHub.
• Visit and star the Drall repository on GitHub.
• Visit symetris.ca – the company that sponsored Drall’s initial development.