Moving to Drupal 12 also means updating Drush. Drush 13 does not support Drupal 12, and the Drush 14 branch has been abandoned and will not be released. Drush 15 is the supported path forward.

Drush 15 makes many of its commands available through dr, Drupal core's command line application. The drush entrypoint is gone, so commands like drush deploy and drush updatedb become dr deploy and dr updatedb. Some commands have been dropped, including site:install.

Community member Gabor Hojtsy is also working on Drush 15 compatibility checks in the Upgrade Status module. The goal is to help site owners assess which of their Drush commands already have dr counterparts and provide links to a porting guide for commands that need updating.

We use site:install in our Drupal starter template at Velir to get a new DDEV site running locally and install a bare site in CI for testing.

Core's dr install only supports SQLite, and both environments use MySQL. I needed a replacement that could handle both.

How Drush did it

Drush does not implement Drupal's installer. It builds an array of settings and passes it to install_drupal() in core/includes/install.core.inc. That array supplies the install profile, database connection, site details, and admin account.

A standalone PHP script can call the same installer.

The install script

The script lives at scripts/install-site.php, outside the web root, and refuses to run unless PHP_SAPI is cli. Our template uses docroot as the web root. If your project uses web, adjust the chdir() path in the PHP script below.

<?php

/**
 * @file
 * Installs Drupal from the command line, as drush site:install did.
 *
 * Drush 15 has no site:install, and core's dr install only installs to
 * SQLite. This calls core's installer the same way Drush 13 did.
 *
 * Usage:
 *   php scripts/install-site.php [profile] [--existing-config] [--check]
 *     [--site-name=NAME] [--site-mail=MAIL]
 *     [--account-name=NAME] [--account-mail=MAIL]
 *     [--locale=LANGCODE]
 *
 * The database comes from settings.php, as it does in DDEV, or from a
 * DB_URL environment variable, as it does in CI. It is never an argument,
 * so its password stays out of the process list and shell history. The
 * profile defaults to standard, or with --existing-config, to the profile
 * in the exported configuration. The account password is random and never
 * shown. --check validates the arguments and exits without installing.
 */

use Drupal\Core\Config\FileStorage;
use Drupal\Core\Database\Database;
use Drupal\Core\Site\Settings;

if (PHP_SAPI !== 'cli') {
  exit(1);
}

$class_loader = require __DIR__ . '/../vendor/autoload.php';
chdir(__DIR__ . '/../docroot');
require_once 'core/includes/install.core.inc';

$options = [
  'existing-config' => FALSE,
  'check' => FALSE,
  'site-name' => 'Drupal',
  'site-mail' => 'admin@example.invalid',
  'account-name' => 'admin',
  'account-mail' => 'admin@example.invalid',
  'locale' => 'en',
];
$profile = NULL;

foreach (array_slice($argv, 1) as $arg) {
  if (str_starts_with($arg, '-') && !str_starts_with($arg, '--')) {
    fwrite(STDERR, "Unknown option $arg\n");
    exit(1);
  }

  if (!str_starts_with($arg, '--')) {
    $profile = $arg;
    continue;
  }

  [$name, $value] = array_pad(explode('=', substr($arg, 2), 2), 2, NULL);

  if (!array_key_exists($name, $options)) {
    fwrite(STDERR, "Unknown option --$name\n");
    exit(1);
  }

  if (is_bool($options[$name])) {
    if ($value !== NULL) {
      fwrite(STDERR, "--$name takes no value.\n");
      exit(1);
    }

    $options[$name] = TRUE;
    continue;
  }

  if ($value === NULL || $value === '') {
    fwrite(STDERR, "--$name needs a value, like --$name=VALUE.\n");
    exit(1);
  }

  $options[$name] = $value;
}

if ($profile === NULL && $options['existing-config']) {
  Settings::initialize(getcwd(), 'sites/default', $class_loader);
  $sync = Settings::get('config_sync_directory');
  $extension = $sync ? (new FileStorage($sync))->read('core.extension') : FALSE;

  if (empty($extension['profile'])) {
    fwrite(STDERR, "No profile found in the exported configuration. Name one.\n");
    exit(1);
  }

  $profile = $extension['profile'];
}

$profile ??= 'standard';

$found = preg_match('/^[a-z0-9_]+$/', $profile) && (
  is_file("core/profiles/$profile/$profile.info.yml")
  || glob("profiles/{,*/}$profile/$profile.info.yml", GLOB_BRACE)
);

if (!$found) {
  fwrite(STDERR, "No install profile named $profile.\n");
  exit(1);
}

if ($options['check']) {
  echo "Ready to install the $profile profile.\n";
  exit(0);
}

$pass = bin2hex(random_bytes(12));

$settings = [
  'parameters' => [
    'profile' => $profile,
    'langcode' => $options['locale'],
    'existing_config' => (bool) $options['existing-config'],
  ],
  'forms' => [
    'install_configure_form' => [
      'site_name' => $options['site-name'],
      'site_mail' => $options['site-mail'],
      'account' => [
        'name' => $options['account-name'],
        'mail' => $options['account-mail'],
        'pass' => ['pass1' => $pass, 'pass2' => $pass],
      ],
    ],
  ],
];

$db_url = getenv('DB_URL');

if ($db_url) {
  if (!is_file('sites/default/settings.php')) {
    copy('sites/default/default.settings.php', 'sites/default/settings.php');
  }

  $database = Database::convertDbUrlToConnectionInfo($db_url, FALSE);
  $settings['forms']['install_settings_form'] = [
    'driver' => $database['namespace'],
    $database['namespace'] => $database,
  ];
}

install_drupal($class_loader, $settings);

echo "Installed Drupal with the {$settings['parameters']['profile']} profile.\n";

A few parts of it are worth explaining.

After the CLI check, the next three lines set the stage the same way core's install.php does. It loads Composer's autoloader, changes into the docroot (the installer resolves paths like sites/default relative to the current directory), and pulls in install.core.inc so install_drupal() exists.

I kept the options we use in our projects: the install profile, existing configuration, site details, admin account, and language. The database connection is not an option; it comes from settings.php or the environment, as described below. Options that take a value must use --name=value with a nonempty value. --existing-config and --check are flags and take no value. Unknown options, including single-dash arguments like -l, are rejected instead of being mistaken for a profile name. The DDEV wrapper handles -y and --yes itself before calling the PHP script.

--existing-config needed a little more work. When you install from existing configuration, Drupal has to use the same install profile the configuration was exported from, or the install fails. Drush looked that up for you, so the script does too. It initializes Drupal's settings, finds the config_sync_directory, and reads the profile out of the exported core.extension.yml. You can still name a profile yourself and it will use that instead.

Core cannot install a profile with a hook_install() from configuration, and standard has one. Sites that install from configuration need to use minimal or a custom profile that supports it.

The admin password is always random and never printed. There is no --account-pass option, so a password cannot end up in shell history or the process list through an install argument. Use dr uli for a one-time login link after installation, then dr user:password to set a password afterward.

Lastly, the database connection comes from settings.php unless the DB_URL environment variable is set. DDEV writes its connection into settings.ddev.php for you. In CI there is no settings.php yet, so we supply DB_URL. The script copies default.settings.php into place, turns the URL into a connection array with core's own Database::convertDbUrlToConnectionInfo(), and hands it to the installer as the values for the database form. The installer then writes the connection into settings.php, the same as it would after the web installer. There is no --db-url option; the URL is read from the environment rather than passed in the process arguments.

Wrapping it in a DDEV command

Running ddev exec php /var/www/html/scripts/install-site.php works, but nobody is going to remember that. DDEV lets you add your own commands by dropping a script into .ddev/commands/web, so I added .ddev/commands/web/install-site to expose it as ddev install-site:

#!/usr/bin/env bash

## Description: Install Drupal into the DDEV database, as drush site:install did
## Usage: install-site [profile] [-y] [--existing-config] [--check] [--site-name=NAME] [--account-name=NAME] [--account-mail=MAIL] [--locale=LANGCODE]
## Example: "ddev install-site" or "ddev install-site minimal -y" or "ddev install-site --existing-config"
## ExecRaw: true

set -eu

# The database dropped below is always DDEV's, so the install must be too.
unset DB_URL

script=/var/www/html/scripts/install-site.php
yes=false
check=false
args=()

for arg in "$@"; do
  case "$arg" in
    -y|--yes) yes=true ;;
    --check) check=true ;;
    *) args+=("$arg") ;;
  esac
done

if [ "$check" = true ]; then
  exec php "$script" --check "${args[@]}"
fi

php "$script" --check "${args[@]}" > /dev/null

if [ -n "$(mysql -N -e 'SHOW TABLES' | head -n 1)" ]; then
  if [ "$yes" != true ]; then
    read -r -p "The database already has tables. Drop them all and install? [y/N] " answer

    case "$answer" in
      y|Y|yes) ;;
      *) echo "Cancelled."; exit 1 ;;
    esac
  fi

  mysql -e 'DROP DATABASE db; CREATE DATABASE db'
fi

php "$script" "${args[@]}"

echo "Log in with a one-time link from: ddev exec dr uli --url=${DDEV_PRIMARY_URL}"

The ## comments at the top are how DDEV knows what to show in ddev help install-site, and ExecRaw passes the arguments through to the script exactly as you typed them.

The main thing this command adds on top of the PHP script is the part of site:install I relied on most without thinking about it: wiping the database first. Drupal's installer won't install over an existing site, and Drush used to drop the tables for you after asking. This does the same thing. If the database has any tables, it asks before dropping them, and -y skips the question, just like it did in Drush. Dropping and recreating the whole db database is simpler than dropping tables one at a time, and in DDEV that database belongs to this project and nothing else.

Before checking or dropping any tables, the wrapper runs the PHP script with --check. That validates the arguments, resolves the profile from existing configuration when needed, and checks that the profile name is valid and its .info.yml file exists. A typo like -l or an unknown profile stops the command before deletion. This checks arguments and profile availability; it does not run Drupal's installation checks.

The wrapper also unsets DB_URL, so the environment cannot redirect the install away from DDEV's database while the wrapper drops the local one. You can run ddev install-site minimal --check yourself to check the arguments and profile without changing the database.

Now it works the way everyone on the team is used to:

ddev install-site
ddev install-site minimal --site-name="My site"
ddev install-site --existing-config -y

Once the site is installed, use dr uli to generate a one-time login link for uid 1, the default account for that command. In DDEV, run:

ddev exec 'dr uli --url=$DDEV_PRIMARY_URL'

dr does not read the site URL that DDEV sets for Drush, so without --url the link points at http://localhost instead of your DDEV site. The single quotes make $DDEV_PRIMARY_URL expand inside the container, where DDEV sets it. The ddev install-site command prints this command with your site's URL filled in when it finishes.

Open the link in your browser to log in. To set a password afterward, use dr user:password:

ddev exec dr user:password admin 'your-new-password'

Replace your-new-password with the password you want to use. If you installed with --account-name, use that account name instead of admin.

Using it in CI

In CI, we use the same script to install a bare Drupal site into the MySQL service container before running our tests. Our GitHub Actions test job used to run drush site:install minimal -y --db-url=.... That step is now:

- name: Install Drupal
  env:
    DB_URL: ${{ env.SIMPLETEST_DB }}
  run: php scripts/install-site.php minimal

The database is empty on every run, so there is nothing to drop and no confirmation to skip. DB_URL receives the MySQL connection URL from SIMPLETEST_DB, which is already configured for PHPUnit. The settings.php written during installation stays on the Test job's runner. It is not cached, committed, or deployed; the Deploy job builds from a fresh checkout.

The deploy builds also remove docroot/core/install.php, the web installer entrypoint. The standalone script calls install_drupal() through install.core.inc, so it does not depend on that entrypoint.

A word of caution

This script calls install_drupal() directly, the same as Drush 13 did. If a future Drupal release changes the installer's settings array, the script may need updating. It also assumes a single site in sites/default. If you run a multisite, you will need to teach it which site directory to use.

If dr install gains the options we need, I will happily delete this script. For now, it gives us a command we can use in DDEV and CI to install Drupal into MySQL.