Skip to main content
Version: v2

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, deploy steps, 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 that sees this scan path loads the file, not only Drush. Vortex doesn't set it for the appserver container that serves web requests. For web requests, set PHP directives in .docker/config/php/custom.ini. See PHP configuration.

Both places add the directory after a colon instead of replacing PHP_INI_SCAN_DIR. The colon keeps the directories PHP already scans: an existing PHP_INI_SCAN_DIR value, or PHP's default scan directory when the variable starts out empty. That way, on Acquia, the hosting provider's own PHP ini overrides (such as sendmail_path) aren't lost.

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, no host directory is mounted. The image build copies the project into /app, 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, including Drush, and doesn't change the memory limit used to serve web requests.

If a Drush command exhausts this limit, profile the command before raising the value. An exhausted 1G limit usually points to a memory leak in custom code rather than a limit set too low. Raising the ceiling hides the leak until a larger dataset reaches the new limit.

To give a single command more memory without changing the default, run Drush's PHP entry point, vendor/bin/drush.php, through php -d. 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> without per-environment entries. You can use the aliases from your host machine or from inside the container.

The project name is hardcoded in the alias file because Drush doesn't load variables from .env files. The hardcoded name keeps the aliases working identically on the host and in the container. It appears in 2 lines: the user: value (your_site-${env-name} in the template) and the uri: value. If you change LAGOON_PROJECT in .env, update both lines to match.

The file also hardcodes the details of the Lagoon cluster: the SSH host in host:, the SSH port in the -p option of ssh.options, and 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. It 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