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(2mo ago)81355.6k↑39.9%111MITPHPPHP ^8.2CI passing

Since Sep 24Pushed 2mo 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 1mo 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

62

—

FairBetter than 99% of packages

Maintenance83

Actively maintained with recent releases

Popularity51

Moderate usage in the ecosystem

Community25

Small or concentrated contributor base

Maturity75

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

84d 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

[spatie/laravel-backup

A Laravel package to backup your application

6.0k21.8M191](/packages/spatie-laravel-backup)[spatie/laravel-translatable

A trait to make an Eloquent model hold translations

2.4k23.0M413](/packages/spatie-laravel-translatable)[silber/bouncer

Eloquent roles and abilities.

3.6k4.4M25](/packages/silber-bouncer)[watson/validating

Eloquent model validating trait.

9723.3M47](/packages/watson-validating)[dyrynda/laravel-model-uuid

This package allows you to easily work with UUIDs in your Laravel models.

4802.8M8](/packages/dyrynda-laravel-model-uuid)[spatie/laravel-model-flags

Add flags to Eloquent models

4301.1M1](/packages/spatie-laravel-model-flags)

PHPackages © 2026

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