Skip to main content
Version: v1

Drush

The Drush website describes the tool as follows:

Drush is a command line shell and Unix scripting interface for Drupal. Drush core ships with lots of useful commands and generators. Similarly, it runs update.php, executes SQL queries, runs content migrations, and misc utilities like cron or cache rebuild. Drush can be extended by 3rd party commandfiles.

Vortex uses Drush wherever it talks to Drupal, from the provisioning scripts to the Behat tests. This page is for developers who run Drush against their local site or a Lagoon environment. It shows how to run Drush in the stack, what the shipped configuration changes and how to reach a Lagoon environment through its site alias.

All the standard Drush commands work, and Vortex adds shorthand commands for the most common tasks:

  • ahoy fetch-db - fetch the database dump from the source that VORTEX_FETCH_DB_SOURCE sets, such as a URL or a hosting environment
  • ahoy import-db - import the database dump into the local environment
  • ahoy provision - import the database dump or install from a profile, then run database updates, the configuration import, cache rebuilds and deploy hooks

Usage​

Run Drush inside the cli container, where the DATABASE_* variables point it at the stack's database service:

ahoy drush <command>

ahoy drush also passes -l ${LOCALDEV_URL}, so the links Drush generates, such as the one-time login link from ahoy drush uli, point at your local site.

Configuration​

The shipped Drush configuration lives in the drush/ directory:

PHP runtime configuration​

Edit drush/php-ini/drush.ini to change PHP runtime settings for PHP CLI processes, Drush commands included. Any valid PHP ini directive works there.

PHP finds the file through the PHP_INI_SCAN_DIR environment variable, which Vortex sets in the CLI container image (.docker/cli.dockerfile) and in the Acquia provision hook (hooks/library/provision.sh). Every PHP CLI process with this scan path loads the file, Drush included. The php container that serves web requests doesn't get the scan path. For web requests, set PHP directives in .docker/config/php/custom.ini. See PHP configuration.

The CLI image and the Acquia hook both append the directory to PHP_INI_SCAN_DIR after a colon. The colon keeps the directories PHP already scans: the existing value, or PHP's default scan directory when the variable is empty. On Acquia, the hosting provider's own PHP ini overrides, such as sendmail_path, stay in effect.

Locally, a change to drush.ini applies to the next PHP process without a rebuild. The project directory is mounted at /app, and PHP reads the scan directory each time a process starts. In CI and on Lagoon, the image build copies the project into /app instead of mounting it, so a change there applies from the next build.

To confirm that PHP loads the file, list the ini files it reads, which include /app/drush/php-ini/drush.ini, or print the memory limit in effect:

# List the ini files that PHP loads
ahoy cli php --ini
# Print the memory limit in effect
ahoy cli "php -i | grep memory_limit"

Memory limit​

The shipped configuration sets the PHP memory limit higher than the platform default, which is 400M in the Lagoon images:

; drush/php-ini/drush.ini
memory_limit = 1G

This value is sized for database imports and configuration synchronization on large sites. It applies to PHP CLI processes that load this scan path, Drush included, but web requests keep their own memory limit.

If a Drush command exhausts this limit, profile the command before you raise the value. An exhausted 1G limit usually points to a memory leak in custom code. Raising the limit hides the leak until a larger dataset reaches the new limit.

To give a single command more memory, run Drush's PHP entry point, vendor/bin/drush.php, through php -d. Pass drush.php, because vendor/bin/drush is a shell wrapper and handing it to php prints the script instead of running Drush:

ahoy cli php -d memory_limit=2G vendor/bin/drush.php <command>

Aliases​

For Lagoon hosting, the shipped drush/sites/lagoon.site.yml file defines a wildcard alias, so every environment resolves as @lagoon.<branch-or-pr> with no per-environment entries. You can use the aliases from your host machine or from inside the container.

Drush doesn't load variables from .env files, so the project name is hardcoded in the alias file. The hardcoded project name makes the aliases work the same on the host and in the container. The project name appears in 2 lines:

  • The user: value, your_site-${env-name} in the template
  • The uri: value

If you change LAGOON_PROJECT in .env, update both lines to match.

The file also hardcodes these details of the Lagoon cluster:

  • The SSH host in host:
  • The SSH port in the -p option of ssh.options
  • The route domain at the end of uri:

If your project runs on another Lagoon cluster, replace them with that cluster's values.

To run a Drush command against a Lagoon environment, follow the steps in the tab that matches how you run Drush:

  1. Make sure your SSH key is loaded in your ssh-agent:
ssh-add ~/.ssh/path/to/key
  1. Run Drush commands using the Lagoon site aliases:
# Show status of the develop environment
drush @lagoon.develop status
# SSH into the web container of the PR-123 environment
drush @lagoon.pr-123 ssh

Confirm that the alias works by running the status command in the tab that matches how you run Drush. The command prints the status of the develop environment, including its Drupal version. On the host, the command runs the project's Drush from vendor/bin, so it needs PHP installed on your machine:

./vendor/bin/drush @lagoon.develop status