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 thatVORTEX_FETCH_DB_SOURCEsets, such as a URL or a hosting environmentahoy import-db- import the database dump into the local environmentahoy 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
- Docker Compose
ahoy drush <command>
docker compose exec cli 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:
drush/drush.ymlpasses--disable-sslto thesql:*commands (sql:cli,sql:query,sql:dump,sql:drop,sql:create) and tosite:install. The database commands then connect to the stack's database service without TLS. The file also adds--no-tablespacestosql:dumpand lists the production site aliases. See Production guard.drush/Listeners/ProductionGuardListener.phpregisters the production guard, whose logic ships indrevops/vortex-tooling. See Production guard.drush/sites/lagoon.site.ymldefines the site aliases for Lagoon-hosted environments. See Aliases.drush/php-ini/drush.iniadjusts the PHP runtime for CLI processes. See PHP runtime configuration.
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:
- Ahoy
- Docker Compose
# List the ini files that PHP loads
ahoy cli php --ini
# Print the memory limit in effect
ahoy cli "php -i | grep memory_limit"
# List the ini files that PHP loads
docker compose exec cli php --ini
# Print the memory limit in effect
docker compose exec cli bash -c "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
- Docker Compose
ahoy cli php -d memory_limit=2G vendor/bin/drush.php <command>
docker compose exec 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
-poption ofssh.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:
- Host
- Ahoy
- Docker Compose
- Make sure your SSH key is loaded in your
ssh-agent:
ssh-add ~/.ssh/path/to/key
- 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
- Make sure your SSH key is loaded into
pygmy:
pygmy addkey --key ~/.ssh/path/to/key
- Run Drush commands using the Lagoon site aliases:
# Show status of the develop environment
ahoy drush @lagoon.develop status
# SSH into the web container of the PR-123 environment
ahoy drush @lagoon.pr-123 ssh
- Make sure your SSH key is loaded into
pygmy:
pygmy addkey --key ~/.ssh/path/to/key
- Run Drush commands using the Lagoon site aliases:
# Show status of the develop environment
docker compose exec cli drush @lagoon.develop status
# SSH into the web container of the PR-123 environment
docker compose exec cli 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:
- Host
- Ahoy
- Docker Compose
./vendor/bin/drush @lagoon.develop status
ahoy drush @lagoon.develop status
docker compose exec cli drush @lagoon.develop status
Production guard
Vortex blocks 4 destructive Drush commands when they target a
production site alias. A mistyped drush sql:sync @self @prod then fails
before it overwrites the production database. The following table lists
the guarded commands and the alias the guard checks for each one:
| Command | Alias the guard checks |
|---|---|
sql:sync | The target, such as @prod in drush sql:sync @self @prod |
core:rsync | The target, such as @prod in drush core:rsync @self:%files @prod:%files |
sql:drop | The selected site, such as @prod in drush @prod sql:drop |
site:install | The selected site, such as @prod in drush @prod site:install |
A blocked command stops before Drush connects to the site, and Drush prints this error:
[error] Refusing to run sql:drop against the production site alias @prod. Set VORTEX_DRUSH_PRODUCTION_GUARD_SKIP=1 to bypass this guard.
The guard checks the alias where you type the command. A command you run on
the production server itself, such as after drush @prod ssh, targets no
alias, so the guard lets it run.
Production aliases
drush/drush.yml lists the production aliases under
vortex.production_aliases:
vortex:
production_aliases:
- prod
An entry matches the alias with that name and every alias whose environment
has that name. The prod entry matches @prod, @self.prod and
@lagoon.prod. It doesn't match @production. An entry with a site name,
such as lagoon.main, matches only that alias.
On Lagoon, the alias of the production environment is
@lagoon.<branch>, where <branch> is the value of
VORTEX_LAGOON_PRODUCTION_BRANCH. With the default main branch, add
lagoon.main to the list:
vortex:
production_aliases:
- prod
- lagoon.main
Bypass the guard
To run a guarded command against production on purpose, set
VORTEX_DRUSH_PRODUCTION_GUARD_SKIP to 1 for that command. Drush prints a
warning that names the variable, then runs the command:
- Host
- Ahoy
- Docker Compose
VORTEX_DRUSH_PRODUCTION_GUARD_SKIP=1 drush @prod sql:drop
VORTEX_DRUSH_PRODUCTION_GUARD_SKIP=1 ahoy drush @prod sql:drop
docker compose exec -e VORTEX_DRUSH_PRODUCTION_GUARD_SKIP=1 cli \
drush @prod sql:drop
Set the variable on the command line only. An export in your shell turns
off the guard for every command that follows.
Change the guard
The guard's logic lives in the
DrevOps\VortexTooling\Drush\ProductionGuardListener class of
drevops/vortex-tooling, so tooling updates bring fixes to your project.
Drush finds the guard through drush/Listeners/ProductionGuardListener.php,
which extends that class and adds nothing else. With a tooling version that
doesn't ship the class, the file declares nothing and the guard stays off
until you update drevops/vortex-tooling.
To change a rule for your project, override the matching method in
drush/Listeners/ProductionGuardListener.php. For example, to also guard
sql:create against the selected site:
use Symfony\Component\Console\Input\InputInterface;
#[AsEventListener(priority: 100)]
class ProductionGuardListener extends VortexProductionGuardListener {
protected function resolveTargetAliases(string $command, InputInterface $input): array {
if ($command === 'sql:create') {
return [$this->siteAliasManager()->getSelf()->name()];
}
return parent::resolveTargetAliases($command, $input);
}
}
Keep the #[AsEventListener(priority: 100)] line. Drush registers the guard
only when the class in drush/Listeners/ declares it, and the priority runs
the guard before core:rsync connects to the target.