PHPackages                             spatie/laravel-queued-db-cleanup - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. spatie/laravel-queued-db-cleanup

ActiveLibrary[Database & ORM](/categories/database)

spatie/laravel-queued-db-cleanup
================================

Safely delete large numbers of records

1.6.0(4mo ago)80399.4k↓51.6%111MITPHPPHP ^8.2CI passing

Since Sep 24Pushed 4mo ago3 watchersCompare

[ Source](https://github.com/spatie/laravel-queued-db-cleanup)[ Packagist](https://packagist.org/packages/spatie/laravel-queued-db-cleanup)[ Docs](https://github.com/spatie/laravel-queued-db-cleanup)[ GitHub Sponsors](https://github.com/spatie)[ RSS](/packages/spatie-laravel-queued-db-cleanup/feed)WikiDiscussions main Synced 4d ago

READMEChangelog (10)Dependencies (6)Versions (18)Used By (1)

Safely delete large numbers of records
======================================

[](#safely-delete-large-numbers-of-records)

[![Latest Version on Packagist](https://camo.githubusercontent.com/4c892f9d9bc493552c2f52f8566138ddc8db4190accf750d4c859b3fd2d14ca2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7370617469652f6c61726176656c2d7175657565642d64622d636c65616e75702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/spatie/laravel-queued-db-cleanup)[![Tests](https://github.com/spatie/laravel-queued-db-cleanup/workflows/Tests/badge.svg)](https://github.com/spatie/laravel-queued-db-cleanup/workflows/Tests/badge.svg)[![Total Downloads](https://camo.githubusercontent.com/f51dd4a151f5eaf94a9d3b254a428637cad8e5282dfb0e547fb496688cf8107f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7370617469652f6c61726176656c2d7175657565642d64622d636c65616e75702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/spatie/laravel-queued-db-cleanup)

Deleting many database records in one go using Laravel has a few pitfalls you need to be aware of:

- deleting records is possibly a slow operation that can take a long time,
- the delete query will acquire many row locks and possible lock your entire table, other queries will need to wait
- even when managing query execution and cleanup, there's a fixed maximum execution time in a serverless environment

The pitfalls are described in more detail in [this post](https://flareapp.io/blog/7-how-to-safely-delete-records-in-massive-tables-on-aws-using-laravel) on the [Flare blog](https://flareapp.io/).

This package offers a solution to safely delete many records in large tables. Here's an example:

```
Spatie\LaravelQueuedDbCleanup\CleanDatabaseJobFactory::new()
    ->query(YourModel::query()->where('created_at', 'query(YourModel::query()->where('created_at', 'deleteChunkSize(10)
    ->stopWhen(function (Spatie\LaravelQueuedDbCleanup\CleanConfig $config) {
        return $config->pass === 3;
    })
    ->dispatch();
```

`stopWhen` receives an instance of `Spatie\LaravelQueuedDbCleanup\CleanConfig`. It contains these properties to determine whether the cleanup should be stopped:

- `pass`: contains the number of times the cleanup job was started for this particular cleanup.
- `rowsDeletedInThisPass`: the number of rows deleted in this pass
- `totalRowsDeleted`: the total of number of rows deleted by in all passes.

### Using the batch to stop the cleanup process

[](#using-the-batch-to-stop-the-cleanup-process)

You can use the batch id to stop the cleanup process

```
$batch = CleanDatabaseJobFactory::forQuery(YourModel::query())
    ->deleteChunkSize(10)
    ->getBatch();

// you could store this batch id somewhere
$batchId = $batch->id;

$batch->dispatch();
```

Somewhere else in your codebase you could retrieve the stored batch id and use it to cancel the batch, stopping the cleanup process.

```
\Illuminate\Support\Facades\Bus::findBatch($batchId)->cancel();
```

Events
------

[](#events)

You can listen for these events. They all have one public property, `cleanConfig`, which is an instance of `Spatie\LaravelQueuedDbCleanup\CleanConfig`.

### Spatie\\LaravelQueuedDbCleanup\\Events\\CleanDatabasePassStarting

[](#spatielaravelqueueddbcleanupeventscleandatabasepassstarting)

Fired when a new pass starts in the cleanup process.

### Spatie\\LaravelQueuedDbCleanup\\Events\\CleanDatabasePassCompleted

[](#spatielaravelqueueddbcleanupeventscleandatabasepasscompleted)

Fired when a pass has been completed in the cleanup process.

### Spatie\\LaravelQueuedDbCleanup\\Events\\CleanDatabaseCompleted

[](#spatielaravelqueueddbcleanupeventscleandatabasecompleted)

Fired when the entire cleanup process has been completed.

Testing
-------

[](#testing)

```
composer test
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](https://github.com/spatie/.github/blob/main/CONTRIBUTING.md) for details.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [Freek Van der Herten](https://github.com/freekmurze)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

61

—

FairBetter than 98% of packages

Maintenance76

Regular maintenance activity

Popularity50

Moderate usage in the ecosystem

Community25

Small or concentrated contributor base

Maturity76

Established project with proven stability

 Bus Factor1

Top contributor holds 73.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~123 days

Recently: every ~238 days

Total

17

Last Release

131d ago

Major Versions

0.0.1 → 1.0.02020-09-25

PHP version history (3 changes)0.0.1PHP ^7.4

1.1.1PHP ^7.4|^8.0

1.4.0PHP ^8.2

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/7535935?v=4)[Spatie](/maintainers/spatie)[@spatie](https://github.com/spatie)

---

Top Contributors

[![freekmurze](https://avatars.githubusercontent.com/u/483853?v=4)](https://github.com/freekmurze "freekmurze (133 commits)")[![laravel-shift](https://avatars.githubusercontent.com/u/15991828?v=4)](https://github.com/laravel-shift "laravel-shift (8 commits)")[![AdrianMrn](https://avatars.githubusercontent.com/u/12762044?v=4)](https://github.com/AdrianMrn "AdrianMrn (6 commits)")[![Plytas](https://avatars.githubusercontent.com/u/17316322?v=4)](https://github.com/Plytas "Plytas (6 commits)")[![Nielsvanpach](https://avatars.githubusercontent.com/u/10651054?v=4)](https://github.com/Nielsvanpach "Nielsvanpach (4 commits)")[![AlexVanderbist](https://avatars.githubusercontent.com/u/6287961?v=4)](https://github.com/AlexVanderbist "AlexVanderbist (4 commits)")[![grantjanecek](https://avatars.githubusercontent.com/u/17169721?v=4)](https://github.com/grantjanecek "grantjanecek (3 commits)")[![dmason30](https://avatars.githubusercontent.com/u/20278756?v=4)](https://github.com/dmason30 "dmason30 (3 commits)")[![rubenvanassche](https://avatars.githubusercontent.com/u/619804?v=4)](https://github.com/rubenvanassche "rubenvanassche (3 commits)")[![spekulatius](https://avatars.githubusercontent.com/u/8433587?v=4)](https://github.com/spekulatius "spekulatius (3 commits)")[![telkins](https://avatars.githubusercontent.com/u/53731?v=4)](https://github.com/telkins "telkins (2 commits)")[![Gummibeer](https://avatars.githubusercontent.com/u/6187884?v=4)](https://github.com/Gummibeer "Gummibeer (2 commits)")[![petar-djuric](https://avatars.githubusercontent.com/u/49185208?v=4)](https://github.com/petar-djuric "petar-djuric (1 commits)")[![mbardelmeijer](https://avatars.githubusercontent.com/u/1583095?v=4)](https://github.com/mbardelmeijer "mbardelmeijer (1 commits)")[![0xflotus](https://avatars.githubusercontent.com/u/26602940?v=4)](https://github.com/0xflotus "0xflotus (1 commits)")

---

Tags

cleanupmyselfspatieeloquentdeletevaporlaravel-queued-db-cleanup

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/spatie-laravel-queued-db-cleanup/health.svg)

```
[![Health](https://phpackages.com/badges/spatie-laravel-queued-db-cleanup/health.svg)](https://phpackages.com/packages/spatie-laravel-queued-db-cleanup)
```

###  Alternatives

[illuminate/database

The Illuminate Database package.

2.8k54.9M11.7k](/packages/illuminate-database)[laravel/ai

The official AI SDK for Laravel.

1.0k3.2M203](/packages/laravel-ai)[spatie/laravel-backup

A Laravel package to backup your application

6.0k24.4M245](/packages/spatie-laravel-backup)[spatie/laravel-health

Monitor the health of a Laravel application

87512.0M167](/packages/spatie-laravel-health)[illuminate/queue

The Illuminate Queue package.

21332.6M1.6k](/packages/illuminate-queue)[backpack/crud

Quickly build admin interfaces using Laravel, Bootstrap and JavaScript.

3.4k3.7M223](/packages/backpack-crud)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)