Drupal Batch API: re-save 12,000 nodes safely
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.