Skip to main content
Blue Moose logo Blue Moose Field notes
← All articles
code

Drupal Batch API: re-save 12,000 nodes safely

Laptop with code on screen

Last month I had to re-save about 12,000 nodes after changing how a computed field gets filled. My first attempt was a foreach over Node::loadMultiple() in a Drush script. It ran for a few minutes, then died on the PHP memory limit with the entity cache still holding every node I had touched. The fix is the Batch API, and the part that makes it work is a small detail in how you write the operation callback.

The operation: a cursor, not an offset

A batch operation is a callable that PHP invokes repeatedly until it sets $context['finished'] to 1. Between calls, the state in $context['sandbox'] survives. I key the sandbox on the last processed node ID rather than an offset. If a save changes which rows match your query, an offset skips or repeats rows, while a nid > $last cursor stays correct.

<?php

namespace Drupal\example\Batch;

use Drupal\Core\Entity\EntityTypeManagerInterface;

final class RetitleBatch {

  public const CHUNK = 50;

  public static function process(string $bundle, array &$context): void {
    $storage = \Drupal::entityTypeManager()->getStorage('node');

    if (!isset($context['sandbox']['last'])) {
      $context['sandbox']['last'] = 0;
      $context['sandbox']['done'] = 0;
      $context['sandbox']['total'] = (int) $storage->getQuery()
        ->accessCheck(FALSE)
        ->condition('type', $bundle)
        ->count()
        ->execute();
      $context['results']['updated'] = 0;
    }

    $nids = $storage->getQuery()
      ->accessCheck(FALSE)
      ->condition('type', $bundle)
      ->condition('nid', $context['sandbox']['last'], '>')
      ->sort('nid')
      ->range(0, self::CHUNK)
      ->execute();

    foreach ($storage->loadMultiple($nids) as $node) {
      $node->setNewRevision(FALSE);
      $node->save();
      $context['results']['updated']++;
    }

    $storage->resetCache($nids);

    $context['sandbox']['last'] = $nids ? max($nids) : $context['sandbox']['last'];
    $context['sandbox']['done'] += count($nids);
    $context['message'] = t('Processed @done of @total nodes', [
      '@done' => $context['sandbox']['done'],
      '@total' => $context['sandbox']['total'],
    ]);
    $context['finished'] = $nids
      ? min(1, $context['sandbox']['done'] / max(1, $context['sandbox']['total']))
      : 1;
  }

}

Three details matter here. accessCheck(FALSE) is required on entity queries in current Drupal, and for a maintenance job it is the correct value. loadMultiple() issues one query for the whole chunk instead of 50. And resetCache($nids) is what stops memory from growing: without it, the static entity cache keeps every loaded node for the length of the request.

Wiring it up with BatchBuilder

\Drupal\Core\Batch\BatchBuilder gives you a fluent way to assemble the batch definition instead of a hand-written nested array. I checked its public methods against core: setTitle(), setInitMessage(), setFinishCallback(), addOperation() and toArray() are all there. Here it is inside a Drush command:

<?php

namespace Drupal\example\Drush\Commands;

use Drupal\Core\Batch\BatchBuilder;
use Drupal\example\Batch\RetitleBatch;
use Drush\Attributes as CLI;
use Drush\Commands\DrushCommands;

final class RetitleCommands extends DrushCommands {

  #[CLI\Command(name: 'example:retitle')]
  #[CLI\Argument(name: 'bundle', description: 'Node bundle to re-save.')]
  public function retitle(string $bundle = 'article'): void {
    $batch = (new BatchBuilder())
      ->setTitle('Re-saving nodes')
      ->setInitMessage('Starting...')
      ->setFinishCallback([self::class, 'finished'])
      ->addOperation([RetitleBatch::class, 'process'], [$bundle]);

    batch_set($batch->toArray());
    drush_backend_batch_process();
  }

  public static function finished(bool $success, array $results, array $operations): void {
    $message = $success
      ? sprintf('Updated %d nodes.', $results['updated'] ?? 0)
      : 'The batch hit an error and stopped early.';
    \Drupal::logger('example')->notice($message);
  }

}

The same batch_set() call works from a form submit handler, where Drupal drives the batch through its progress page. Only the last line changes: under Drush you call drush_backend_batch_process() yourself.

Gotchas I'd flag

Operation arguments get serialized between requests, so pass scalars such as the bundle string, never an entity or a service object. Keep per-call work small: 50 saves is fine, but if each save triggers a slow hook, drop CHUNK to 10. Put expensive setup in the isset($context['sandbox']) branch so it runs once, not on every call.

Also be honest about when not to use this. If the work is async and can happen later, a queue worker is the better tool because failures retry on their own. A batch is for one-off or admin-triggered jobs where you want a progress readout and a clear finish. For the 12,000-node re-save it ran flat in memory and finished without me babysitting it. I haven't run this exact listing, so check it against your Drush version before trusting it.

BM
Blue Moose
The moose behind Blue Moose. Full-stack PHP developer — Drupal by day, Symfony by night, tests always.