Drupal: Drush

drush cr is the command that is run after nearly every change of code, YAML or a library definition. It rebuilds the service container, discovers again every hook implementation, route, plugin and Twig template, and empties the render, page and dynamic page caches (see Performance and caching).

Source: Drush: cache:rebuild

The sibling commands are cache:get, cache:set, cache:clear and cache:tags for working on one cache bin or invalidating one tag, and cache:warm (see drush deploy). Pitfalls: drush cr is also the way to recover from a fatal error caused by a stale container after a module was removed from disk. A rebuild on a busy production site makes the next requests slow and can cause a stampede, so it belongs in the deployment sequence and not in a loop.

The configuration commands move settings between the active configuration (in the database) and the sync directory (YAML files in the Git repository). The detailed workflow, config_sync_directory, Config Split and the safe import rules are in Configuration management; the commands themselves:

Source: Drush: config:export, Drush: config:import, Drush: config:get and Drush: config:set

Details worth knowing:

Source: Drush: config:set

Other commands of the same group are config:status (the differences between the active configuration and the directory, the quick "is the repository in sync" check), config:delete, config:edit and config:pull (copy the configuration of another site to the local sync directory).

drush updatedb (alias updb) is the command line version of update.php. It runs the pending hook_update_N() functions and post-update functions of every module and, by default, clears caches afterwards (--no-cache-clear suppresses that). Since Drush 13.7.2 the documentation states that updatedb puts the site into maintenance mode while it runs. drush updatedb:status lists what is pending without running it, which is what a pipeline can use to decide whether a deployment needs a maintenance window.

Source: Drush: updatedb

The usual order after new code is deployed is: updatedb, then config:import, then cache:rebuild, which is exactly the sequence of drush deploy.

drush deploy (Drush 10.3 and later) exists so that nobody has to remember that order. After the deployment script has updated the code (git pull or a new image, and composer install --no-dev), one command makes the site match the new code. According to the official "Deploy command for Drupal" topic it runs, in order:

The three kinds of update function run in this order within one deployment: hook_update_N() first (low-level schema and data changes, where the full API is not available), then hook_post_update_NAME() (still before the configuration import), and finally hook_deploy_NAME(), a Drush-specific hook that runs after the configuration import, when the new fields, vocabularies and permissions already exist. That makes a deploy hook the correct place to create content or fill a new field that the imported configuration introduced, which neither of the Drupal hooks can rely on.

A deploy hook lives in a file called MODULE.deploy.php in the module folder, and its function name is MODULE_deploy_NAME(). The hook receives a $sandbox array and can return a status message; to process a large amount of data, it sets $sandbox['#finished'] to a value below 1 until it is done, and Drush calls it again, in the same way as an update function. For the Meridian Museum, a new on_display field is added to collection_object by configuration, and a deploy hook fills it for the objects that have a gallery:

Source: Drush: Deploy command for Drupal

Drush records which deploy hooks have run, so each runs once per database. drush deploy:hook-status lists the pending ones and drush deploy:mark-complete marks them all as done without running them, which is used when a hook has already been applied by hand. A deploy hook that is skipped because the site was deployed with separate updatedb, config:import and cache:rebuild commands is the most common surprise: use drush deploy, not three commands, in every environment.

Options of the individual steps are configured in drush.yml (for example command.config.import.options), because drush deploy itself takes only the global options.

drush uli prints a one-time login link and, unless --no-browser is given, opens it in the default browser. It is how the administrator of a new site gets in, and how a lost password is recovered without email.

Source: Drush: user:login

With no option the link is for user 1, and an optional path argument is where the user lands after login. Pitfalls: a link that points to http://default/... means the URI was not supplied (use --uri, an alias or DRUSH_OPTIONS_URI); the link works once, and a second use or a link older than the expiry shows "You have tried to use a one-time login link that has either been used or is no longer valid"; and the output is a credential, so it must never be pasted into a ticket or chat.

Source: Drush: pm:install and Drush: pm:uninstall

pm:install installs the dependencies listed in the module’s info.yml and enables the module; it does not download it. Downloading is Composer’s job (composer require drupal/webform); the drush dl and drush pm-download commands of Drush 8 no longer exist. The module list is a comma-separated or space-separated list. pm:uninstall refuses to remove a module whose configuration or content other modules depend on, and the --simulate option shows what would be uninstalled first. Because the enabled modules are stored in core.extension, installing a module also changes the exported configuration, so config:export follows it. The older drush dis (pm-disable) disappeared with Drupal 8 because Drupal has no disabled state, only installed and uninstalled.

The commands that export, open and replace the database are described with their backup and restore workflows in Backups and disaster recovery. In short:

Source: Drush: sql:dump, Drush: sql:cli and Drush: sql:sync

sql:sync SOURCE TARGET dumps the source database, copies the dump (by rsync) and imports it into the target, replacing what is there. It therefore needs both aliases to be reachable, and the target is destroyed without a second prompt when -y is given. Options include --no-dump and --no-sync to reuse an existing dump, --create-db, the table lists --skip-tables-list, --structure-tables-list and --tables-list, and the matching ...-key options that pick a list from configuration. For a restore, $(drush sql:connect) < dump.sql is more efficient than piping into sql:cli.

If the dblog module is enabled, Drupal writes its log to the database, and Drush reads it without a browser (see Logging, status report and troubleshooting).

Source: Drush: watchdog:show

watchdog:show (aliases ws, wd-show) prints the last 10 entries by default, takes an optional substring, and offers --count, --severity, --severity-min, --type, --extended, --fields, --field and --filter. watchdog:tail follows the log as new entries arrive, watchdog:show-one ID prints one entry in full, and watchdog:delete empties or trims the table. On a site that writes the log to syslog or a file (the syslog module, Monolog) these commands see nothing.

The State system holds values that belong to one environment and are not configuration: the last cron time, the maintenance flag, the Twig debug switches. Drush reads and writes it, including keys no screen shows:

Source: Drush: state:set

The value is stored as it is typed according to --input-format (string, integer, float, boolean, json, yaml or the default auto), and - reads it from standard input, for a JSON array for instance. The Twig and cache switches shown are the Drupal 10.1 and later way to enable Twig debug, auto reload and disabled render caches without development.services.yml (see Twig templates and debugging). The same switch is in settings.php in the environments that should always have it.

Maintenance mode is stored in State too (system.maintenance_mode), but there is a dedicated command:

The core:cron reference suggests the form drush maint:status && drush core:cron so that cron does not run while the site is in maintenance mode, which would poison caches.

Source: Drush: user:create and Drush: role:perm:add

user:create (alias ucrt) takes the account name, --mail and --password and can print chosen fields; user:role:add and user:role:remove assign roles. role:perm:add (alias rap) takes the role’s machine name and a comma-separated list of permission names (the exact label strings, as in drush role:list), so a typo gives an error that the permission does not exist. Security notes: a password given on the command line is stored in the shell history and visible in the process list, so pass it from a variable or a secret manager, or create the user without a password and send a drush uli link; permissions granted this way change configuration, which means the next config:import from a branch that does not contain it removes them again (see Users, roles and permissions and Access control and permissions in code).

Source: Drush: core:cron and Drush: queue:run

drush cron runs the same service as the cron URL and Automated Cron, but in a command-line PHP process with no web server time limit. queue:run NAME processes one queue and stops when the queue is empty or at --time-limit (seconds), --items-limit or when the worker throws SuspendQueueException; --lease-time is how long an item stays claimed before another runner can take it. A worker that has no cron key in its definition is processed only by this command. Scheduling Drush with system cron, systemd timers and Kubernetes CronJobs is in Cron, queues and maintenance, and the worker and the meridian:sync command are in Queue, Batch and Cron APIs. In containers, see Kubernetes Jobs and CronJobs for how to run a command such as drush cron on a schedule.

drush recipe PATH (the alias of recipe:apply) applies a recipe to the installed site, equivalent to php core/scripts/drupal recipe PATH:

Source: Drush: recipe:apply

The argument is the folder of the recipe, and --input=RECIPE.INPUT=VALUE passes a value to the recipe or to one of its dependencies. Recipes are explained, including inputs and config actions, in Drupal Recipes. A recipe has no update path: it is applied once, its result is configuration, and that configuration is exported afterwards with drush cex.

drush generate (alias gen) asks questions and writes the skeleton of a module, plugin, service, form, test or Drush command. Since Drush 12 the generators are part of Drush, not a separate Drupal Code Generator package, and the generator command lists them all.

Source: Drush: generate

The generators are grouped: module, theme, controller, hook, field, single-directory-component; plugin:* (block, field formatter/type/widget, queue worker, filter, condition, constraint, REST resource, Views plugins); service:* (event subscriber, access checker, logger, middleware, Twig extension, …​); entity:* (entity:content, entity:configuration, entity:bundle-class); form:*; test:* (unit, kernel, browser, webdriver, nightwatch); yml:* (routing, services, libraries, permissions, links); and drush:* (drush:command, drush:symfony-command, drush:generator, drush:alias-file). The options are --answer (answer a question non-interactively; repeat for each), --destination, --working-dir, --dry-run and --replace. A generator is a starting point, not a template to trust blindly: check that the output uses attributes and dependency injection, that its coding style matches the standards (see Coding standards and static analysis), and that older generator output copied from a book matches today’s conventions. Drupal 10 Development Cookbook (2023) uses drush generate to create custom entities; the command is still right, but the plugins and hooks it produces are the attribute and object-oriented-hook forms in Drupal 11 (see Plugin API and attributes and Hooks and object-oriented hooks).

Source: Drush: php:eval

php:eval (aliases eval, ev) runs a PHP snippet with the site bootstrapped and prints the return value with var_dump by default (--format changes it). It is the quickest way to call a service. For anything with complicated shell quoting use php:script FILE, which runs a file instead. Both run with full privileges as user 0, bypass access checks, and may change production data, so they are for investigation and one-off repair; a repeatable change belongs in an update function or deploy hook.

status shows, among other things, the Drupal and PHP versions, the database driver and connection status, the Drush version and configuration files, the install profile, the paths of modules, themes and files, the configuration sync directory and the bootstrap level reached. When a command fails, the value of bootstrap (Successful or empty) tells whether Drush could reach the database at all. core:requirements prints the Status report from the command line, which is suitable for a monitoring probe (see Logging, status report and troubleshooting).

Aliases are YAML files called NAME.site.yml. The place Drush looks first, and the one to use for a project, is drush/sites/ in the project (next to composer.json). A file called self.site.yml is special: it defines the environments of the current site, and they are addressed as @self.ENV, or just @ENV when no other alias file uses the name. A file called meridian.site.yml defines @meridian.ENV. Other directories, such as ~/.drush/sites or /etc/drush/sites, are searched only when listed in drush.yml; Drush does not search directories recursively, so every folder must be listed.

Source: Drush: Site aliases

The keys:

Usage:

A site specification is an alias given inline: drush deploy@www.meridian.example/var/www/meridian/current/web#www.meridian.example core:status has the form user@host/path#uri. Environment variables can be used anywhere in a Drush configuration file as ${env.NAME}, for instance user: ${env.MERIDIAN_DEPLOY_USER}, which keeps account names out of the repository.

An alias can reach a site that is inside a container or a pod instead of behind SSH. The Docker transport runs Drush with docker compose exec, and the Kubernetes transport with kubectl exec:

Source: Drush: Site aliases

With these, drush @self.ci status executes docker compose exec web ... and drush @self.prod-k8s cron executes in the named pod without an SSH server in the image. See Compose in practice and kubectl essentials for the container side, and Docker and containers for the Drupal images. For a kubectl alias the deployment pipeline usually has the kubeconfig as a secret and not in the alias file; the kubeconfig and entrypoint keys exist for the cases where it must be named.

A top-level key of '*' is a wildcard environment, and ${env-name} is replaced with the name used on the command line:

With it drush @preview.pr-412 status addresses a pull-request preview without an alias per branch. The documentation warns that a wildcard matches any name, typos included, so a mistyped @preview.pr-41 tries to connect to a host that does not exist (or to a wrong one); use an alias-alter policy file if that needs reporting.

@self is the current site, which is what sql:sync @prod @self copies into. Common problems: an alias that works for status but not deploy because the remote Drush is not installed or is a different version; root that points to the Git checkout and not to the web folder; a missing uri, giving http://default in links; and SSH asking for a password or host-key confirmation, which hangs in CI (use keys, a known-hosts file and ssh.tty: false).

Drush has used several styles over the years, and a lot of online material (including the books above) shows the old ones:

The Drush 13.7.0 release notes say that annotated commands are deprecated and that support for them will be removed in a future release, and that core commands move to native Symfony Console commands in 14.x. The page "Writing Drush commands" of the 13.x documentation lists Symfony Console commands as the recommended style and the attribute-annotated and docblock-annotated styles as deprecated. A new command should therefore be a Console command when the project requires Drush 13.7 or later (declare "conflict": {"drush/drush": "<13.7"} in the module’s composer.json), and an attribute command when it must also run on Drush 12 or on 13.0 to 13.6. Both are shown below.

What no longer exists is the file drush.services.yml. Up to Drush 11 a module declared its commands in it; Drush 12 deprecated the file and Drush 13 removed it, so the official pages describe only two ways to inject dependencies in 13: AutowireTrait and a static create() method. A drush.services.yml left in a module is not read by Drush 13 and should be deleted when the module is upgraded. Drupal 10 Development Cookbook (2023) shows the drush.services.yml plus @command annotation form; the drush.services.yml part of it works only up to Drush 12.

Commands of a symlinked Composer package (a path repository) are not found automatically; add the package path to drush.yml while developing. After adding a class, run drush cr, because the command list is cached. If the command is still missing, run drush list and then drush -vvv COMMAND, which prints service-instantiation errors such as a constructor argument that cannot be autowired.

The command meridian:sync-status reports how many collection objects wait in the synchronisation queue:

Source: Drush: Writing commands and Drush: Dependency injection

Points to notice:

The older style puts everything on a method. It is the style of the meridian:sync command on the queue page, and it is the one that runs on every Drush from 12 to 14. This command lists the objects on display in a gallery, in any output format:

Source: Drush: Writing commands

Reading this class:

Source: Drush: Writing commands

A Drush command is tested with a Kernel test of its service (the logic belongs in a service such as the CollectionSyncPlanner of the queue page, so it can be tested without Drush) and, where the command itself needs a test, with Drush’s own DrushTestTrait from the drush/drush package, which executes the command and returns its output (see Automated testing). Keep a command thin: parse the input, call a service, format the output.

Commands are also the building block of automation. The Meridian Museum deployment script is the sequence

and its details, including the CI/CD pipeline, are in Deployment and CI/CD.